hivellm/PHP

<!-- PHP:START -->

PHP Project Rules

Agent Automation Commands

CRITICAL: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).

# 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

{
  "name": "your-vendor/your-package",
  "description": "A short description of your package",
  "type": "library",
  "license": "MIT",
  "authors": [
    {
      "name": "Your Name",
      "email": "[email protected]"
    }
  ],
  "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!

# 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

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:

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 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

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

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

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:

   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
• Composer constraints: ^1.0, ~1.0, 1.0.*

<!-- PHP:END -->