start-vibing-stacks 2.16.0 → 2.18.0

package/stacks/php/skills/mariadb-octane/SKILL.md

@@ -1,12 +1,91 @@
 ---
 name: mariadb-octane
-version: 1.0.0
+version: 2.0.0
+description: "MariaDB patterns for Laravel Octane (long-lived workers) targeting MariaDB 11.8 LTS (released 2025, supported until June 2028). Octane-safe connection config (PERSISTENT + EMULATE_PREPARES off + STRICT_TRANS_TABLES + utf8mb4 default in 11.8), automatic flush on request boundary, Octane::tick health probes, MariaDB 11.8 features (VECTOR data type + VEC_DISTANCE_*, JSON Schema validation, system-versioned temporal tables, TIMESTAMP range to 2106, PARSEC auth plugin, parallel mariadb-dump), strict migrations with explicit lengths, composite/covering indexes, cursor pagination, transaction safety in workers, immutable_datetime casts. Invoke for any query, migration, model, or DB config in Laravel Octane."
 ---
 
-# MariaDB + Octane — Database Patterns for Persistent Workers
+# MariaDB + Octane — Database Patterns (MariaDB 11.8 LTS, 2026)
 
 **ALWAYS invoke when writing queries, migrations, models, or DB config in Laravel Octane.**
 
+## MariaDB 11.8 LTS — what changed (release Jun 2025; LTS until Jun 2028)
+
+MariaDB 11.8 supersedes 11.4 LTS. Adopt for new projects; plan migration for existing.
+
+| Feature | Why it matters |
+|---|---|
+| **Default charset is now `utf8mb4`** (was `latin1` for ~20 years) | New tables don't need explicit charset; old tables stay as-is until ALTERed |
+| **Native `VECTOR` type + `VEC_DISTANCE_COSINE` / `VEC_DISTANCE_EUCLIDEAN`** | Embeddings + similarity search in the same DB — RAG without a separate vector store. SIMD on AVX2/AVX512/ARM/PowerPC |
+| **JSON Schema validation** at column level | Constrain `JSON` columns instead of validating only in PHP |
+| **System-versioned (temporal) tables** | Native row history, point-in-time queries — replaces hand-rolled audit tables |
+| **`TIMESTAMP` range extended to 2106** | The 2038 problem is fixed for new schemas |
+| **PARSEC auth plugin** (Password Auth Response Signed by Elliptic Curves) | Stronger than `mysql_native_password`; safer than `caching_sha2_password` for SSL-less internal hops |
+| **Parallel `mariadb-dump` / `mariadb-import`** | Backup/restore minutes instead of hours on multi-GB DBs |
+
+### Vector search example (RAG-style)
+
+```sql
+-- MariaDB 11.7+
+CREATE TABLE doc_chunks (
+    id     INT AUTO_INCREMENT PRIMARY KEY,
+    text   TEXT NOT NULL,
+    embedding VECTOR(1536) NOT NULL,                -- e.g. text-embedding-3-small
+    VECTOR INDEX (embedding) USING HNSW             -- approximate nearest neighbor
+);
+
+-- Similarity search
+SELECT id, text, VEC_DISTANCE_COSINE(embedding, VEC_FromText(?)) AS distance
+FROM   doc_chunks
+ORDER  BY distance
+LIMIT  5;
+```
+
+```php
+// Eloquent — bind embedding as a JSON-encoded array of floats; MariaDB driver coerces
+$results = DB::select(
+    'SELECT id, text, VEC_DISTANCE_COSINE(embedding, VEC_FromText(?)) AS distance
+       FROM doc_chunks ORDER BY distance LIMIT 5',
+    [json_encode($queryEmbedding)],
+);
+```
+
+### System-versioned tables (audit history without triggers)
+
+```sql
+CREATE TABLE accounts (
+    id      INT PRIMARY KEY,
+    balance DECIMAL(12,2) NOT NULL,
+    PERIOD FOR system_time(start_ts, end_ts),
+    start_ts TIMESTAMP(6) GENERATED ALWAYS AS ROW START,
+    end_ts   TIMESTAMP(6) GENERATED ALWAYS AS ROW END
+) WITH SYSTEM VERSIONING;
+
+-- Query historical state
+SELECT * FROM accounts FOR SYSTEM_TIME AS OF '2026-04-01 12:00:00';
+SELECT * FROM accounts FOR SYSTEM_TIME BETWEEN '2026-04-01' AND '2026-05-01';
+```
+
+Replaces hand-rolled `accounts_history` tables fed by triggers — MariaDB does it natively, including `pg_dump`-style point-in-time queries.
+
+### JSON Schema column constraint
+
+```sql
+ALTER TABLE leads
+    MODIFY metadata JSON
+    CHECK (JSON_SCHEMA_VALID('{
+        "type": "object",
+        "required": ["source", "campaign"],
+        "properties": {
+            "source":   { "type": "string" },
+            "campaign": { "type": "string" }
+        }
+    }', metadata));
+```
+
+Bad payloads now fail at INSERT time, not at the next time PHP tries to read them.
+
+---
+
 ## Why Octane Changes Everything
 
 ```
@@ -39,8 +118,9 @@ Problems in Octane:
     'database' => env('DB_DATABASE'),
     'username' => env('DB_USERNAME'),
     'password' => env('DB_PASSWORD'),
-    'charset' => 'utf8mb4',
-    'collation' => 'utf8mb4_unicode_ci',
+    'charset' => 'utf8mb4',                  // default in MariaDB 11.8 — keep explicit for older servers
+    'collation' => 'utf8mb4_uca1400_ai_ci',   // 11.x — Unicode 14, accent-insensitive, case-insensitive
+                                              // (use utf8mb4_unicode_ci on MariaDB ≤ 10.11 / MySQL)
     'prefix' => '',
     'strict' => true,                    // ← MANDATORY
     'engine' => 'InnoDB',
@@ -388,3 +468,15 @@ Route::get('/health', function () {
 | `Lead::count()` on millions of rows | Cached count or approximate count |
 | `'metadata' => 'json'` cast | `'metadata' => 'array'` (auto decode) |
 | `datetime` cast | `immutable_datetime` (Octane-safe, no mutation) |
+| Hand-rolled `*_history` tables fed by triggers | System-versioned (`WITH SYSTEM VERSIONING`) — MariaDB 11.x |
+| Storing embeddings as `LONGTEXT` JSON | Native `VECTOR(N)` + `VEC_DISTANCE_*` (MariaDB 11.7+) |
+| Validating JSON only in PHP | Add `JSON_SCHEMA_VALID` CHECK constraint on the column |
+
+## See Also
+
+- `_shared/skills/postgres-patterns` — analogous skill on the Postgres side (PG 18 features); MariaDB-specific equivalents documented here
+- `_shared/skills/database-migrations` — universal parallel-change / backfill rules
+- `laravel-octane` — worker safety rules this skill plugs into
+- `php-patterns` — `readonly`, enums, immutable_datetime that pair with Eloquent casts
+- `phpstan-analysis` (Larastan) — model PHPDoc generation makes Eloquent type-safe
+- `api-design` — pagination shape that backend cursor pagination feeds

package/stacks/php/skills/php-patterns/SKILL.md

@@ -1,15 +1,108 @@
 ---
 name: php-patterns
-version: 1.0.0
+version: 2.0.0
+description: "Modern PHP idioms for Laravel apps targeting PHP 8.3 and 8.4 (Nov 2024). Covers property hooks (replace boilerplate getters/setters), asymmetric visibility (public read / private write), lazy objects via Reflection, typed class constants (8.3), readonly classes, enums, match, named args, null-safe, first-class callable syntax, constructor promotion, Octane-safe DI patterns. Invoke for any new PHP class, refactor of an old one, or when reviewing OOP code."
 ---
 
-# PHP 8.3+ Patterns for Laravel
+# PHP 8.3 / 8.4 Patterns for Laravel
 
 ## Version Requirements
 
-- **PHP >= 8.3** — MANDATORY. Use all modern features.
-- **Composer >= 2.0** — For dependency management.
-- Use strict types: `declare(strict_types=1);` in EVERY file.
+- **PHP ≥ 8.3** — minimum supported (Laravel 12 supports 8.2–8.5; we target 8.3+).
+- **PHP 8.4 strongly recommended** for new projects (released **Nov 21, 2024**) — adds property hooks + asymmetric visibility + lazy objects.
+- **Composer ≥ 2.8** — see `composer-workflow`.
+- `declare(strict_types=1);` in EVERY file. No exceptions.
+
+## PHP 8.4 Highlights — adopt for new code
+
+### Property Hooks — replace getter/setter boilerplate
+
+The single most consequential 8.4 feature. Replaces hand-rolled `get`/`set` methods that exist solely to wrap a stored value.
+
+```php
+class User
+{
+    public function __construct(
+        public string $firstName,
+        public string $lastName,
+    ) {}
+
+    // Computed property — no method call, no boilerplate
+    public string $fullName {
+        get => trim("{$this->firstName} {$this->lastName}");
+    }
+
+    // Validation on assignment
+    public string $email {
+        set (string $value) {
+            if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
+                throw new \InvalidArgumentException("Invalid email: {$value}");
+            }
+            $this->email = strtolower($value);
+        }
+    }
+}
+
+$u = new User('John', 'Doe');
+echo $u->fullName;          // "John Doe" — read like a field
+$u->email = 'JOHN@DOE.COM'; // validated + lowercased on assign
+```
+
+Use property hooks when the field has computation or validation. **Don't** wrap a plain value just because old code did.
+
+### Asymmetric Visibility — read public, write protected
+
+```php
+final class Order
+{
+    public function __construct(
+        public private(set) string $id,         // readable everywhere; writable only inside Order
+        public protected(set) string $status,   // writable in Order + subclasses
+    ) {}
+
+    public function markPaid(): void { $this->status = 'paid'; }
+}
+
+$o = new Order('ord_123', 'pending');
+echo $o->id;             // OK
+$o->status = 'paid';     // ERROR — only Order/subclasses can write
+$o->markPaid();          // OK
+```
+
+Replaces the `private $id; public function id() { return $this->id; }` pattern entirely.
+
+### Lazy Objects — defer expensive init
+
+```php
+$reflector = new \ReflectionClass(ExpensiveService::class);
+$service = $reflector->newLazyGhost(function (ExpensiveService $svc): void {
+    // Runs only on first real access — bootstraps DB conn, loads cache, etc.
+    $svc->__construct(/* ... */);
+});
+
+// $service behaves like ExpensiveService but does nothing until used:
+$service->doSomething();   // <-- init runs here, exactly once
+```
+
+Mostly relevant for ORM-style proxies / DI containers. Day-to-day app code rarely needs it.
+
+### New JIT (IR Framework)
+
+Enabled by default in PHP 8.4. No app code change needed; just verify your `opcache.ini` enables JIT in production:
+
+```ini
+opcache.jit_buffer_size=128M
+opcache.jit=tracing
+```
+
+### Other 8.4 deltas worth knowing
+
+- HTML5-aware `Dom\HTMLDocument` (replaces the legacy quirks-mode parser)
+- `array_find()`, `array_find_key()`, `array_any()`, `array_all()` — finally
+- Object API for `BCMath\Number` — chainable arbitrary-precision math
+- 4-year support lifecycle (active + security)
+
+## Modern PHP Features (USE THESE)
 
 ## Modern PHP Features (USE THESE)
 

package/stacks/php/skills/phpstan-analysis/SKILL.md

@@ -1,73 +1,179 @@
 ---
 name: phpstan-analysis
-version: 1.0.0
+version: 2.0.0
+description: "PHPStan 2.x (released Nov 11, 2024) static analysis for PHP 8.3-8.5 / Laravel 12. Covers Level 10 (strict mixed even from inferred types — new in 2.0), the list<T> array type for sequential int-keyed arrays, baseline workflow for legacy code, generics + array shapes annotations, larastan extension for Laravel-specific rules (Eloquent magic, facades, container resolution), 50-70% memory reduction in 2.0, CI integration with --error-format. Invoke when configuring PHPStan, raising the level, fixing reported issues, or onboarding a legacy codebase."
 ---
 
-# PHPStan Static Analysis
+# PHPStan Static Analysis (2.x, Nov 2024)
+
+**Invoke when configuring PHPStan, raising the level, fixing reports, or wiring it into CI.**
+
+> PHPStan 2.0 (Nov 11, 2024) added **Level 10** and the **`list<T>`** type, dropped 50-70% memory usage, and tightened reference-parameter analysis. It's a transparent upgrade from 1.x — same config keys, stricter inferences. Update as part of any project refresh.
 
 ## Setup
 
 ```bash
-composer require --dev phpstan/phpstan
+composer require --dev phpstan/phpstan "^2.0"
+
+# Laravel projects — add Larastan for framework awareness
+composer require --dev larastan/larastan "^3.0"
 ```
 
-## Configuration (phpstan.neon)
+## Configuration (`phpstan.neon` / `phpstan.neon.dist`)
 
 ```neon
+# Plain PHP project
 parameters:
-    level: 6
+    level: 8                       # Target. Raise toward 10.
     paths:
         - src
-        - app
+        - tests
     excludePaths:
         - vendor
         - storage
         - bootstrap/cache
-    checkMissingIterableValueType: false
+    treatPhpDocTypesAsCertain: false   # Pragmatic for first month at high level
+    reportUnmatchedIgnoredErrors: true
+    parallel:
+        maximumNumberOfProcesses: 4
+
+# Laravel project (Larastan)
+includes:
+    - vendor/larastan/larastan/extension.neon
+parameters:
+    level: 8
+    paths:
+        - app
+        - bootstrap
+        - config
+        - database
+        - routes
+    excludePaths:
+        - storage
+        - bootstrap/cache
 ```
 
-## Levels
+## Levels — what each one adds
 
-| Level | What it checks |
-|-------|---------------|
-| 0 | Basic checks (unknown classes, functions) |
-| 1 | Possibly undefined variables, return types |
-| 2 | Unknown methods on all expressions |
+| Level | Catches |
+|---|---|
+| 0 | Unknown classes / functions / methods on `$this` |
+| 1 | Possibly undefined variables, undefined params on `$this`, unreachable code |
+| 2 | Unknown methods on **all** expressions (not just `$this`) |
 | 3 | Return types, property types |
-| 4 | Dead code, always true/false |
-| 5 | Argument types |
-| **6** | **MINIMUM for this project** — strict types |
-| 7 | Union types |
-| 8 | Nullable types everywhere |
-| 9 | Mixed type restrictions |
+| 4 | Dead code, always-true/always-false branches |
+| 5 | Argument types in function/method calls |
+| 6 | Missing typehints (params + returns) |
+| 7 | Partially-wrong union types |
+| 8 | Calling methods / accessing props on nullable types |
+| 9 | `mixed` is treated strictly when **explicitly typed** |
+| **10 (NEW in 2.0)** | `mixed` strict even when **implicitly inferred** (any unknown type) |
+
+**Recommended target:** Level 8 for new projects (achievable with Larastan + readonly DTOs); raise to 9 once stable; 10 only after eliminating all `mixed` from your own code.
+
+## `list<T>` — the new sequential array type *(2.0)*
+
+Use when you have a 0-indexed contiguous array. PHPStan can then narrow types far more precisely than with `array<int, T>`.
+
+```php
+/**
+ * @param list<int> $ids   sequential 0,1,2,... no gaps
+ * @return list<User>      same shape on the way out
+ */
+public function findManyById(array $ids): array
+{
+    return User::whereIn('id', $ids)->get()->all();
+}
+```
+
+Other useful array types:
+
+| PHPDoc | Meaning |
+|---|---|
+| `array<int>` | Any-shape array of ints |
+| `list<int>` | Sequential, 0-indexed, no gaps |
+| `non-empty-array<string, int>` | At least one entry; string keys, int values |
+| `non-empty-list<User>` | Sequential AND non-empty |
+| `array{name: string, age: int}` | Array shape (object-like) |
+| `array{name: string, age?: int}` | Optional key |
 
 ## Running
 
 ```bash
-vendor/bin/phpstan analyse                    # Default config
-vendor/bin/phpstan analyse --level=6 src/     # Specific level & path
-vendor/bin/phpstan analyse --generate-baseline # Generate baseline for legacy code
+vendor/bin/phpstan analyse                     # Use config
+vendor/bin/phpstan analyse --level=8 src/      # Override level + path
+vendor/bin/phpstan analyse --memory-limit=1G   # Bigger projects (still ~50% less than 1.x)
+vendor/bin/phpstan analyse --generate-baseline # Snapshot legacy errors → unblocks CI
+vendor/bin/phpstan analyse --error-format=github  # CI annotations on PRs
 ```
 
+## Baseline workflow (legacy adoption)
+
+```bash
+# Day 1: ratchet to a level that's mostly clean, baseline the rest
+vendor/bin/phpstan analyse --level=6 --generate-baseline
+
+# Day 2+: every new file/edit cannot ADD baseline entries
+# Periodically: chip away at the baseline (delete entries, fix code)
+vendor/bin/phpstan analyse --level=6                # must pass
+vendor/bin/phpstan analyse --level=6 --error-format=github
+```
+
+`reportUnmatchedIgnoredErrors: true` ensures the baseline shrinks (or fails CI) instead of growing silently.
+
 ## Common Fixes
 
 ```php
-// ❌ PHPStan error: Parameter $data has no type hint
+// ❌ Parameter $data has no type hint
 function process($data) {}
 
-// ✅ Fixed
+// ✅
 function process(array $data): void {}
 
-// ❌ PHPStan error: Method returns mixed
+
+// ❌ Method returns mixed
 function getData() { return $this->db->query(); }
 
-// ✅ Fixed
-/** @return array<string, mixed> */
+// ✅ — PHPDoc + native return type
+/** @return list<array<string, mixed>> */
 function getData(): array { return $this->db->query(); }
+
+
+// ❌ "Cannot access property $name on User|null"
+echo $request->user()->name;
+
+// ✅ — assert or null-coalesce
+echo $request->user()?->name ?? 'guest';
+
+
+// ❌ "Property User::$email is never written, only read"
+class User {
+    public function __construct(public readonly string $email) {}
+    // PHPStan now reports if you typo-shadow the property elsewhere
+}
 ```
 
+## CI integration
+
+```yaml
+# .github/workflows/ci.yml
+- name: PHPStan
+  run: vendor/bin/phpstan analyse --error-format=github --memory-limit=1G
+```
+
+GitHub annotations show inline diff comments on the PR — much higher signal than the textual report.
+
 ## Rules
 
-1. **Level 6 minimum** — no exceptions
-2. **Fix errors, don't ignore** — use baseline only for legacy code
-3. **Run before commit** — part of quality gates
+1. **Target level 8 minimum** for new code; raise to 9/10 incrementally
+2. **Larastan is mandatory** on Laravel projects (Eloquent magic methods, facades, container)
+3. **Baseline only legacy code** — new files must be clean
+4. **Run before every commit** — wired into the quality gate
+5. **`reportUnmatchedIgnoredErrors: true`** — baseline shrinks, never grows silently
+6. **No `@phpstan-ignore` without a comment** explaining why and a link to the issue if upstream
+
+## See Also
+
+- `quality-gate` — typecheck step ordering
+- `composer-workflow` — `--memory-limit` and CI script wiring
+- `phpunit-testing` — Pest 4 + PHPUnit 12 typing patterns that benefit from PHPStan