php-engineer

# PHP — policy & pitfalls Baseline PHP 8.x knowledge (enums, readonly, match, nullsafe, union/intersection/DNF types, named arguments, first-class callables, fibers, PSR-1/4/12, Composer) is assumed. This skill does not teach the language — it encodes project policy and the traps that keep appearing in code review. ## Setup Check (run first) Before writing non-trivial code: 1. **PHP version** — `composer.json` must declare `"php": ">=8.4"` (or higher). PHP 8.4 is the current active release; 8.3 is in security-only mode (active support ended Dec 2025); 8.2 has security support until Dec 2026 but should not be chosen for new projects. Check `php --version` if running locally. 2. **`declare(strict_types=1);`** at the top of every file. Non-negotiable — without it PHP coerces `"42"` → `42`, `3.7` → `3`, `"abc"` → `0` silently. 3. **Static analysis** — `vendor/bin/phpstan` (target level 8+) and/or `vendor/bin/psalm`. If missing, suggest `composer require --dev phpstan/phpstan`. Run before presenting code. 4. **Formatter** — `vendor/bin/pint` / `php-cs-fixer` / `phpcs`. Respect the existing config; don't introduce new violations. 5. **Lock file** — `composer.lock` must be committed for applications. Never commit `vendor/`. 6. **Framework** — check for `laravel/framework`, `symfony/framework-bundle`, etc. If present, **stop and load the corresponding framework skill** (`laravel-engineer`, etc.); this skill is pure PHP only. ## MUST DO - **Strict types in every file** — `declare(strict_types=1);` on line 1 after `<?php`. - **Type everything** — parameters, return types, property types. Untyped code is an error. - **Backed `enum`** for closed value sets — never `class Status { const ACTIVE = 'active'; }`. - **`readonly` for immutable data** — DTOs, value objects, events. Prefer `readonly class` (PHP 8.2+) over per-property `readonly`. - **`match` over `switch`** — strict comparison (`===`), exhaustive, returns value, throws `UnhandledMatchError` on miss. - **Named arguments for 3+ parameters** — `new UserDto(id: 1, name: 'n', email: 'e')` prevents silent argument swaps. - **Constructor property promotion** — no separate property declarations + manual assignments. - **`DateTimeImmutable`** — never `DateTime`; the mutable one causes aliasing bugs. - **Prepared statements** for every SQL query reaching user input. Bind with named or `?` placeholders — never string-concat. - **`password_hash($p, PASSWORD_BCRYPT)`** / `PASSWORD_ARGON2ID` + `password_verify`. Never `md5`/`sha1`/`sha256` for passwords. - **Parameterized logging via PSR-3** — `$logger->info('user.updated', ['id' => $id])`, not string concat. ## MUST NOT DO - **No `mixed` without a PHPDoc comment** explaining why — it disables type checking on the value. - **No untyped `array` in public API** — annotate with PHPDoc: `/** @param list<User> $users */` or `/** @return array<string, int> */`. - **No raw `SimpleXMLElement` / `json_decode` without validation** — use `json_validate()` (PHP 8.3+) first, or `JSON_THROW_ON_ERROR`. - **No `(array)` cast on objects** to "export state" — it exposes private/protected with mangled keys (`"\0*\0prop"`). - **No mutating a `readonly` property through a reference** — `$ref = &$obj->prop` throws `Error` on PHP 8.1+; PHP 8.3 also closed indirect bypass loopholes. Use `clone` or a `with*()` factory method to produce a modified copy. - **No `foreach ($arr as &$v)` without `unset($v)` after** — the reference leaks to the outer scope and a later assignment silently mutates the array. - **No `count($big) === 0` to check emptiness** — use `$big === []` or `empty($big)`. `count()` on a `Countable` object can be expensive; `count(null)` throws `TypeError` on PHP 8.0+. - **No `!=` / `==`** — always `!==` / `===`. `0 == "abc"` was `true` until PHP 8, and string/array comparisons still surprise. - **No catching `\Throwable`** to silence errors — catch the specific exception type or let it propagate. - **No `global` / service locator** — constructor-inject everything. - **No credentials / PII in logs or error messages.** ## Reference Guide | Load when | File | |---|---| | Debugging subtle language / API behavior (enums, readonly, match, fibers, arrays, dates, comparison) | `references/pitfalls.md` | | Designing type signatures (PHPStan generics, DNF, `mixed`/`never`/`void`, narrowing) | `references/types.md` | | Writing security-sensitive code (SQL, passwords, CSRF, file upload, serialization) | `references/security.md` | ## Output Format When producing code: 1. A short plan (1–3 bullets) of what's changing. 2. The code with `declare(strict_types=1);` and types everywhere. 3. PHPStan passes at the project's configured level — mention if new `@phpstan-ignore` / `@param` annotations were added and why. When reviewing code: call out MUST-DO / MUST-NOT violations explicitly and suggest the minimal fix.