/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. Trigger on "add phpstan to this legacy project", "laravel eloquent is too slow", "upgrade this to php 8 enums and readonly", "add strict types everywhere". Do not use for an injection or auth vulnerability audit — see the security-review skill.
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.