php-conventions

PHP Conventions (stack-agnostic, PHP 8.1+)

This skill encodes idioms that reduce bugs and improve readability in any PHP codebase. Apply alongside the active framework plugin's conventions skill (e.g., laravel:laravel-conventions, symfony:symfony-conventions).

Detection

Read composer.json first to learn the target PHP version:

• "require": { "php": "^8.1" } (or higher) → all idioms below apply.
• "config": { "platform": { "php": "8.x" } } pins the resolver version.

Match the project's minimum version — do not use PHP 8.2+ features (e.g. readonly classes, DNF types) on an 8.1 project.

strict_types — always on

Every .php file with logic starts with:

<?php

declare(strict_types=1);

namespace App\Domain;

Strict typing turns silent coercions into TypeErrors at the boundary, catching bugs early. The declaration must be the first statement.

Constructor property promotion

Collapse the declare/assign boilerplate into the signature.

// Prefer
final class Money
{
    public function __construct(
        public readonly int $amount,
        public readonly Currency $currency,
    ) {
    }
}

// Avoid — manual field + assignment
final class Money
{
    private int $amount;
    private Currency $currency;

    public function __construct(int $amount, Currency $currency)
    {
        $this->amount = $amount;
        $this->currency = $currency;
    }
}

readonly properties — immutability by default

final class OrderLine
{
    public function __construct(
        public readonly string $sku,
        public readonly int $quantity,
    ) {
    }

    public function withQuantity(int $quantity): self
    {
        return new self($this->sku, $quantity); // return a new instance, never mutate
    }
}

readonly properties can be assigned once (from within the declaring scope) and never again. Use them for value objects and DTOs. On PHP 8.2+ a whole class may be marked readonly.

Enums — replace magic constants