Skip to content
Skills Library
Programming · Building & coding

php-conventions

/php-conventions

Modern PHP idioms for any PHP project (PHP 8.1+): readonly properties, enums, match expressions, constructor property promotion, typed properties, named arguments, nullsafe operator, first-class callable syntax, strict_types, PSR-12 style, and null discipline. Apply when the project is a PHP 8.1+ project. Stack-agnostic — referenced by every PHP plugin in the marketplace. Use this skill to: - Write strongly-typed, immutable-by-default value objects with readonly properties and enums. - Replace switch ladders and magic constants with match expressions and backed enums. - Cut constructor boilerp

Repository
claude-sdlc ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

87/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability17 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Modern PHP idioms for any PHP project (PHP 8.1+): readonly properties, enums, match expressions, constructor property promotion, typed properties, named arguments, nullsafe operator, first-class callable syntax, strict_types, PSR-12 style, and null discipline. Apply when the project is a PHP 8.1+ project. Stack-agnostic — referenced by every PHP plugin in the marketplace. Use this skill to: - Write strongly-typed, immutable-by-default value objects with readonly properties and enums. - Replace switch ladders and magic constants with match expressions and backed enums. - Cut constructor boilerp

Original author description

Modern PHP idioms for any PHP project (PHP 8.1+): readonly properties, enums, match expressions, constructor property promotion, typed properties, named arguments, nullsafe operator, first-class callable syntax, strict_types, PSR-12 style, and null discipline. Apply when the project is a PHP 8.1+ project. Stack-agnostic — referenced by every PHP plugin in the marketplace. Use this skill to: - Write strongly-typed, immutable-by-default value objects with readonly properties and enums. - Replace switch ladders and magic constants with match expressions and backed enums. - Cut constructor boilerp

How it works

  1. Detection
  2. stricttypes — always on
  3. Constructor property promotion
  4. readonly properties — immutability by default
  5. Enums — replace magic constants
  6. match — exhaustive, type-safe branching
  7. Typed properties, parameters, and returns
  8. Nullsafe operator and null discipline
  9. Named arguments
  10. First-class callable syntax
Original SKILL.md headings · 197 lines, 784 words
SKILL.md preview
---
name: php-conventions
description: |
  Modern PHP idioms for any PHP project (PHP 8.1+): readonly properties, enums, match expressions, constructor property promotion, typed properties, named arguments, nullsafe operator, first-class callable syntax, strict_types, PSR-12 style, and null discipline. Apply when the project is a PHP 8.1+ project. Stack-agnostic — referenced by every PHP plugin in the marketplace.

  Use this skill to:
  - Write strongly-typed, immutable-by-default value objects with readonly properties and enums.
  - Replace switch ladders and magic constants with match expressions and backed enums.
  - Cut constructor boilerplate with property promotion and express optionality with typed nullable returns.
  - Keep code PSR-12 compliant with declare(strict_types=1) in every file.

  Do NOT use this skill for:
  - Framework-specific idioms (Eloquent, Doctrine, Symfony services, Laravel facades — those live in framework plugin skills).
  - Composer / autoloading / dependency management — see php-foundation:composer-tooling.
  - Testing patterns — see php-foundation:php-testing.
user-invocable: false
paths: ["**/*.php"]
---

# 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-plugin:laravel-conventions`, `symfony-plugin: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
<?php

declare(strict_types=1);

namespace App\Domain;
```

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

## Constructor property promotion

Collapse the declare/assign boilerplate into the signature.

```php
// 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

```php
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

Use backed enums for closed sets of values; attach behaviour with methods.

```php
enum Status: string
{
    case Draft = 'draft';
    case Active = 'active';
    case Archived = 'archived';

    public function isPublished(): bool
    {
        return $this === self::Active;
    }

    public function label(): string
    {
        return match ($this) {
            self::Draft => 'Draft',
            self::Active => 'Active',
            self::Archived => 'Archived',
        };
    }
}

$status = Status::from('active');        // throws ValueError on unknown
$maybe = Status::tryFrom($input);        // null on unknown
```

Never model a closed set with bare string constants or class `const` lists when a backed enum fits.

## match — exhaustive, type-safe branching

```php
$discount = match (true) {
    $total >= 1000 => 0.15,
    $total >= 500  => 0.10,
    $total >= 100  => 0.05,
    default        => 0.0,
};
```

`match` uses strict comparison (`===`), has no fallthrough, and throws `UnhandledMatchError` if nothing matches and no `default` is present — far safer than `switch`.

## Typed properties, parameters, and returns

```php
final class UserService
{
    public function findById(int $id): ?User      // explicit nullable return
    {
        return $this->repository->find($id);
    }

    /** @return list<User> */
    public function active(): array                // PHPDoc narrows array element type
    {
        return $this->repository->whereActive();
    }
}
```

- Type every parameter, property, and return value. Use `?T` for nullable, union types (`int|string`) where genuinely needed.
- PHP has no generics — use PHPDoc (`list<T>`, `array<K, V>`) so static analysers (PHPStan/Psalm) can check element types.

## Nullsafe operator and null discipline

```php
$country = $order?->customer?->address?->country;   // short-circuits to null

// Validate at boundaries instead of propagating null
public function charge(Customer $customer): void
{
    $card = $customer->defaultCard()
        ?? throw new NoPaymentMethodException($customer->id);
    // ...
}
```

- Do not return `null` to signal errors from public methods — throw a domain exception or return an empty collection.
- Use the nullsafe operator for optional read chains, not to hide missing required data.

## Named arguments

```php
$response = $client->request(
    method: 'POST',
    uri: '/orders',
    options: ['json' => $payload],
);
```

Use named arguments to clarify boolean/optional parameters at the call site. Do not reorder — pass them in declaration order for readability.

## First-class callable syntax

```php
$names = array_map(strtoupper(...), $words);
$ids = array_map($user->id(...), $users);
```

Prefer `$callable(...)` over string callable names or array `[$obj, 'method']` forms.

## Code style — PSR-12

- 4-space indentation, no tabs. One class per file. Files use `<?php` (no closing `?>`).
- `final` by default; open for extension only when designed for it.
- Single quotes for strings without interpolation.
- One blank line between methods; trailing comma in multi-line arrays/arguments.
- Run a formatter (the active framework plugin provides a Stop hook — Laravel Pint or PHP-CS-Fixer with the `@PSR12` / `@Symfony` ruleset). Do not hand-tune whitespace the formatter owns.

## Class design rules

- Single Responsibility: one reason to change per class.
- Prefer composition over inheritance; keep inheritance trees shallow.
- Keep the public API minimal — `private`/`protected` by default, `public` only when needed.
- Define contracts with `interface`; depend on abstractions, not concretions.
- Avoid static state. Pure static helpers for stateless functions are acceptable.

Versions

The database has no other skills named php-conventions.

Database snapshot: 13.11.2026 · package version a23e8630dd9a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100php-idioms
    Modern PHP 8.x idioms: strict types, typed properties, enums, readonly classes, match expressions, and PSR standards. Use when writing, refactoring, or reviewing pure PHP code, domain services, or libraries. Pair with laravel-idioms for Laravel applications.
  • 100php-modern
    Write modern PHP 8.x code — typed properties, enums, readonly classes, match expressions, named arguments, union/intersection types, fibers, attributes, and constructor promotion. Use when writing PHP for WooCommerce or any PHP 8.x project.
  • 100php-modern
    Write modern PHP 8.x code — typed properties, enums, readonly classes, match expressions, named arguments, union/intersection types, fibers, attributes, and constructor promotion. Use when writing PHP for Magento or any PHP 8.x project.
  • 100php-language
    Apply core PHP language standards and modern 8.x features. Use when working with PHP 8.x features like enums, fibers, readonly properties, or named arguments.
  • 85PHP Modern Features
    Use when modern PHP features including typed properties, union types, match expressions, named arguments, attributes, enums, and patterns for writing type-safe, expressive PHP code with latest language improvements.
  • 100php-language-modern
    Use when writing modern non-framework PHP 8.1-8.5 — property hooks, asymmetric visibility, pipe operator, attributes, enums, readonly. Do NOT use for style (php-standards) or Laravel.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.