PHP Patterns

PHP Patterns

When to Use

Writing or reviewing modern PHP (8.1+) code: value objects, domain models, framework-agnostic services, or any PHP file that should use current language features instead of PHP 5/7 idioms.

Core Patterns

Strict Types and Typed Properties

Always declare strict_types and type every property, parameter, and return value.

<?php

declare(strict_types=1);

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

    public function add(Money $other): self
    {
        if ($this->currency !== $other->currency) {
            throw new InvalidArgumentException('Currency mismatch');
        }

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

Enums Instead of Class Constants

enum OrderStatus: string
{
    case Pending = 'pending';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function isTerminal(): bool
    {
        return match ($this) {
            self::Shipped, self::Cancelled => true,
            self::Pending => false,
        };
    }
}

$status = OrderStatus::from($request->get('status'));

match() Over switch

match is an expression, uses strict comparison, and has no fallthrough.

$discount = match (true) {
    $total >= 10_000 => 0.15,
    $total >= 5_000  => 0.10,
    $total >= 1_000  => 0.05,
    default          => 0.0,
};

Readonly Value Objects

Prefer immutable value objects over mutable DTOs — build a new instance instead of setters.

final class Address
{
    public function __construct(
        public readonly string $street,
        public readonly string $city,
        public readonly string $postalCode,
    ) {
    }

    public function withCity(string $city): self
    {
        return new self($this->street, $city, $this->postalCode);
    }
}

Nullsafe and First-Class Callables

// Nullsafe chaining — short-circuits to null instead of throwing
$city = $order?->customer?->address?->city;

// First-class callable syntax (PHP 8.1+) instead of string/array callables
$mapped = array_map(strtoupper(...), $names);
$validator = $this->validateEmail(...);

Attributes Instead of Docblock Annotations

#[Route('/orders/{id}', methods: ['GET'])]
final class ShowOrderController
{
    public function __invoke(#[CurrentUser] User $user, string $id): Response
    {
        // ...
    }
}

Checklist

• declare(strict_types=1) at the top of every file
• All classes final unless explicitly designed for extension
• Constructor property promotion used instead of manual assignment
• Value objects are readonly
• No array type hints where a typed DTO/enum would be clearer
• match used instead of switch for value mapping
• Named arguments used for functions with 3+ parameters of the same type

Anti-Patterns

// BAD: mutable public properties, no types
class User {
    public $name;
    public $email;
}

// GOOD: readonly, typed, validated at construction
final class User
{
    public function __construct(
        public readonly string $name,
        public readonly string $email,
    ) {
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException("Invalid email: {$email}");
        }
    }
}

// BAD: array as ad-hoc struct
function createOrder(array $data): array { /* ... */ }

// GOOD: typed input/output
function createOrder(CreateOrderRequest $request): Order { /* ... */ }

Quick Reference

See Also

• skills/php-ecosystem/laravel-patterns.md
• skills/php-ecosystem/php-testing.md
• skills/php-ecosystem/php-security.md