PHP Specialist

Overview

Write modern, type-safe, and maintainable PHP 8.x code adhering to PSR standards and SOLID principles. This skill covers the full modern PHP toolchain: language features introduced in PHP 8.0 through 8.4, PSR interoperability standards, Composer dependency management, static analysis with PHPStan and Psalm, coding style enforcement with PHP CS Fixer and Pint, and architectural patterns that leverage the type system for correctness at compile time rather than runtime.

Apply this skill whenever PHP code is being written, reviewed, or refactored in any framework or standalone context.

Multi-Phase Process

Phase 1: Environment Assessment

1. Identify PHP version from composer.json -> require.php
2. Review composer.json for autoloading strategy (PSR-4 namespaces)
3. Check for static analysis configuration (phpstan.neon, psalm.xml)
4. Identify coding standard tool (pint.json, .php-cs-fixer.php)
5. Catalog existing patterns: enums, DTOs, value objects, interfaces

STOP — Do NOT write code without knowing the PHP version and autoloading strategy.

Phase 2: Design

1. Define interfaces and contracts before implementations
2. Design value objects and DTOs with readonly properties
3. Map domain concepts to backed enums where applicable
4. Plan exception hierarchy for the domain
5. Identify seams for dependency injection

STOP — Do NOT implement without interfaces defined for key boundaries.

Phase 3: Implementation

1. Write interfaces first — contracts before concrete classes
2. Implement with constructor promotion, readonly properties, union/intersection types
3. Use match expressions over switch; named arguments for clarity
4. Leverage first-class callable syntax for functional composition
5. Apply SOLID principles at every class boundary

STOP — Do NOT skip strict_types declaration in any PHP file.

Phase 4: Quality Assurance

1. Run PHPStan at maximum achievable level (target level 9)
2. Enforce coding style with PHP CS Fixer or Laravel Pint
3. Verify type coverage — no mixed without justification
4. Review for SOLID violations and code smells
5. Confirm Composer autoload is optimized (--classmap-authoritative)

PHP Version Feature Decision Table

Modern PHP 8.x Features

Enums (PHP 8.1+)

See REFERENCE.md for code examples.

Readonly Properties and Classes (PHP 8.1 / 8.2)

See REFERENCE.md for code examples.

Constructor Promotion

See REFERENCE.md for code examples.

Named Arguments

See REFERENCE.md for code examples.

Match Expressions

See REFERENCE.md for code examples.

Union and Intersection Types

See REFERENCE.md for code examples.

First-Class Callable Syntax (PHP 8.1+)

See REFERENCE.md for code examples.

Fibers (PHP 8.1+)

See REFERENCE.md for code examples.

PSR Standards

PSR-4 Autoloading

See REFERENCE.md for code examples and the directory-mapping rule.

Composer Dependency Management

Essential Commands

Best Practices

• Always commit composer.lock — reproducible installs across environments
• Use ^ (caret) constraints: "laravel/framework": "^12.0" allows minor/patch updates
• Separate dev dependencies: testing, static analysis, and debug tools go in require-dev
• Run composer audit in CI to catch known vulnerabilities
• Use composer dump-autoload --classmap-authoritative in production for speed

Static Analysis

PHPStan Levels

PHPStan Configuration

See REFERENCE.md for code examples.

PHP CS Fixer / Pint

See REFERENCE.md for code examples.

For Laravel projects, use Pint with a pint.json preset — it wraps PHP CS Fixer with Laravel-specific defaults.

SOLID Principles in PHP

Dependency Inversion Example

See REFERENCE.md for code examples.

Error Handling Patterns

Custom Exception Hierarchy

See REFERENCE.md for code examples.

Result Pattern (Error as Value)

See REFERENCE.md for code examples.

Type Safety Patterns

Branded / Opaque Types via Readonly Classes

See REFERENCE.md for code examples.

Generic Collections via PHPStan Annotations

See REFERENCE.md for code examples.

Anti-Patterns / Common Mistakes

Anti-Rationalization Guards

• Do NOT skip declare(strict_types=1) because "it's just a small script" -- add it everywhere.
• Do NOT use mixed without a comment justifying why a narrower type is impossible.
• Do NOT suppress PHPStan errors without a written explanation of why the code is correct.
• Do NOT use the service locator pattern (app()) in business logic, even in Laravel.
• Do NOT skip interfaces for key boundaries because "there's only one implementation" -- there will be two.

Documentation Lookup (Context7)

Use mcp__context7__resolve-library-id then mcp__context7__query-docs for up-to-date docs. Returned docs override memorized knowledge.

• php — for language features, built-in functions, or PHP 8.x syntax
• composer — for package management, autoloading, or scripts configuration

Integration Points

Skill Type

FLEXIBLE — Adapt the process phases to the scope of work. A single function may need only Phase 3 and 4. A new module or package should follow all four phases. Non-negotiable regardless of scope: declare(strict_types=1), PHPStan compliance at the project's configured level, and PSR-4 autoloading.