/php

name: php
description: Use when writing PHP 8.2+ or working in Laravel and Symfony codebases. Covers strict types, enums, readonly classes, attributes, PSR standards, and static analysis with PHPStan.
metadata:
  category: languages
  version: 1.0.0
  tags: [php, laravel, symfony, phpstan, psr]

PHP

Purpose

Write PHP that behaves like a typed language: strict types on, enums instead of string constants, readonly value objects, and PHPStan at a level high enough to catch real defects.

When to Use

• Writing or reviewing PHP 8.2+.
• Working in Laravel or Symfony applications.
• Introducing static analysis to a legacy PHP codebase.
• Modeling domain values and states.
• Fixing performance problems in ORM-heavy code.

Capabilities

• Strict typing, union and intersection types, `never` and `readonly`.
• Enums with backing values and interfaces.
• Attributes for routing, validation, and DI metadata.
• PSR-4 autoloading, PSR-12 style, PSR-3 logging.
• PHPStan configuration and incremental adoption via baselines.

Inputs

• Source tree, `composer.json`, framework and version.
• Existing analysis configuration and baseline, if any.

Outputs

• Files opening with `declare(strict_types=1);`.
• Typed properties, parameters, and return types throughout.
• A PHPStan configuration at level 8 (or a baseline plus a plan to reach it).

Workflow

1. **Turn on strictness** — `declare(strict_types=1)` in every file; PHPStan with a baseline to freeze existing debt. 2. **Replace magic with types** — String constants become enums; array shapes become value objects or DTOs. 3. **Implement** — Constructor promotion, readonly properties, named arguments at call sites. 4. **Eliminate ORM traps** — Eager-load relations; never query inside a loop. 5. **Gate** — PHPStan, PHP-CS-Fixer, PHPUnit or Pest.

Best Practices

• Never use `array` as a domain type. An untyped array is a shape that no tool can check.
• Enums replace class constants and give you exhaustive `match`.
• Readonly promoted constructor properties are the shortest path to immutable value objects.
• In Eloquent, `with()` your relations. An N+1 query in a list endpoint is the single most common PHP performance defect.
• Do not catch `\Exception` broadly. Catch the specific type, or let it reach the handler.
• Keep framework types out of the domain layer — a domain service should not know what an HTTP request is.

Examples

**Enum plus readonly value object:**

<?php
declare(strict_types=1);

enum SubscriptionState: string
{
    case Trialing  = 'trialing';
    case Active    = 'active';
    case PastDue   = 'past_due';
    case Cancelled = 'cancelled';

    public function isBillable(): bool
    {
        return match ($this) {
            self::Active, self::PastDue => true,
            self::Trialing, self::Cancelled => false,
        };
    }
}

final readonly class Subscription
{
    public function __construct(
        public string $id,
        public SubscriptionState $state,
        public \DateTimeImmutable $renewsAt,
    ) {}
}

Notes

• PHPStan level 8 adds null-safety checks; it is the level where the tool starts finding real bugs rather than style issues.
• `readonly` classes (8.2) make every property readonly implicitly — a cleaner default for DTOs.
• Laravel's `lazy()` and `chunk()` prevent memory exhaustion on large result sets; `get()` on an unbounded query will eventually take the process down.