php-guide

name	php-guide
description	PHP language guardrails, patterns, and best practices for AI-assisted development. Use when working with PHP files (.php), composer.json, or when the user mentions PHP. Provides type declaration patterns, Composer conventions, PSR standards, and testing guidelines specific to this project's coding standards.
license	MIT
metadata	{"author":"samuel","version":"1.0","category":"language","language":"php","extensions":".php"}

PHP Guide

Applies to: PHP 8.1+, Web Applications, APIs, CLIs, Microservices

Core Principles

1. Strict Types Always: Every PHP file starts with declare(strict_types=1)
2. Type Declarations Everywhere: All parameters, return types, and properties must have type declarations
3. PSR Standards: Follow PSR-12 coding standard, PSR-4 autoloading, PSR-7 HTTP messages
4. Composition Over Inheritance: Prefer interfaces, traits, and dependency injection over deep class hierarchies
5. Modern PHP First: Use PHP 8.1+ features (enums, readonly properties, fibers, named arguments, match expressions)

Guardrails

Version & Dependencies

• Target PHP 8.1+ (enums, readonly properties, fibers, intersection types)
• Define all dependencies in composer.json with version constraints
• Run composer validate and composer audit before committing
• Use composer.lock for applications (commit it), omit for libraries
• Separate require-dev for development-only dependencies
• Never use composer update in production (use composer install --no-dev)

Code Style (PSR-12)

• Run PHP-CS-Fixer or PHP_CodeSniffer before every commit
• Naming: PascalCase classes/enums, camelCase methods/properties, UPPER_SNAKE constants
• One class per file, file name matches class name
• Opening braces on same line for control structures, next line for classes/methods
• declare(strict_types=1) as first statement after <?php in every file
• No closing ?> tag in pure PHP files
• Imports: one use per declaration, grouped (classes, functions, constants), alphabetized

<?php

declare(strict_types=1);

namespace App\Domain\User;

use App\Domain\Exception\ValidationException;
use App\Domain\ValueObject\Email;

final class UserService
{
    public function __construct(
        private readonly UserRepositoryInterface $repository,
        private readonly EventDispatcherInterface $dispatcher,
    ) {}

    public function register(string $name, string $email): User
    {
        $emailVO = Email::fromString($email);

        if ($this->repository->existsByEmail($emailVO)) {
            throw ValidationException::duplicateEmail($email);
        }

         = ::(: , : );
        ->repository->();
        ->dispatcher->( (->id));

         ;
    }
}

Type Declarations

• All function parameters MUST have type declarations
• All methods MUST declare return types (including void)
• Use union types (string|int) instead of mixed when possible
• Use intersection types (Countable&Iterator) for combined type constraints
• Use Type|null for nullable parameters (prefer explicit over ?Type)
• Use never return type for functions that always throw or exit
• Avoid mixed -- if truly needed, document why

Error Handling

• Never use @ error suppression operator
• Convert PHP errors to exceptions with set_error_handler at bootstrap
• Create domain-specific exception hierarchies extending a base exception
• Use specific exception types (not generic \Exception or \RuntimeException)
• Always include context in exception messages
• Catch specific exceptions, never bare catch (\Throwable $e) without re-throwing
• Use previous parameter to chain exceptions

<?php

declare(strict_types=1);

namespace App\Domain\Exception;

abstract class DomainException extends \RuntimeException
{
    public function __construct(
        string $message,
        public readonly string $errorCode = 'UNKNOWN',
        int $code = 0,
        ?\Throwable $previous = null,
    ) {
        parent::__construct($message, $code, $previous);
    }
}

final class NotFoundException extends DomainException
{
    public static function forResource(string $resource, string $id): self
    {
        return new self(
            message: (, , ),
            errorCode: ,
        );
    }
}

Security

• All user input validated before processing (filter functions or validation libraries)
• All SQL queries use prepared statements with bound parameters (PDO or Doctrine DBAL)
• All output escaped for context: htmlspecialchars() for HTML, parameterized for SQL
• All file operations validate paths (realpath() + check against allowed directories)
• Never use eval(), exec(), system(), passthru(), or backtick operator with user input
• Use password_hash() with PASSWORD_ARGON2ID (or PASSWORD_BCRYPT minimum)
• Set session.cookie_httponly, session.cookie_secure, session.cookie_samesite
• Use CSRF tokens for all state-changing requests

Project Structure

myproject/
├── src/                        # Application source (PSR-4: App\)
│   ├── Domain/                 # Business logic, entities, value objects
│   ├── Application/            # Use cases, command/query handlers
│   ├── Infrastructure/         # Framework, database, external services
│   └── Kernel.php
├── tests/
│   ├── Unit/                   # Fast, isolated unit tests
│   ├── Integration/            # Tests with real dependencies
│   └── bootstrap.php
├── config/                     # Configuration files
├── public/                     # Web root (index.php entry point)
├── composer.json
├── composer.lock
├── phpunit.xml
├── phpstan.neon
└── .php-cs-fixer.php

• PSR-4 autoloading: "App\\": "src/" in composer.json
• Domain layer has zero framework dependencies
• Infrastructure implements domain interfaces
• One class per file, directory structure mirrors namespace
• Keep public/ as the web root with a single index.php front controller

Key Patterns

Use PHP 8.1+ features idiomatically:

• Enums: Backed enums with methods for labels, state machines, role-based permissions
• Readonly classes (PHP 8.2+): Value objects, DTOs, Money pattern -- all properties implicitly readonly
• Named arguments: Improve readability for constructors and functions with many parameters
• Match expressions: Prefer over switch -- strict comparison, expression-based, no fallthrough
• Fibers: Cooperative multitasking foundation for async frameworks

Enums (PHP 8.1+)

<?php

declare(strict_types=1);

enum UserRole: string
{
    case Admin = 'admin';
    case Editor = 'editor';
    case Viewer = 'viewer';

    public function label(): string
    {
        return match ($this) {
            self::Admin => 'Administrator',
            self::Editor => 'Editor',
            self::Viewer => 'Viewer',
        };
    }

    /** @return list<Permission> */
    public function permissions(): array
    {
        return match ($this) {
            self::Admin => Permission::cases(),
            self::Editor => [Permission::Read, Permission::Write],
            self:: => [::],
        };
    }
}

Readonly Classes (PHP 8.2+)

<?php

declare(strict_types=1);

readonly class Money
{
    public function __construct(
        public int $amount,
        public string $currency,
    ) {}

    public function add(self $other): self
    {
        if ($this->currency !== $other->currency) {
            throw new \InvalidArgumentException('Cannot add different currencies');
        }

        return new self($this->amount + $other->amount, $this->currency);
    }
}

See references/patterns.md for additional patterns: dependency injection, repository pattern, value objects, command/handler, fibers, match expressions, and tooling configurations.

Testing

Standards

• Test files: *Test.php in tests/ mirroring src/ structure
• Test methods: test_<unit>_<scenario>_<expected> or #[Test] attribute
• PHPUnit as primary framework; Pest as alternative
• Coverage: >80% business logic, >60% overall
• Use data providers for parameterized tests
• Mock external dependencies with Mockery or PHPUnit mocks
• No database or network calls in unit tests
• Each test method tests one behavior

PHPUnit with Data Providers

<?php

declare(strict_types=1);

namespace Tests\Unit\Domain\ValueObject;

use App\Domain\Exception\ValidationException;
use App\Domain\ValueObject\Email;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;

final class EmailTest extends TestCase
{
    #[Test]
    #[DataProvider('validEmailProvider')]
    public function it_accepts_valid_emails(string $input): void
    {
        $email = Email::fromString($input);

        self::assertSame((), ->());
    }

    
      {
          => [];
          => [];
          => [];
          => [];
    }

    
    ()
     {
        ->(::);

        ::();
    }

    
      {
          => [];
          => [];
          => [];
          => [];
          => [];
    }
}

Tooling

Required Dev Dependencies

• phpunit/phpunit ^10.0 -- testing
• phpstan/phpstan ^1.10 -- static analysis (level 8)
• friendsofphp/php-cs-fixer ^3.0 -- code style
• mockery/mockery ^1.6 -- mocking
• vimeo/psalm ^5.0 -- alternative static analysis

PHPStan: Always Level 8

# phpstan.neon
parameters:
    level: 8
    paths:
        - src
    treatPhpDocTypesAsCertain: false
    checkMissingIterableValueType: true

See references/patterns.md for full composer.json, phpstan.neon, and .php-cs-fixer.php configurations.

Essential Commands

composer install              # Install dependencies
composer validate             # Validate composer.json
composer audit                # Check for security vulnerabilities
php vendor/bin/phpunit        # Run all tests
php vendor/bin/phpunit --coverage-text  # With coverage summary
php vendor/bin/phpstan analyse         # Static analysis (level 8)
php vendor/bin/psalm                   # Alternative static analysis
php vendor/bin/php-cs-fixer fix        # Auto-fix code style
php vendor/bin/php-cs-fixer fix --dry-run --diff  # Preview fixes

References

For detailed code examples, see:

• references/patterns.md -- Enum patterns, readonly classes, dependency injection, repository pattern, type declarations, error handling, modern PHP features, mocking, tooling configurations

External References

• PHP: The Right Way
• PSR-12: Extended Coding Style
• PSR-4: Autoloading Standard
• PHPStan Documentation
• PHPUnit Documentation
• Psalm Documentation
• PHP-CS-Fixer Documentation