/sota-php

name: sota-php
description: >-
  State-of-the-art PHP engineering (supported PHP branches) 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; verify the supported branches at php.net/supported-versions.php, see [`rules/01`](rules/01-language-baseline.md)), `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`](rules/05-composer-tooling.md): 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`](rules/01-language-baseline.md)) 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/02-injection.md)–[`rules/04`](rules/04-sessions-auth-web-hardening.md)) 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`](rules/05-composer-tooling.md)) 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`](rules/06-performance-runtime.md))

AUDIT mode

**Coverage:** every `rules/` file's Audit checklist applies in AUDIT mode. Mark one *not applicable* only with its reason in the report — never skip a file because the thing it checks for is absent, since that absence may be the finding.

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

This is the router's canonical row; each finding carries the [`sota` rules/03](../sota/rules/03-audit-findings.md) §2 evidence block, and the report follows its §5 order.

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" are