@hivehub/rulebook 5.5.2 → 5.8.0

package/templates/languages/PHP.md

@@ -1,416 +1,416 @@
-<!-- PHP:START -->
-# PHP Project Rules
-
-## Agent Automation Commands
-
-**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
-
-```bash
-# Complete quality check sequence:
-./vendor/bin/pint --test  # Format check (Laravel Pint)
-# OR: ./vendor/bin/php-cs-fixer fix --dry-run
-./vendor/bin/phpstan analyze  # Static analysis
-./vendor/bin/phpunit      # All tests (100% pass)
-./vendor/bin/phpunit --coverage-text  # Coverage (95%+ required)
-
-# Security audit:
-composer audit            # Vulnerability scan
-composer outdated         # Check outdated deps
-```
-
-## PHP Configuration
-
-**CRITICAL**: Use PHP 8.2+ with strict types enabled.
-
-- **Version**: PHP 8.2+
-- **Strict Types**: Enabled
-- **Type Hints**: Required for all functions
-- **Error Reporting**: E_ALL | E_STRICT
-
-### composer.json Requirements
-
-```json
-{
-  "name": "your-vendor/your-package",
-  "description": "A short description of your package",
-  "type": "library",
-  "license": "MIT",
-  "authors": [
-    {
-      "name": "Your Name",
-      "email": "your.email@example.com"
-    }
-  ],
-  "require": {
-    "php": "^8.2"
-  },
-  "require-dev": {
-    "phpunit/phpunit": "^11.0",
-    "phpstan/phpstan": "^1.10",
-    "squizlabs/php_codesniffer": "^3.8",
-    "friendsofphp/php-cs-fixer": "^3.48"
-  },
-  "autoload": {
-    "psr-4": {
-      "YourVendor\\YourPackage\\": "src/"
-    }
-  },
-  "autoload-dev": {
-    "psr-4": {
-      "YourVendor\\YourPackage\\Tests\\": "tests/"
-    }
-  },
-  "scripts": {
-    "test": "phpunit",
-    "cs-fix": "php-cs-fixer fix",
-    "cs-check": "php-cs-fixer fix --dry-run --diff",
-    "stan": "phpstan analyse",
-    "phpcs": "phpcs src tests"
-  },
-  "minimum-stability": "stable",
-  "prefer-stable": true
-}
-```
-
-## Code Quality Standards
-
-### Mandatory Quality Checks
-
-**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
-
-**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
-
-```bash
-# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
-
-# 1. Format check (matches workflow - use check, not fix!)
-composer cs-check
-
-# 2. Static analysis (MUST pass with no errors - matches workflow)
-composer stan
-
-# 3. Code style check (matches workflow)
-composer phpcs
-
-# 4. Run all tests (MUST pass 100% - matches workflow)
-composer test
-
-# 5. Check coverage (MUST meet threshold)
-./vendor/bin/phpunit --coverage-text
-
-# If ANY fails: ❌ DO NOT COMMIT - Fix first!
-```
-
-**If ANY of these fail, you MUST fix the issues before committing.**
-
-**Why This Matters:**
-- CI/CD failures happen when local commands differ from workflows
-- Example: Using `cs-fix` locally but `cs-check` in CI = failure
-- Example: Missing static analysis locally = CI PHPStan failures
-
-### Code Style
-
-Use PHP-CS-Fixer with PSR-12 standard. Configuration in `.php-cs-fixer.php`:
-
-```php
-<?php
-
-declare(strict_types=1);
-
-$finder = PhpCsFixer\Finder::create()
-    ->in(__DIR__ . '/src')
-    ->in(__DIR__ . '/tests');
-
-return (new PhpCsFixer\Config())
-    ->setRules([
-        '@PSR12' => true,
-        '@PHP82Migration' => true,
-        'strict_param' => true,
-        'array_syntax' => ['syntax' => 'short'],
-        'declare_strict_types' => true,
-        'native_function_invocation' => ['include' => ['@all']],
-        'no_unused_imports' => true,
-        'ordered_imports' => ['sort_algorithm' => 'alpha'],
-        'phpdoc_align' => true,
-        'phpdoc_order' => true,
-        'trailing_comma_in_multiline' => ['elements' => ['arrays']],
-    ])
-    ->setFinder($finder);
-```
-
-### Static Analysis
-
-Use PHPStan at maximum level. Configuration in `phpstan.neon`:
-
-```neon
-parameters:
-    level: max
-    paths:
-        - src
-        - tests
-    excludePaths:
-        - tests/Fixtures/*
-    checkMissingIterableValueType: true
-    checkGenericClassInNonGenericObjectType: true
-    reportUnmatchedIgnoredErrors: true
-```
-
-### Testing
-
-- **Framework**: PHPUnit 11+
-- **Location**: `tests/` directory
-- **Coverage**: XDebug or PCOV
-- **Coverage Threshold**: 95%+
-
-Configuration in `phpunit.xml`:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
-         bootstrap="vendor/autoload.php"
-         colors="true"
-         failOnRisky="true"
-         failOnWarning="true"
-         cacheDirectory=".phpunit.cache">
-    <testsuites>
-        <testsuite name="Unit">
-            <directory>tests/Unit</directory>
-        </testsuite>
-        <testsuite name="Integration">
-            <directory>tests/Integration</directory>
-        </testsuite>
-    </testsuites>
-    <source>
-        <include>
-            <directory>src</directory>
-        </include>
-    </source>
-    <coverage>
-        <report>
-            <html outputDirectory="coverage"/>
-            <text outputFile="php://stdout"/>
-        </report>
-    </coverage>
-</phpunit>
-```
-
-Example test:
-
-```php
-<?php
-
-declare(strict_types=1);
-
-namespace YourVendor\YourPackage\Tests;
-
-use PHPUnit\Framework\TestCase;
-use YourVendor\YourPackage\MyClass;
-
-final class MyClassTest extends TestCase
-{
-    public function testProcessValidInput(): void
-    {
-        $myClass = new MyClass();
-        $result = $myClass->process('hello');
-        
-        $this->assertSame('HELLO', $result);
-    }
-
-    public function testProcessEmptyInputThrowsException(): void
-    {
-        $this->expectException(\InvalidArgumentException::class);
-        $this->expectExceptionMessage('Input cannot be empty');
-        
-        $myClass = new MyClass();
-        $myClass->process('');
-    }
-}
-```
-
-### Type Declarations
-
-- Use strict types in all files
-- Type hint all parameters and return types
-- Use union types and nullable types appropriately
-
-Example:
-
-```php
-<?php
-
-declare(strict_types=1);
-
-namespace YourVendor\YourPackage;
-
-use InvalidArgumentException;
-
-final class DataProcessor
-{
-    /**
-     * Process the input data and return the result.
-     *
-     * @param string $input The input to process
-     * @return string The processed output
-     * @throws InvalidArgumentException If input is empty
-     */
-    public function process(string $input): string
-    {
-        if ($input === '') {
-            throw new InvalidArgumentException('Input cannot be empty');
-        }
-
-        return strtoupper($input);
-    }
-
-    /**
-     * Find a value in the data.
-     *
-     * @param array<string, mixed> $data
-     * @param string $key
-     * @return mixed|null
-     */
-    public function findValue(array $data, string $key): mixed
-    {
-        return $data[$key] ?? null;
-    }
-
-    /**
-     * Process multiple items.
-     *
-     * @param list<string> $items
-     * @return list<string>
-     */
-    public function processMany(array $items): array
-    {
-        return array_map(
-            fn (string $item): string => $this->process($item),
-            $items
-        );
-    }
-}
-```
-
-## Documentation
-
-- Use PHPDoc blocks for all public methods
-- Include `@param`, `@return`, `@throws` tags
-- Use generics annotations for arrays
-
-Example:
-
-```php
-<?php
-
-declare(strict_types=1);
-
-namespace YourVendor\YourPackage;
-
-/**
- * Service for managing user data.
- *
- * This class provides methods for creating, updating, and retrieving user information.
- */
-final class UserService
-{
-    /**
-     * Find a user by ID.
-     *
-     * @param positive-int $userId The user ID
-     * @return array{id: int, name: string, email: string}|null User data or null if not found
-     */
-    public function findById(int $userId): ?array
-    {
-        // Implementation
-    }
-
-    /**
-     * Get all users.
-     *
-     * @return list<array{id: int, name: string, email: string}>
-     */
-    public function getAll(): array
-    {
-        // Implementation
-    }
-}
-```
-
-## Project Structure
-
-```
-project/
-├── composer.json           # Composer configuration
-├── phpunit.xml             # PHPUnit configuration
-├── phpstan.neon            # PHPStan configuration
-├── .php-cs-fixer.php       # PHP-CS-Fixer configuration
-├── README.md               # Project overview (allowed in root)
-├── CHANGELOG.md            # Version history (allowed in root)
-├── LICENSE                 # Project license (allowed in root)
-├── src/
-│   └── YourClass.php
-├── tests/
-│   ├── Unit/
-│   └── Integration/
-└── docs/                   # Project documentation
-```
-
-## CI/CD Requirements
-
-Must include GitHub Actions workflows for:
-
-1. **Testing** (`php-test.yml`):
-   - Test on ubuntu-latest, windows-latest
-   - Test on PHP 8.2, 8.3
-   - Upload coverage reports
-
-2. **Linting** (`php-lint.yml`):
-   - PHPStan: `composer stan`
-   - PHP-CS-Fixer: `composer cs-check`
-   - PHPCS: `composer phpcs`
-
-## Package Publication
-
-### Publishing to Packagist
-
-**Prerequisites:**
-1. Create account at https://packagist.org
-2. Submit your package (automatic sync with GitHub)
-3. Configure webhook in GitHub for auto-updates
-
-**Publishing Workflow:**
-
-1. Update version in composer.json (optional, uses git tags)
-2. Update CHANGELOG.md
-3. Run quality checks:
-   ```bash
-   composer cs-fix
-   composer stan
-   composer test
-   ```
-
-4. Create git tag: `git tag v1.0.0 && git push --tags`
-5. Packagist automatically updates from GitHub
-6. Package available at: `https://packagist.org/packages/your-vendor/your-package`
-
-**Publishing Checklist:**
-
-- ✅ All tests passing
-- ✅ PHPStan at max level passes
-- ✅ Code style conforms to PSR-12
-- ✅ CHANGELOG.md updated
-- ✅ README.md up to date
-- ✅ LICENSE file present
-- ✅ composer.json metadata complete
-- ✅ GitHub repository public
-- ✅ Webhook configured on Packagist
-
-**Semantic Versioning:**
-
-Packagist uses git tags for versions:
-- Tag format: `v1.0.0`
-- Follows [SemVer](https://semver.org/)
-- Composer constraints: `^1.0`, `~1.0`, `1.0.*`
-
-<!-- PHP:END -->
-
+<!-- PHP:START -->
+# PHP Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+./vendor/bin/pint --test  # Format check (Laravel Pint)
+# OR: ./vendor/bin/php-cs-fixer fix --dry-run
+./vendor/bin/phpstan analyze  # Static analysis
+./vendor/bin/phpunit      # All tests (100% pass)
+./vendor/bin/phpunit --coverage-text  # Coverage (95%+ required)
+
+# Security audit:
+composer audit            # Vulnerability scan
+composer outdated         # Check outdated deps
+```
+
+## PHP Configuration
+
+**CRITICAL**: Use PHP 8.2+ with strict types enabled.
+
+- **Version**: PHP 8.2+
+- **Strict Types**: Enabled
+- **Type Hints**: Required for all functions
+- **Error Reporting**: E_ALL | E_STRICT
+
+### composer.json Requirements
+
+```json
+{
+  "name": "your-vendor/your-package",
+  "description": "A short description of your package",
+  "type": "library",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Your Name",
+      "email": "your.email@example.com"
+    }
+  ],
+  "require": {
+    "php": "^8.2"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^11.0",
+    "phpstan/phpstan": "^1.10",
+    "squizlabs/php_codesniffer": "^3.8",
+    "friendsofphp/php-cs-fixer": "^3.48"
+  },
+  "autoload": {
+    "psr-4": {
+      "YourVendor\\YourPackage\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "YourVendor\\YourPackage\\Tests\\": "tests/"
+    }
+  },
+  "scripts": {
+    "test": "phpunit",
+    "cs-fix": "php-cs-fixer fix",
+    "cs-check": "php-cs-fixer fix --dry-run --diff",
+    "stan": "phpstan analyse",
+    "phpcs": "phpcs src tests"
+  },
+  "minimum-stability": "stable",
+  "prefer-stable": true
+}
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Format check (matches workflow - use check, not fix!)
+composer cs-check
+
+# 2. Static analysis (MUST pass with no errors - matches workflow)
+composer stan
+
+# 3. Code style check (matches workflow)
+composer phpcs
+
+# 4. Run all tests (MUST pass 100% - matches workflow)
+composer test
+
+# 5. Check coverage (MUST meet threshold)
+./vendor/bin/phpunit --coverage-text
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- CI/CD failures happen when local commands differ from workflows
+- Example: Using `cs-fix` locally but `cs-check` in CI = failure
+- Example: Missing static analysis locally = CI PHPStan failures
+
+### Code Style
+
+Use PHP-CS-Fixer with PSR-12 standard. Configuration in `.php-cs-fixer.php`:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+$finder = PhpCsFixer\Finder::create()
+    ->in(__DIR__ . '/src')
+    ->in(__DIR__ . '/tests');
+
+return (new PhpCsFixer\Config())
+    ->setRules([
+        '@PSR12' => true,
+        '@PHP82Migration' => true,
+        'strict_param' => true,
+        'array_syntax' => ['syntax' => 'short'],
+        'declare_strict_types' => true,
+        'native_function_invocation' => ['include' => ['@all']],
+        'no_unused_imports' => true,
+        'ordered_imports' => ['sort_algorithm' => 'alpha'],
+        'phpdoc_align' => true,
+        'phpdoc_order' => true,
+        'trailing_comma_in_multiline' => ['elements' => ['arrays']],
+    ])
+    ->setFinder($finder);
+```
+
+### Static Analysis
+
+Use PHPStan at maximum level. Configuration in `phpstan.neon`:
+
+```neon
+parameters:
+    level: max
+    paths:
+        - src
+        - tests
+    excludePaths:
+        - tests/Fixtures/*
+    checkMissingIterableValueType: true
+    checkGenericClassInNonGenericObjectType: true
+    reportUnmatchedIgnoredErrors: true
+```
+
+### Testing
+
+- **Framework**: PHPUnit 11+
+- **Location**: `tests/` directory
+- **Coverage**: XDebug or PCOV
+- **Coverage Threshold**: 95%+
+
+Configuration in `phpunit.xml`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         failOnRisky="true"
+         failOnWarning="true"
+         cacheDirectory=".phpunit.cache">
+    <testsuites>
+        <testsuite name="Unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+        <testsuite name="Integration">
+            <directory>tests/Integration</directory>
+        </testsuite>
+    </testsuites>
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+    <coverage>
+        <report>
+            <html outputDirectory="coverage"/>
+            <text outputFile="php://stdout"/>
+        </report>
+    </coverage>
+</phpunit>
+```
+
+Example test:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourVendor\YourPackage\Tests;
+
+use PHPUnit\Framework\TestCase;
+use YourVendor\YourPackage\MyClass;
+
+final class MyClassTest extends TestCase
+{
+    public function testProcessValidInput(): void
+    {
+        $myClass = new MyClass();
+        $result = $myClass->process('hello');
+        
+        $this->assertSame('HELLO', $result);
+    }
+
+    public function testProcessEmptyInputThrowsException(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Input cannot be empty');
+        
+        $myClass = new MyClass();
+        $myClass->process('');
+    }
+}
+```
+
+### Type Declarations
+
+- Use strict types in all files
+- Type hint all parameters and return types
+- Use union types and nullable types appropriately
+
+Example:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourVendor\YourPackage;
+
+use InvalidArgumentException;
+
+final class DataProcessor
+{
+    /**
+     * Process the input data and return the result.
+     *
+     * @param string $input The input to process
+     * @return string The processed output
+     * @throws InvalidArgumentException If input is empty
+     */
+    public function process(string $input): string
+    {
+        if ($input === '') {
+            throw new InvalidArgumentException('Input cannot be empty');
+        }
+
+        return strtoupper($input);
+    }
+
+    /**
+     * Find a value in the data.
+     *
+     * @param array<string, mixed> $data
+     * @param string $key
+     * @return mixed|null
+     */
+    public function findValue(array $data, string $key): mixed
+    {
+        return $data[$key] ?? null;
+    }
+
+    /**
+     * Process multiple items.
+     *
+     * @param list<string> $items
+     * @return list<string>
+     */
+    public function processMany(array $items): array
+    {
+        return array_map(
+            fn (string $item): string => $this->process($item),
+            $items
+        );
+    }
+}
+```
+
+## Documentation
+
+- Use PHPDoc blocks for all public methods
+- Include `@param`, `@return`, `@throws` tags
+- Use generics annotations for arrays
+
+Example:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourVendor\YourPackage;
+
+/**
+ * Service for managing user data.
+ *
+ * This class provides methods for creating, updating, and retrieving user information.
+ */
+final class UserService
+{
+    /**
+     * Find a user by ID.
+     *
+     * @param positive-int $userId The user ID
+     * @return array{id: int, name: string, email: string}|null User data or null if not found
+     */
+    public function findById(int $userId): ?array
+    {
+        // Implementation
+    }
+
+    /**
+     * Get all users.
+     *
+     * @return list<array{id: int, name: string, email: string}>
+     */
+    public function getAll(): array
+    {
+        // Implementation
+    }
+}
+```
+
+## Project Structure
+
+```
+project/
+├── composer.json           # Composer configuration
+├── phpunit.xml             # PHPUnit configuration
+├── phpstan.neon            # PHPStan configuration
+├── .php-cs-fixer.php       # PHP-CS-Fixer configuration
+├── README.md               # Project overview (allowed in root)
+├── CHANGELOG.md            # Version history (allowed in root)
+├── LICENSE                 # Project license (allowed in root)
+├── src/
+│   └── YourClass.php
+├── tests/
+│   ├── Unit/
+│   └── Integration/
+└── docs/                   # Project documentation
+```
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows for:
+
+1. **Testing** (`php-test.yml`):
+   - Test on ubuntu-latest, windows-latest
+   - Test on PHP 8.2, 8.3
+   - Upload coverage reports
+
+2. **Linting** (`php-lint.yml`):
+   - PHPStan: `composer stan`
+   - PHP-CS-Fixer: `composer cs-check`
+   - PHPCS: `composer phpcs`
+
+## Package Publication
+
+### Publishing to Packagist
+
+**Prerequisites:**
+1. Create account at https://packagist.org
+2. Submit your package (automatic sync with GitHub)
+3. Configure webhook in GitHub for auto-updates
+
+**Publishing Workflow:**
+
+1. Update version in composer.json (optional, uses git tags)
+2. Update CHANGELOG.md
+3. Run quality checks:
+   ```bash
+   composer cs-fix
+   composer stan
+   composer test
+   ```
+
+4. Create git tag: `git tag v1.0.0 && git push --tags`
+5. Packagist automatically updates from GitHub
+6. Package available at: `https://packagist.org/packages/your-vendor/your-package`
+
+**Publishing Checklist:**
+
+- ✅ All tests passing
+- ✅ PHPStan at max level passes
+- ✅ Code style conforms to PSR-12
+- ✅ CHANGELOG.md updated
+- ✅ README.md up to date
+- ✅ LICENSE file present
+- ✅ composer.json metadata complete
+- ✅ GitHub repository public
+- ✅ Webhook configured on Packagist
+
+**Semantic Versioning:**
+
+Packagist uses git tags for versions:
+- Tag format: `v1.0.0`
+- Follows [SemVer](https://semver.org/)
+- Composer constraints: `^1.0`, `~1.0`, `1.0.*`
+
+<!-- PHP:END -->
+