@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/php-best-practices/references/composer-packaging.md

@@ -1,289 +0,0 @@
-# Composer Packaging Reference
-
-## PSR-4 Autoloading
-
-### Standard configuration
-
-```json
-{
-    "autoload": {
-        "psr-4": {
-            "Acme\\MyPackage\\": "src/"
-        }
-    },
-    "autoload-dev": {
-        "psr-4": {
-            "Acme\\MyPackage\\Tests\\": "tests/"
-        }
-    }
-}
-```
-
-### PSR-4 rules
-
-| Namespace | File path | Valid |
-| --- | --- | --- |
-| `Acme\MyPackage\User` | `src/User.php` | Yes |
-| `Acme\MyPackage\Domain\User` | `src/Domain/User.php` | Yes |
-| `Acme\MyPackage\User` | `src/Models/User.php` | No — namespace doesn't match |
-
-After changing autoload config, run:
-```bash
-composer dump-autoload --optimize
-```
-
-### Never use manual loading
-
-```php
-// BAD — defeats autoloading, creates implicit dependencies
-require_once __DIR__ . '/../src/User.php';
-include 'helpers.php';
-
-// GOOD — Composer handles everything
-use Acme\MyPackage\User;
-$user = new User();
-```
-
-## composer.json for Libraries
-
-```json
-{
-    "name": "acme/validation",
-    "description": "Type-safe validation library for PHP 8.4+",
-    "type": "library",
-    "license": "MIT",
-    "require": {
-        "php": ">=8.4",
-        "psr/log": "^3.0"
-    },
-    "require-dev": {
-        "phpunit/phpunit": "^11.0",
-        "phpstan/phpstan": "^2.0",
-        "friendsofphp/php-cs-fixer": "^3.0"
-    },
-    "autoload": {
-        "psr-4": {
-            "Acme\\Validation\\": "src/"
-        }
-    },
-    "autoload-dev": {
-        "psr-4": {
-            "Acme\\Validation\\Tests\\": "tests/"
-        }
-    },
-    "config": {
-        "sort-packages": true
-    },
-    "minimum-stability": "stable",
-    "prefer-stable": true,
-    "scripts": {
-        "test": "phpunit",
-        "analyse": "phpstan analyse",
-        "cs-fix": "php-cs-fixer fix",
-        "cs-check": "php-cs-fixer fix --dry-run --diff",
-        "check": ["@cs-check", "@analyse", "@test"]
-    }
-}
-```
-
-## composer.json for Applications
-
-```json
-{
-    "name": "acme/my-app",
-    "type": "project",
-    "require": {
-        "php": ">=8.4",
-        "acme/validation": "^2.0",
-        "symfony/http-foundation": "^7.0"
-    },
-    "config": {
-        "optimize-autoloader": true,
-        "sort-packages": true
-    }
-}
-```
-
-### Lock file rules
-
-| Context | Commit composer.lock? | Why |
-| --- | --- | --- |
-| Application | Yes | Reproducible builds — everyone gets same versions |
-| Library | No | Consumers need flexibility to resolve their own dependency tree |
-
-## Semantic Versioning
-
-### Version constraints
-
-| Constraint | Meaning | Example |
-| --- | --- | --- |
-| `^2.0` | `>=2.0.0 <3.0.0` | Most common — allows minor updates |
-| `~2.1` | `>=2.1.0 <2.2.0` | Allows patch updates only |
-| `2.1.3` | Exact version | Rarely needed — too restrictive |
-| `>=2.0 <2.5` | Range | Explicit bounds |
-| `*` | Any version | Never use in production |
-
-### When to bump versions
-
-| Change | Version bump | Example |
-| --- | --- | --- |
-| Breaking API change | Major | 2.x -> 3.0.0 |
-| New feature, backward compatible | Minor | 2.1.x -> 2.2.0 |
-| Bug fix, backward compatible | Patch | 2.1.1 -> 2.1.2 |
-
-### Tagging releases
-
-```bash
-git tag -a v2.1.0 -m "Release v2.1.0: add validation rules"
-git push origin v2.1.0
-```
-
-## Security Auditing
-
-### Check for known vulnerabilities
-
-```bash
-# Built into Composer 2.4+
-composer audit
-
-# Example output:
-# Found 1 security vulnerability advisory affecting 1 package:
-# Package: vendor/package
-# CVE: CVE-2024-XXXX
-# Title: SQL injection in query builder
-# Severity: high
-```
-
-### CI integration
-
-```yaml
-- name: Security audit
-  run: composer audit --format=json
-```
-
-### Dependency health
-
-```bash
-# List outdated packages
-composer outdated --direct
-
-# Show why a package is installed
-composer why vendor/package
-
-# Show dependency tree
-composer show --tree
-```
-
-## Package Publishing
-
-### Packagist registration
-
-1. Create a `composer.json` with proper `name` field.
-2. Tag a release with semantic version.
-3. Submit repository URL to [packagist.org](https://packagist.org).
-4. Set up GitHub webhook for auto-updates.
-
-### Package structure
-
-```
-my-package/
-├── composer.json
-├── LICENSE
-├── phpstan.neon.dist
-├── phpunit.xml.dist
-├── .php-cs-fixer.dist.php
-├── .gitignore
-├── src/
-│   ├── RuleInterface.php
-│   ├── Validator.php
-│   └── Rules/
-│       ├── Required.php
-│       └── MinLength.php
-└── tests/
-    ├── ValidatorTest.php
-    └── Rules/
-        ├── RequiredTest.php
-        └── MinLengthTest.php
-```
-
-### .gitignore for packages
-
-```
-/vendor/
-/.phpunit.cache/
-/.phpstan-cache/
-/coverage/
-composer.lock
-.php-cs-fixer.cache
-```
-
-## Composer Scripts
-
-### Pre/post hooks
-
-```json
-{
-    "scripts": {
-        "post-install-cmd": [
-            "@php artisan clear-compiled"
-        ],
-        "post-update-cmd": [
-            "@php artisan clear-compiled"
-        ],
-        "test": "phpunit",
-        "analyse": "phpstan analyse",
-        "cs": "php-cs-fixer fix --dry-run --diff",
-        "check": [
-            "@cs",
-            "@analyse",
-            "@test"
-        ]
-    }
-}
-```
-
-### Running scripts
-
-```bash
-composer run-script test
-composer test        # shorthand for well-known scripts
-composer check       # runs cs, analyse, test in sequence
-```
-
-## Platform Requirements
-
-```json
-{
-    "require": {
-        "php": ">=8.4",
-        "ext-json": "*",
-        "ext-mbstring": "*",
-        "ext-pdo": "*"
-    },
-    "config": {
-        "platform": {
-            "php": "8.4.0"
-        }
-    }
-}
-```
-
-The `config.platform` setting forces Composer to resolve dependencies as if running the specified PHP version, even if the local PHP is newer. This prevents accidentally requiring features unavailable in production.
-
-## Autoload Optimization
-
-```bash
-# Development — fastest dump, includes all classes
-composer dump-autoload
-
-# Production — builds classmap for all PSR-4/PSR-0 classes
-composer dump-autoload --optimize
-
-# Production with APCu caching (if ext-apcu available)
-composer dump-autoload --optimize --apcu
-```
-
-In production deployments:
-```bash
-composer install --no-dev --optimize-autoloader --no-interaction
-```

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/php-best-practices/references/modern-php.md

@@ -1,363 +0,0 @@
-# Modern PHP Features Reference
-
-## Property Hooks (PHP 8.4)
-
-Property hooks replace magic `__get`/`__set` with type-safe, per-property logic that the engine optimizes.
-
-### Get hooks for computed properties
-
-```php
-<?php declare(strict_types=1);
-
-class Temperature
-{
-    public float $fahrenheit {
-        get => $this->celsius * 9 / 5 + 32;
-    }
-
-    public function __construct(
-        public float $celsius,
-    ) {}
-}
-
-$t = new Temperature(100.0);
-echo $t->fahrenheit; // 212.0
-```
-
-### Set hooks for validation
-
-```php
-<?php declare(strict_types=1);
-
-class UserProfile
-{
-    public string $email {
-        set {
-            if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
-                throw new \InvalidArgumentException("Invalid email: {$value}");
-            }
-            $this->email = strtolower($value);
-        }
-    }
-
-    public int $age {
-        set {
-            if ($value < 0 || $value > 150) {
-                throw new \RangeException("Age must be 0-150, got: {$value}");
-            }
-            $this->age = $value;
-        }
-    }
-
-    public function __construct(string $email, int $age)
-    {
-        $this->email = $email;
-        $this->age = $age;
-    }
-}
-```
-
-### Get + set combined
-
-```php
-<?php declare(strict_types=1);
-
-class Product
-{
-    private int $priceInCents;
-
-    public float $price {
-        get => $this->priceInCents / 100;
-        set => $this->priceInCents = (int) round($value * 100);
-    }
-}
-```
-
-## Asymmetric Visibility (PHP 8.4)
-
-Control read and write access independently.
-
-```php
-<?php declare(strict_types=1);
-
-class Order
-{
-    // Readable by anyone, writable only by this class
-    public private(set) OrderStatus $status;
-
-    // Readable by anyone, writable by this class and subclasses
-    public protected(set) \DateTimeImmutable $updatedAt;
-
-    public function __construct(
-        public readonly string $id,
-        public readonly string $customerId,
-    ) {
-        $this->status = OrderStatus::Pending;
-        $this->updatedAt = new \DateTimeImmutable();
-    }
-
-    public function confirm(): void
-    {
-        $this->status = OrderStatus::Confirmed;
-        $this->updatedAt = new \DateTimeImmutable();
-    }
-}
-
-// External code:
-$order->status;          // OK — public read
-$order->status = 'x';   // ERROR — private set
-$order->confirm();       // OK — mutates via method
-```
-
-## Enums
-
-### Backed enums
-
-```php
-<?php declare(strict_types=1);
-
-enum Currency: string
-{
-    case USD = 'USD';
-    case EUR = 'EUR';
-    case GBP = 'GBP';
-    case THB = 'THB';
-
-    public function symbol(): string
-    {
-        return match ($this) {
-            self::USD => '$',
-            self::EUR => '€',
-            self::GBP => '£',
-            self::THB => '฿',
-        };
-    }
-
-    public function minorUnits(): int
-    {
-        return match ($this) {
-            self::USD, self::EUR, self::GBP => 2,
-            self::THB => 2,
-        };
-    }
-}
-
-// From string
-$currency = Currency::from('USD');        // throws on invalid
-$currency = Currency::tryFrom('INVALID'); // returns null
-```
-
-### Enums implementing interfaces
-
-```php
-<?php declare(strict_types=1);
-
-interface HasLabel
-{
-    public function label(): string;
-}
-
-enum OrderStatus: string implements HasLabel
-{
-    case Pending = 'pending';
-    case Processing = 'processing';
-    case Shipped = 'shipped';
-    case Delivered = 'delivered';
-
-    public function label(): string
-    {
-        return match ($this) {
-            self::Pending => 'Awaiting Processing',
-            self::Processing => 'Being Prepared',
-            self::Shipped => 'In Transit',
-            self::Delivered => 'Delivered',
-        };
-    }
-
-    /** @return list<self> */
-    public static function activeStatuses(): array
-    {
-        return [self::Pending, self::Processing, self::Shipped];
-    }
-}
-```
-
-### Enum in match expressions
-
-```php
-<?php declare(strict_types=1);
-
-function calculateShippingDays(OrderStatus $status): ?int
-{
-    return match ($status) {
-        OrderStatus::Pending => null,
-        OrderStatus::Processing => 3,
-        OrderStatus::Shipped => 1,
-        OrderStatus::Delivered => 0,
-    };
-}
-```
-
-## Match Expression
-
-`match` is strict-comparison (`===`), returns a value, and requires exhaustive handling.
-
-```php
-<?php declare(strict_types=1);
-
-// Returns a value — no fall-through
-$result = match (true) {
-    $age < 13 => 'child',
-    $age < 18 => 'teen',
-    $age < 65 => 'adult',
-    default => 'senior',
-};
-
-// Multi-condition arms
-$icon = match ($fileType) {
-    'jpg', 'jpeg', 'png', 'gif', 'webp' => 'image',
-    'pdf' => 'document',
-    'mp4', 'webm' => 'video',
-    default => 'file',
-};
-
-// No match throws UnhandledMatchError — forces exhaustive handling
-```
-
-## Named Arguments
-
-```php
-<?php declare(strict_types=1);
-
-// Clarify intent for multi-parameter calls
-$user = new User(
-    name: 'Alice',
-    email: 'alice@example.com',
-    role: Role::Admin,
-    isActive: true,
-);
-
-// Skip optional parameters
-function createNotification(
-    string $message,
-    string $channel = 'email',
-    int $priority = 5,
-    bool $immediate = false,
-): Notification { /* ... */ }
-
-createNotification(
-    message: 'Order shipped',
-    immediate: true,
-    // $channel and $priority use defaults
-);
-```
-
-## First-Class Callable Syntax
-
-```php
-<?php declare(strict_types=1);
-
-// Create closures from existing functions
-$trimmed = array_map(trim(...), $strings);
-
-// Works with methods
-$names = array_map($user->getName(...), $users);
-
-// Works with static methods
-$filtered = array_filter($items, Product::isActive(...));
-```
-
-## Readonly Classes
-
-```php
-<?php declare(strict_types=1);
-
-// All properties are implicitly readonly
-readonly class Address
-{
-    public function __construct(
-        public string $street,
-        public string $city,
-        public string $state,
-        public string $zip,
-        public string $country,
-    ) {}
-
-    public function withCity(string $city): self
-    {
-        // Immutable — return new instance
-        return new self(
-            street: $this->street,
-            city: $city,
-            state: $this->state,
-            zip: $this->zip,
-            country: $this->country,
-        );
-    }
-}
-```
-
-## Fibers
-
-Fibers provide cooperative multitasking — suspend and resume execution at explicit points.
-
-```php
-<?php declare(strict_types=1);
-
-// Low-level fiber usage (prefer libraries like Revolt/AMPHP)
-$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'
-```
-
-### Practical use: async I/O with Revolt event loop
-
-```php
-<?php declare(strict_types=1);
-
-use Revolt\EventLoop;
-
-// Non-blocking HTTP fetch
-function fetchAsync(string $url): string
-{
-    $suspension = EventLoop::getSuspension();
-
-    $client = new HttpClient();
-    $client->requestAsync($url, function (string $body) use ($suspension) {
-        $suspension->resume($body);
-    });
-
-    return $suspension->suspend(); // Fiber suspends until response arrives
-}
-
-// Both fetches run concurrently on the event loop
-EventLoop::queue(function () {
-    $users = fetchAsync('https://api.example.com/users');
-    $orders = fetchAsync('https://api.example.com/orders');
-    processData($users, $orders);
-});
-
-EventLoop::run();
-```
-
-## DNF Types (Disjunctive Normal Form)
-
-Combine union and intersection types:
-
-```php
-<?php declare(strict_types=1);
-
-// (A&B)|C — type must be (both A and B) or C
-function process((Countable&Iterator)|array $input): int
-{
-    if (is_array($input)) {
-        return count($input);
-    }
-    return $input->count();
-}
-```