/sota-php

name: sota-php
description: >-
  State-of-the-art PHP engineering (2026 baseline, PHP 8.3+ floor, 8.5 current) for both
  writing new PHP and auditing existing PHP code. Covers strict_types and modern idioms
  (enums, readonly, match, fibers, property hooks), OWASP-grade security (SQL injection,
  XSS, file uploads, LFI/RFI, unserialize/Phar object injection, sessions, password
  hashing, sodium, SSRF), framework-neutral web hardening, Composer supply chain and
  static analysis (PHPStan/Psalm levels, baselines), and runtime performance (OPcache,
  preloading, FPM tuning, JIT, N+1). Use whenever the task involves PHP source,
  composer.json, php.ini, FPM config, or a PHP framework — building features,
  scaffolding projects, reviewing PRs, or hunting bugs and vulnerabilities.
  Trigger keywords: PHP, composer, Laravel, Symfony, WordPress, PHPStan, Psalm, PHPUnit,
  Pest, PDO, php-fpm, OPcache, strict_types, phar, unserialize, htmlspecialchars.

SOTA PHP (2026)

Purpose

This skill encodes the 2026 state of the art for PHP: a supported-version baseline (PHP 8.3+ floor; 8.5 is the latest annual line — verify current, see `rules/01`), `strict_types` everywhere, typed object-oriented design, security-by-default at every trust boundary, a locked and audited Composer supply chain, and measured runtime performance. It serves two modes:

• **BUILD** — writing new code or modifying existing code to this standard.
• **AUDIT** — reviewing existing code against this standard and reporting findings.

The detailed rules live in `rules/*.md`. Read SKILL.md fully; load rules files on demand per the index table below.

BUILD mode

When creating or modifying PHP code:

1. **Establish context first.** Check `composer.json` (`require.php`, `config.platform`), `composer.lock`, the framework in use, PHPStan/Psalm config, and CS ruleset. Match the project's PHP floor — no enums on a project that still supports 8.0. For a *new* project, scaffold per `rules/05`: PHP ≥ 8.3 floor, committed lockfile, PHPStan at max level (baseline only for legacy), PER-CS formatting, CI gates from day one. 2. **Default style:** `declare(strict_types=1)` in every file, full parameter/return/ property types, constructor promotion, `readonly` where state shouldn't mutate, enums over class constants, `match` over `switch`, exceptions over error codes, no `@` suppression. (`rules/01`) 3. **Security posture is non-optional** even when unrequested: PDO prepared statements, context-correct output escaping, upload validation by content, no `unserialize()` on external data, `password_hash`/`sodium`/`random_bytes` for anything secret. (`rules/02`–`rules/04`) 4. **Framework first.** When a framework is present (e.g. Laravel, Symfony), use its escaping, CSRF, auth, and validation mechanisms instead of hand-rolling — but verify raw-escape hatches (`DB::raw`, `|raw`, `html()`) aren't fed user input. 5. **Tests accompany code** (PHPUnit or Pest as the project dictates); static analysis and CS must pass before code is presented. (`rules/05`) 6. **Performance:** OPcache assumptions belong in deploy config, not code; anything beyond correct-by-default (eager loading, streaming, generators) requires a profile first. (`rules/06`)

AUDIT mode

When reviewing existing PHP code:

1. **Sweep mechanically first.** Run the "Audit checklist" blocks at the end of every relevant rules file — ordered grep/composer/phpstan commands. Start with `composer audit --locked` and a grep sweep for `unserialize(`, `eval(`, `shell_exec`, string-interpolated SQL, and `echo $_`. 2. **Then read for design:** trust-boundary placement, escaping strategy (output-time or scattered?), session lifecycle, N+1 patterns, lockfile discipline. 3. **Verify every finding** — open the file, trace the data flow. An `unserialize()` of a value the same app signed with HMAC is not CRITICAL. Note mitigations already present. 4. **Don't report style noise** a fixer would auto-fix; mention once collectively.

Severity conventions

| Severity | Meaning | Examples | |---|---|---| | CRITICAL | Exploitable now, or data loss | SQL built by interpolation from request data, `unserialize($_GET…)`, `include` of user path, `eval` on input, uploads executed as PHP | | HIGH | Exploitable with preconditions, or prod-breaking | XSS via unescaped output, `md5()` passwords, missing `use_strict_mode`/fixation, SSRF fetch of user URL, `CURLOPT_SSL_VERIFYPEER => false`, world-readable secrets | | MEDIUM | Correctness/maintenance risk | no lockfile committed, no `composer audit` in CI, loose `==` on security decisions, `rand()` for tokens in non-auth context, N+1 on hot path, no static analysis | | LOW | Deviation from SOTA, friction | missing `strict_types`, untyped properties, `switch` where `match` fits, dev deps in prod image | | INFO | Worth knowing | newer-PHP features available after floor bump, tooling consolidation |

Finding format

file:line | rule violated (rules/NN §S) | severity | effort | fix

Effort: trivial · small · medium · large. Group by severity, CRITICAL first. Borderline severities state the deciding assumption; unconfirmed findings are marked "needs verification", never asserted. End with counts per severity, the sweep commands run, and explicit "checked and clean" areas.

Rules index

| File | Read this when... | |---|---| | `rules/01-language-baseline.md` | choosing/verifying PHP version floor (support/EOL table); writing any PHP: strict_types, typed properties, enums, readonly, match, fibers, 8.4/8.5 features, comparison pitfalls incl. **`strpos` returning `false` where `0` is a real match**, error handling, deprecations | | `rules/02-injection.md` | code touching SQL, shell, or HTML output: PDO prepared statements, command execution, XSS and context-aware escaping, template engines, eval-family bans | | `rules/03-files-deserialization-ssrf.md` | file uploads, include/require paths, stream w