skills-public/code-languages/php.md

name, description

name	description
php	Use this skill when writing, linting, analysing, testing, or releasing PHP — libraries, Composer packages, generated SDKs, and plain PHP-FPM web applications behind nginx. Covers strict_types, PHPStan at max, PER-CS 2.0 with risky rules, final readonly value objects, backed enums, PSR interfaces over implementations, output escaping, and PHPUnit strictness.

PHP — Rules & Preferences

Extends coding-dev.md. Everything there applies; this adds PHP specifics.

PHP here means one of two things, and they differ: a library published through Composer, which depends on PSR interfaces and ships no implementation, and a plain PHP-FPM application behind nginx with no framework, where the filesystem is the router. Both carry §1–§8; §9 is the library half and §10 the application half.

---

1. The Gate

composer lint    # php-cs-fixer fix --dry-run --diff
composer stan    # phpstan analyse
composer test    # phpunit
composer check   # all three, in that order

Define those four as scripts in composer.json so the gate has one name. composer check must be clean before anything is called done — zero fixer diffs, zero PHPStan errors, zero test failures, and no warnings, notices or deprecations (see §7).

• Use @php tools/x.php rather than php tools/x.php in a composer script: it runs the interpreter Composer itself is running under, which matters on a machine with several.
• composer test must never touch the network. Point defaultTestSuite at the unit suite so a bare run is safe to fire blind.
• Name tool configs .dist — phpstan.neon.dist, phpunit.xml.dist, .php-cs-fixer.dist.php — so a developer can drop a local override beside them without dirtying the repo. Add the caches (.php-cs-fixer.cache, .phpunit.cache) to .gitignore.
• Lockfile by artifact type: an application commits composer.lock, a library ignores it. Getting this backwards shows up in every diff.

---

2. There Is No PHP On The Host

On this workstation PHP is not installed on the host at all. ~/.local/bin/php is a three-line bridge that execs into the development container, and composer has no bridge — see distrobox-buildbox-dev.md for the container, and coding-dev.md §13 for why toolchains never land on an immutable host root.

# php works from the host. composer does not — go through the container, and chain the cd,
# because entering one resets the working directory.
distrobox enter <container> -- bash -c "cd /abs/path/to/project && composer check"

Caution

Inside the container, prepend PATH=/usr/bin:/bin. The host ~/.local/bin is on PATH ahead of /usr/bin there, so the host's own php bridge shadows the container's real interpreter and dies with /usr/bin/distrobox: No such file or directory. Every vendor/bin/* tool is a PHP script, so vendor/bin/phpstan fails this way and the error names distrobox rather than anything to do with PHP. php vendor/bin/phpstan with the fixed PATH works.

Edit PHP sources with Read/Edit/Write, not with sed or a php -r patch script. The nested quoting inside distrobox enter … bash -c "…" mangles $, backslashes and quotes in exactly the places PHP uses them, and a half-applied patch script reports success.

---

3. Strictness — strict_types In Every File, PHPStan At Max

<?php

declare(strict_types=1);

Every file, with no exceptions, enforced mechanically by the fixer's declare_strict_types rule rather than by review. Without it a "7" from an API quietly becomes int 7 and a hydrator whose whole purpose is to fail loudly on drift stops failing at all.

# phpstan.neon.dist
parameters:
    level: max
    paths:
        - src
        - tests
        - tools
        - examples
    treatPhpDocTypesAsCertain: false

• Analyse tests, tools and examples too, not just src. Those are the three places authors assume are exempt, and they are where a convention actually breaks first.
• treatPhpDocTypesAsCertain: false stops PHPStan trusting a PHPDoc that is narrower than the signature, so genuine runtime is_string/is_array guards are not reported as always-true.
• No baseline and no ignoreErrors. Level max is reachable with standard tags and real guards; a baseline is a list of things nobody will ever go back to.
• A suppression, when genuinely needed, is the narrowest @phpstan-ignore-next-line with the reason on it. Reaching for @phpstan-* or @psalm-* to describe a type is a smell — the standard tags in §5 carry everything level max needs.
• Never relax a strictness flag without an adjacent comment saying why. This is the house habit across every config file in the repo, and it is what makes a relaxation reviewable instead of load-bearing folklore.

---

4. Formatting — PER-CS 2.0, Risky Rules On

// .php-cs-fixer.dist.php
->setRiskyAllowed(true)
->setRules([
    '@PER-CS2.0' => true,
    '@PHP82Migration' => true,
    'declare_strict_types' => true,
    'strict_param' => true,
    'strict_comparison' => true,
    'global_namespace_import' => ['import_classes' => false, 'import_functions' => false],
    'no_unused_imports' => true,
    'ordered_imports' => ['sort_algorithm' => 'alpha'],
    'php_unit_test_case_static_method_calls' => ['call_type' => 'self'],
])

php-cs-fixer and PHPStan, not Pint and not Psalm. The fixer config does more normative work than the prose does: these rules are where five of the conventions below stop being review items.

• strict_comparison + strict_param mean every comparison is ===/!== and every in_array() carries its third argument. Loose in_array matches numeric strings.
• global_namespace_import => false is why every global function, constant and class is written with a leading backslash: \sprintf, \JSON_THROW_ON_ERROR, \DateTimeImmutable, \RuntimeException. Inside a namespace an unqualified call makes PHP look up the namespaced name first and fall back to global — a per-call cost, and a hazard the day something defines App\json_decode.
• Guard a fixer API that newer releases added, rather than calling it unconditionally and breaking the lint step on the oldest version composer.json still allows: if (\method_exists($config, 'setUnsupportedPhpVersionAllowed')) { … }.

---

5. Banned Constructs

Never	Use instead
== / !=	=== / !== (the fixer enforces it)
in_array($x, $a)	\in_array($x, $a, true)
stdClass from json_decode	\json_decode($b, true, 512, \JSON_THROW_ON_ERROR) into array<string, mixed>, then a typed model
json_last_error() checks	\JSON_THROW_ON_ERROR on every encode and decode
\DateTime	\DateTimeImmutable — a mutable date in a readonly class is a hole in the guarantee
setX() on a value object	withX() returning a new instance
http_build_query()	a builder that drops nulls, spells booleans true/false, and repeats a key instead of emitting k[0]=
extract(), eval(), $$var	named variables
@ error suppression	check the return value
array() long syntax	[]
A pure enum for a wire value	a backed enum X: string (§6)
echo $x in HTML	\htmlspecialchars($x, \ENT_QUOTES, 'UTF-8') (§10)
Unqualified strlen/count/sprintf inside a namespace	\strlen, \count, \sprintf

• PHPDoc only says what the signature cannot: array shapes, generics, class-string, list<T>, @template, @implements, @return never. A @param string $x restating a declared scalar is a second source of truth that will drift from the first.
• @return never in a docblock over a native : mixed is the deliberate exception: it gives PHPStan the unreachability while still letting the helper sit in a ternary tail position (return \is_string($v) ? $v : $this->fail(…);), which a native : never forbids.

---

6. Types — final readonly By Default

• final readonly class is the default shape for anything carrying data. Plain final class only for things that memoise, hold mutable state, or are pure behaviour. readonly on the class is what makes "models are immutable, build a new one" enforced by the engine instead of promised in a docblock.
• Constructor property promotion for every property, with private readonly written out explicitly even inside a final class. The one property declared the long way should be the one the constructor has to run through a normaliser — promotion cannot transform a value, so that asymmetry is a readable signal rather than an inconsistency.
• new in a parameter default, not nullable-plus-??: private readonly LoggerInterface $logger = new NullLogger(). The signature then states the real type and PHPStan never sees a nullable to guard. Keep ?X $x = null only where a static factory forwards the argument and "the caller said nothing" has to stay distinguishable.
• Named arguments wherever a call has more than two or three arguments or skips one. A wide constructor built positionally silently mis-wires the day two same-typed fields swap order.
• First-class callable syntax (Model::fromArray(...)) over a 'Model::fromArray' string — it is checked at compile time. Mark a closure that needs no binding static, so it cannot capture $this into a long-lived callable and keep the owner alive.
• Model properties may keep the API's own snake_case names rather than being renamed to camelCase. A rename table has to be maintained in both directions, silently drops whatever the mapping forgot, and makes a devtools capture stop matching the code.

---

7. Enums & Wire Values

• Backed enums only (enum Provider: string). A backed case is what lets one branch collapse any enum to its wire form and a generic reader be typed class-string<T of \BackedEnum>.
• An unrecognised wire value throws, naming the model, the field, the value, the enum class and the remedy. ::from() raises a bare \ValueError with no field name; an Unknown fallback case hands the caller a value the API's own type does not have and defers the failure to someone else's match.
• Where a field genuinely carries any JSON value, type it mixed and explain it in prose. A PHPDoc union nothing actually validates is a lie PHPStan will then trust.

---

8. Errors & Exceptions

• The root of the hierarchy is an interface, interface AppException extends \Throwable {}, not a base class. Callers can then catch (AppException $e) without catching unrelated \RuntimeExceptions, while each exception still extends the most apt SPL class — which an abstract base makes impossible the moment two of them want different parents.
• One static factory mapping status to class (match (true) over 400/401/403/404/409/422/ 429/>= 500). Declare the base's constructor final public function __construct so new $class(…) in that factory stays safe.
• Carry the parsed error envelope, the raw body, and the request method and URI on the exception, and truncate the raw body — a 2 MB proxy error page does not belong in a log line. Document that callers branch on an error code, never on the message, which is prose.
• A failure to parse the error body must never mask the real status. A 502 from a load balancer returns HTML; if the envelope parser throws, the caller sees a JSON parse error instead of "the service is down". Return null from the parser on every one of those paths.
• Retry only idempotent methods — GET, HEAD, OPTIONS, PUT, DELETE. POST and PATCH need an explicit opt-in, because a timeout on a request that actually succeeded is how a giveaway gets drawn twice. Honour Retry-After over the computed backoff, and inject the sleeper so the retry test does not take 30 seconds of wall clock.

---

9. Libraries — PSR Interfaces, Not Implementations

Follow the global ordering (reuse → fork → write, coding-dev.md §3). For a published package specifically:

• Require PSR interfaces and ship no implementation. psr/http-client (18), psr/http-factory (17), psr/http-message (7), psr/log (3), plus php-http/discovery. Guzzle and a PSR-7 implementation go in require-dev with a suggest entry saying any implementation works. Pinning a client forces a version on every consuming application.
• Widen the constraint on an interface package that has had a major ("psr/http-message": "^1.1 || ^2.0") so a consumer's choice does not conflict with yours.
• Wrap the PSR client behind your own one-method transport interface. That is what lets the whole unit suite run against a fake and assert on exact bytes, instead of building PSR-7 mocks in every test.
• Convert a discovery miss into your own configuration exception whose message says what to composer require.
• Secrets enter through an interface, never a string parameter: a token provider whose implementation reads the environment, with a null return treated as legitimate because some endpoints are public. A token passed as a constructor literal lands in every stack trace and var_dump. See coding-dev.md §10 for the general rule.
• Partial updates: distinguish "field absent" from "field is null" per field. Serialise a fetched model, PATCH it back, and a blanket array_filter(…, fn($v) => $v !== null) wipes every server-side value the caller never mentioned — while the opposite default breaks the fields for which null is the value.
• Accept an int where the schema says number. JSON has one number type, so a whole number arrives as an int and strict is_float() rejects every such value. This wants a named regression test.

Generated code lives in directories that are wiped and rewritten whole, never overwritten file by file — otherwise a deleted endpoint lingers as a class that still compiles and 404s. Every generated file opens with a banner carrying the exact regeneration command, generated and hand-written namespaces never share a directory, and nothing is added to a generated namespace — a method on a generated enum is deleted by the next run, so it belongs on a hand-written sibling instead.

---

10. Web Applications — Escaping, Writes, Sessions

A plain PHP-FPM app with no framework still gets one require __DIR__ . '/../vendor/autoload.php' per entry point and PSR-4 for everything else. Hand-rolled require graphs between application files are what produce double-inclusion and load-order bugs.

• Entry points are three lines over a class. Two copies of the same handler are how one of them loses its CSRF check.
• Compute first, echo second. With no template engine the discipline is the separation: all logic above the ?>, then markup with <?= ?> echoes of values already shaped. Logic mixed into markup is where an unescaped echo hides.
• Escape at every echo, with the explicit form \htmlspecialchars($t, \ENT_QUOTES, 'UTF-8'). There are no trusted values.

Caution

json_encode into an inline <script> is an XSS hole, and JSON_UNESCAPED_SLASHES opens it by removing the <\/script> escaping that would otherwise have saved you. Any </script> or <!-- inside the data closes the element and the rest is parsed as HTML. Use JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT, or emit a <script type="application/json"> block and JSON.parse it.

• The document root stays unwritable. A web server that can create files in its own document root is one bug away from writing a .php there. Anything PHP writes goes under sys_get_temp_dir(); a file it must update in place gets permission on the file, not on the directory. If an upload directory must live under the root anyway, sniff content (getimagesize() plus an image-type→extension allowlist, never the uploaded name) and deny .php under it in the server config.
• Check the return value of every write. Both halves of the uid trap recorded in this machine's memory were silent: a cache the web user could not create meant every page view re-scraped three third-party APIs, and an .env the web user could not read looked exactly like "no token configured".
• Atomic writes, two routes. Write a temp file beside the target and rename() it, copying the victim's mode and group first — a rename-created file lands in PHP's group and locks everyone else out of editing it. Fall back to r+ plus flock(LOCK_EX) plus ftruncate, never w, which truncates before the lock and happily creates a stray file at a typo'd path. Treat a short write as a failure.
• Optimistic concurrency by content hash, not mtime — the mtime of a file on a network mount is not something to bet a save on. Validate the whole document before writing; a partial save is never attempted.
• Validate a filename against a listing, not by sanitising it: in_array($name, array_column($this->backups(), 'name'), true). Cleaning the string is how ../../.env gets through, and for a path under a base directory only comparing realpath() results catches a symlink.
• Sessions in one place. One guarded session_start(), an explicit save_path you know is writable (a session that silently fails to persist looks exactly like a login that silently fails), use_strict_mode=1, use_only_cookies=1, and an httponly + samesite=Lax + secure cookie. Decide secure by defaulting to true and excepting loopback: behind a terminating proxy $_SERVER['HTTPS'] is empty on a real HTTPS visit, and reading X-Forwarded-Proto lets a forged header strip the flag. Expire by inactivity, which the client does not control, and session_regenerate_id(true) the moment a visitor gains privilege.
• Re-check authorisation per request, never from an is_admin flag stamped into the session at login — otherwise revoking access means waiting for a session to expire. Request the minimum OAuth scope and discard the access token after use; storing it turns a session leak into an account compromise.
• Discard unsafe input rather than cleaning it: a redirect target must start with /, must not start with //, and must have no control characters or backslashes; strip CR/LF from any header value built from a query string.
• An authenticated JSON API answers 401 with JSON, not a 302 to an HTML login page, which is useless to fetch() and surfaces as a parse error. Every admin call is a POST carrying a CSRF token compared with hash_equals — including the reads, since a GET is reachable from another site's page — dispatched through match with a default that 400s.
• One response shape, {ok: bool, …} with a snake_case reason code, and set the content type, X-Content-Type-Options: nosniff and the cache policy before anything can fail so the error path carries them too. Choose per endpoint whether upstream trouble is a 200 with ok: false (a public endpoint the page polls) or a real status code (a command channel).
• A multipart request has already been consumed into $_POST/$_FILES, so check for the upload action before reading php://input — otherwise the generic JSON path reports "not valid JSON" for a body PHP ate.
• Every outbound call gets a timeout and a connect timeout, http_errors => false so a 4xx body can be read for its reason, and redirects pinned to https. No timeout means a hung third party holding an FPM worker.
• A missing credential is a supported state: separate "configured" from "not configured", answer with a machine-readable reason, and render a page saying it is not set up rather than a 500 nobody can diagnose.

---

11. Testing

• PHPUnit with attributes, never docblock annotations: #[CoversClass], #[DataProvider], #[Group]. Annotations are deprecated in PHPUnit 11 and the config below turns that into a failure rather than a warning.
• Turn on every escalation in phpunit.xml.dist: failOnWarning, failOnNotice, failOnDeprecation, failOnRisky, failOnEmptyTestSuite, beStrictAboutOutputDuringTests. failOnSkipped="false" is the one justified exception, because a suite that skips itself without credentials is the intended outcome on a machine without them — say so in an XML comment next to it.
• Test classes are final; assertions are self::assertSame(…) (the fixer enforces it), while expectation setup, which is genuinely instance state, stays on $this.
• Test method names are full sentences: testAWrongTypeIsReportedRatherThanCoerced().
• Mock at the transport boundary with a fake that fails loudly. Running out of queued responses throws, naming the method, the URI and how many were already served — a fake returning null turns "one more request than expected" into a type error three frames away. Record every send so a test can assert on exact bytes.
• Fixtures are sanitised real captures, not hand-written JSON. A hand-written fixture encodes what the author thinks the API returns, so a drift test passes against an imagined payload. Keep shape, keys and enum values exactly; replace every identifier, handle, display name, avatar URL and message body with a deterministic placeholder so the diff stays stable. The raw capture stays out of the repository.
• A suite needing credentials is a separate testsuite, tagged, not the default, and skips per test by re-reading the environment in a helper — so the skip message is attached to the test that needed it. \getenv() returns false when unset, so guard with is_string before trim. Everything in it is a read, because the only credentials anyone will run it with belong to something live. Regression test every fixed bug.
• Put the file and function size limits in a test, since neither PHPStan nor the fixer has a length rule — see coding-dev.md §4. Measure function length by walking \PhpToken::tokenize(), not by counting braces in text: a { inside a string or a comment looks exactly like a block opener. Skip generated files, whose length is a property of the API surface. Carry over-limit files in an ACCEPTED map whose value is the written reason, and fail when a listed file drops back under so the entry gets removed.

---

12. CI

A PHP workflow runs shivammathur/setup-php@v2 with tools: composer:v2, then composer install --prefer-dist --no-interaction --no-progress, then the gate in order: fixer dry-run, PHPStan, unit suite. Set permissions: contents: read explicitly. Put a credential-needing suite behind a workflow_dispatch input and pass the secret as env:, never as a command-line argument (cli-tooling.md §7).

Important

Under this account, only workflow_dispatch may be live. Every automatic trigger — push, pull_request, schedule — stays in the file but commented out, under a comment saying why, so a fork restores CI by deleting # characters. See the GitHub Actions section of the agent profile; a workflow written with on: push looks correct and never runs.

A job that reports upstream drift should ::warning:: rather than fail: the API moving is information, not a defect in this repository.