@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/php-pro/references/modern-php-features.md

@@ -0,0 +1,189 @@
+# Modern PHP Features
+
+## Enums (PHP 8.1+)
+
+```php
+// Pure enum — no backing value
+enum Status {
+    case Active;
+    case Inactive;
+    case Suspended;
+
+    public function label(): string {
+        return match($this) {
+            self::Active => 'Active',
+            self::Inactive => 'Inactive',
+            self::Suspended => 'Suspended',
+        };
+    }
+}
+
+// Backed enum — string or int backing type
+enum Role: string {
+    case Admin = 'admin';
+    case Editor = 'editor';
+    case Viewer = 'viewer';
+
+    // Create from string (throws ValueError if invalid)
+    // Role::from('admin') → Role::Admin
+    // Role::tryFrom('unknown') → null
+}
+
+// Enum implementing interface
+interface HasPermissions {
+    public function permissions(): array;
+}
+
+enum Role: string implements HasPermissions {
+    case Admin = 'admin';
+    case Editor = 'editor';
+
+    public function permissions(): array {
+        return match($this) {
+            self::Admin => ['read', 'write', 'delete', 'manage'],
+            self::Editor => ['read', 'write'],
+        };
+    }
+}
+```
+
+## Readonly Properties and Classes (PHP 8.2+)
+
+```php
+// Readonly properties — set once, never modified
+class User {
+    public function __construct(
+        public readonly int $id,
+        public readonly string $name,
+        public readonly Email $email,
+        public readonly \DateTimeImmutable $createdAt = new \DateTimeImmutable(),
+    ) {}
+}
+
+// Readonly class — all properties are implicitly readonly
+readonly class Money {
+    public function __construct(
+        public int $amount,
+        public string $currency,
+    ) {}
+
+    public function add(Money $other): self {
+        if ($this->currency !== $other->currency) {
+            throw new \DomainException('Cannot add different currencies');
+        }
+        return new self($this->amount + $other->amount, $this->currency);
+    }
+}
+```
+
+## Match Expression (PHP 8.0+)
+
+```php
+// match is strict (===), returns a value, no fall-through
+$result = match($status) {
+    200, 201 => 'success',
+    301, 302 => 'redirect',
+    404      => 'not found',
+    500      => 'server error',
+    default  => 'unknown',
+};
+
+// match with no subject — replaces if/elseif chains
+$tier = match(true) {
+    $points >= 1000 => 'gold',
+    $points >= 500  => 'silver',
+    $points >= 100  => 'bronze',
+    default         => 'standard',
+};
+```
+
+## Named Arguments (PHP 8.0+)
+
+```php
+// Skip optional parameters, improve readability
+$response = new JsonResponse(
+    data: $payload,
+    status: 201,
+    headers: ['X-Request-Id' => $requestId],
+);
+
+// Useful with functions that have many options
+str_contains(haystack: $input, needle: 'search');
+
+// Named arguments work with arrays using spread
+$args = ['data' => $payload, 'status' => 200];
+$response = new JsonResponse(...$args);
+```
+
+## Fibers (PHP 8.1+)
+
+```php
+// Fibers provide cooperative multitasking — used by frameworks, not typically by userland
+$fiber = new Fiber(function (): void {
+    $value = Fiber::suspend('first');
+    echo "Resumed with: $value\n";
+    Fiber::suspend('second');
+});
+
+$result1 = $fiber->start();     // 'first'
+$result2 = $fiber->resume('hello'); // prints "Resumed with: hello", returns 'second'
+
+// Real-world: async frameworks (ReactPHP, Amp, Revolt) use fibers internally
+// You typically use the framework's async API, not raw fibers
+```
+
+## First-Class Callable Syntax (PHP 8.1+)
+
+```php
+// Create closures from existing functions/methods
+$users = array_filter($users, strlen(...)); // passes strlen as callable
+$names = array_map($user->getName(...), $users);
+
+// Method references
+$validator = $this->validate(...);
+$formatter = NumberFormatter::format(...);
+```
+
+## Intersection and Union Types
+
+```php
+// Union types (PHP 8.0) — value is one of the types
+function process(string|int $value): string|false {
+    // ...
+}
+
+// Intersection types (PHP 8.1) — value satisfies all types
+function countAndIterate(Countable&Iterator $items): void {
+    echo count($items);
+    foreach ($items as $item) { /* ... */ }
+}
+
+// Disjunctive Normal Form types (PHP 8.2)
+function handle((Countable&Iterator)|null $items): void {
+    // nullable intersection type
+}
+```
+
+## Property Hooks (PHP 8.4)
+
+```php
+// Virtual properties with get/set hooks
+class Temperature {
+    public float $celsius {
+        get => ($this->fahrenheit - 32) * 5 / 9;
+        set => $this->fahrenheit = $value * 9 / 5 + 32;
+    }
+
+    public function __construct(
+        public float $fahrenheit,
+    ) {}
+}
+
+// Asymmetric visibility (PHP 8.4)
+class User {
+    public function __construct(
+        public private(set) string $name, // readable publicly, writable only internally
+        public protected(set) int $age,
+    ) {}
+}
+```

package/workflows/powers/php-pro/references/performance-and-deployment.md

@@ -0,0 +1,197 @@
+# Performance and Deployment
+
+## OPcache Configuration
+
+```ini
+; php.ini — production OPcache settings
+opcache.enable=1
+opcache.memory_consumption=256          ; MB, adjust per app size
+opcache.max_accelerated_files=20000     ; must be prime, covers most projects
+opcache.validate_timestamps=0           ; NEVER check file changes in production
+opcache.revalidate_freq=0               ; irrelevant when validate_timestamps=0
+
+; JIT compilation (PHP 8.0+)
+opcache.jit_buffer_size=128M
+opcache.jit=1255                        ; tracing JIT — best for long-running
+; Use 1205 for function-level JIT if tracing JIT causes issues
+
+; File cache for faster restarts
+opcache.file_cache='/tmp/opcache'
+opcache.file_cache_consistency_checks=0 ; skip in production
+```
+
+## Preloading (PHP 7.4+)
+
+```php
+// preload.php — loaded once at server startup, shared across all requests
+// Set in php.ini: opcache.preload=/app/preload.php
+// opcache.preload_user=www-data
+
+$files = [
+    // Framework core classes
+    __DIR__ . '/vendor/autoload.php',
+    // Heavily used domain classes
+    __DIR__ . '/src/Domain/Order.php',
+    __DIR__ . '/src/Domain/User.php',
+    __DIR__ . '/src/Service/OrderService.php',
+];
+
+foreach ($files as $file) {
+    if (file_exists($file)) {
+        opcache_compile_file($file);
+    }
+}
+
+// Composer autoload preloading (Laravel example)
+// require __DIR__ . '/vendor/autoload.php';
+// (new Illuminate\Foundation\PackageManifest(...))->preload();
+```
+
+## Profiling with Xdebug
+
+```ini
+; php.ini — profiling mode
+xdebug.mode=profile
+xdebug.output_dir=/tmp/xdebug-profiles
+xdebug.profiler_output_name=cachegrind.out.%R.%t
+
+; Trigger-based profiling (don't profile every request)
+xdebug.start_with_request=trigger
+; Add ?XDEBUG_PROFILE=1 to URL or set cookie
+```
+
+```bash
+# Analyze with KCachegrind/QCachegrind
+kcachegrind /tmp/xdebug-profiles/cachegrind.out.*.1234567890
+
+# Or use webgrind for browser-based analysis
+```
+
+## Profiling with Blackfire
+
+```bash
+# Install Blackfire probe + agent
+# Profile a specific request
+blackfire run php artisan my:command
+blackfire curl https://myapp.test/api/orders
+
+# Compare two profiles
+blackfire diff profile-1-uuid profile-2-uuid
+
+# Assertions in CI
+blackfire-player run scenarios.bkf --endpoint=https://staging.myapp.com
+```
+
+## Database Query Optimization
+
+```php
+// Avoid N+1 queries — eager load relations
+// BAD — N+1 queries
+$orders = Order::all();
+foreach ($orders as $order) {
+    echo $order->customer->name; // 1 query per order
+}
+
+// GOOD — eager loading
+$orders = Order::with('customer')->get(); // 2 queries total
+
+// Use query scope for reusable filters
+class Order extends Model
+{
+    public function scopeRecent(Builder $query): Builder
+    {
+        return $query->where('created_at', '>', now()->subDays(30));
+    }
+
+    public function scopeForCustomer(Builder $query, int $customerId): Builder
+    {
+        return $query->where('customer_id', $customerId);
+    }
+}
+
+// Usage: Order::recent()->forCustomer(42)->get();
+```
+
+## Caching Patterns
+
+```php
+// Cache-aside pattern
+public function getProduct(int $id): Product
+{
+    $cacheKey = "product:{$id}";
+
+    return Cache::remember($cacheKey, ttl: 3600, callback: function () use ($id) {
+        return $this->repository->findById($id)
+            ?? throw new ProductNotFoundException($id);
+    });
+}
+
+// Cache invalidation on write
+public function updateProduct(int $id, UpdateProductDto $dto): Product
+{
+    $product = $this->repository->update($id, $dto);
+    Cache::forget("product:{$id}");
+    Cache::tags(['products'])->flush(); // tag-based invalidation
+    return $product;
+}
+```
+
+## FrankenPHP / Swoole / RoadRunner
+
+```php
+// FrankenPHP worker mode — keep application in memory
+// frankenphp.yaml
+worker:
+    cmd: ["frankenphp", "php-server", "--worker", "public/index.php"]
+    watch:
+        - src/**/*.php
+
+// Swoole HTTP server (Laravel Octane)
+// Long-running process — beware of:
+// 1. Static/global state leaking between requests
+// 2. Memory leaks from uncollected references
+// 3. Database connections staying open
+
+// Reset state between requests
+protected function resetState(): void
+{
+    // Clear request-scoped caches
+    // Reset singleton instances that hold request state
+    // Flush buffered output
+}
+```
+
+## Deployment Checklist
+
+```bash
+# 1. Install production dependencies
+composer install --no-dev --optimize-autoloader --classmap-authoritative
+
+# 2. Clear and warm caches
+php artisan config:cache      # Laravel
+php artisan route:cache
+php artisan view:cache
+php artisan event:cache
+
+# 3. Run migrations
+php artisan migrate --force
+
+# 4. OPcache reset (after deploying new code)
+# Via SIGUSR2 to PHP-FPM, or cachetool:
+cachetool opcache:reset
+
+# 5. Verify
+php artisan about              # check config
+php artisan queue:monitor      # check workers
+```
+
+## Common Performance Anti-Patterns
+
+| Anti-pattern                 | Impact                      | Fix                                 |
+| ---------------------------- | --------------------------- | ----------------------------------- |
+| N+1 queries                  | O(n) DB calls per list      | Eager loading, joins                |
+| No OPcache                   | Parses PHP on every request | Enable with `validate_timestamps=0` |
+| Synchronous email sending    | Blocks request for 1-5s     | Queue with jobs/workers             |
+| `file_get_contents` for HTTP | No timeout, no retry        | Use Guzzle/Symfony HttpClient       |
+| Storing sessions in files    | Lock contention under load  | Redis/database sessions             |
+| Loading entire table         | Memory exhaustion           | Cursor/chunk processing             |

package/workflows/powers/php-pro/references/php84-strict-typing-checklist.md

@@ -0,0 +1,161 @@
+# PHP 8.4 Strict Typing Checklist
+
+## Strict types enforcement
+
+### File header
+
+Every PHP file must start with:
+
+```php
+<?php
+
+declare(strict_types=1);
+```
+
+- Without this declaration, PHP silently coerces types (e.g., `"123abc"` becomes `123`).
+- With strict types, type mismatches throw `TypeError` immediately.
+
+### Method signatures
+
+```php
+public function createUser(
+    string $name,
+    string $email,
+    ?int $teamId = null,
+): User {
+    // ...
+}
+```
+
+- Type every parameter, return value, and property. No untyped public APIs.
+- Use `?Type` for nullable parameters. Use `mixed` only when genuinely any type is accepted.
+- Use `void` return type when the function returns nothing.
+
+## PHP 8.4 type features
+
+### Enums
+
+```php
+enum Status: string {
+    case Active = 'active';
+    case Inactive = 'inactive';
+    case Suspended = 'suspended';
+}
+
+// Usage
+function setStatus(Status $status): void { /* ... */ }
+setStatus(Status::Active);
+```
+
+- Use backed enums (`string` or `int`) for values stored in databases or APIs.
+- Use pure enums when the enum is only used for type discrimination.
+- Enums can implement interfaces and use traits (without properties).
+
+### Readonly properties and classes
+
+```php
+readonly class UserDTO {
+    public function __construct(
+        public string $name,
+        public string $email,
+        public int $age,
+    ) {}
+}
+```
+
+- Use `readonly` for immutable data transfer objects and value objects.
+- Readonly properties can only be initialized once (in constructor or declaration).
+- Readonly classes make all properties implicitly readonly.
+
+### Union and intersection types
+
+```php
+function process(string|Stringable $input): int|float { /* ... */ }
+
+function handle(Countable&Iterator $collection): void { /* ... */ }
+```
+
+- Union types (`A|B`): value can be any of the listed types.
+- Intersection types (`A&B`): value must satisfy all listed types. Useful for requiring multiple interfaces.
+- DNF types (PHP 8.2+): combine union and intersection: `(A&B)|C`.
+
+## PHPStan configuration
+
+### Recommended `phpstan.neon`
+
+```neon
+parameters:
+    level: 8
+    paths:
+        - src
+        - tests
+    excludePaths:
+        - src/legacy/*
+    checkGenericClassInNonGenericObjectType: true
+    treatPhpDocTypesAsCertain: false
+    reportUnmatchedIgnoredErrors: true
+```
+
+- Start at level 5 for legacy codebases, target level 8+ for new code.
+- Use baseline file (`phpstan-baseline.neon`) to track pre-existing errors without blocking CI.
+- Run `phpstan analyze` in CI on every PR. Block merge on new errors.
+
+### PHPStan generics
+
+```php
+/**
+ * @template T
+ * @param class-string<T> $className
+ * @return T
+ */
+function create(string $className): object { /* ... */ }
+```
+
+- Use `@template` annotations for generic types until PHP has native generics.
+- Annotate collections: `@var array<string, User>` instead of `@var array`.
+
+## Composer security audit
+
+### CI pipeline
+
+```yaml
+steps:
+  - run: composer install --no-dev --prefer-dist
+  - run: composer audit --format=json
+  - run: composer outdated --direct --format=json
+```
+
+- `composer audit` checks installed packages against known vulnerabilities (Packagist advisory database).
+- Run on every CI build. Block deploys on critical/high severity findings.
+- `composer outdated --direct` shows only direct dependency updates needed.
+
+### Lock file hygiene
+
+- Always commit `composer.lock` for applications. Never commit it for libraries.
+- Run `composer validate --strict` in CI to catch manifest issues.
+- Update dependencies in small batches with test verification between updates.
+- Pin PHP version requirement in `composer.json`: `"php": ">=8.4 <8.5"`.
+
+## Error pattern: typed results
+
+```php
+readonly class Result {
+    private function __construct(
+        public readonly bool $ok,
+        public readonly mixed $value = null,
+        public readonly ?string $error = null,
+    ) {}
+
+    public static function success(mixed $value): self {
+        return new self(ok: true, value: $value);
+    }
+
+    public static function failure(string $error): self {
+        return new self(ok: false, error: $error);
+    }
+}
+```
+
+- Use result objects for expected failures (validation, not-found) instead of exceptions.
+- Exceptions remain for truly exceptional conditions (database down, file system errors).
+- This pattern works well with PHPStan generics: `Result<User>`.