PHP

  `DateTime` shifts by a day or an hour, `json_encode` returns false, PDO refuses to bind a parameter or emulates
  prepares, sessions serialize parallel AJAX requests, nginx answers 502 or 504 in front of PHP-FPM, OPcache keeps
  serving old code, or a version upgrade breaks on deprecations. Also for escaping output, hashing passwords, sizing
  FPM workers, writing PHPUnit tests, and clearing PHPStan errors. Not for framework internals — `laravel` covers
  Eloquent, queues, and Laravel auth.
homepage: https://clawic.com/skills/php
metadata:
  clawdbot:
    emoji: 🐘
    requires:
      bins:
      - php
    os:
    - linux
    - darwin
    - win32
    displayName: PHP
    configPaths:
    - ~/Clawic/data/php/
---

User preferences live in `~/Clawic/data/php/config.yaml` (see Configuration); nothing else is stored on the user's machine. If you have data at an old location (`~/php/` or `~/clawic/php/`), move it to `~/Clawic/data/php/`.

## When To Use

- Writing or reviewing PHP — read Core Rules and Output Gates before emitting code
- Any error whose cause is not obvious in ten seconds: white page, silent 500, wrong value with no exception, a hang
- Runtime and deployment work: php.ini precedence, FPM pool sizing, OPcache, CLI workers, cron
- Dependency and upgrade work: Composer constraints, autoloading, deprecations, moving to a newer 8.x
- Data-boundary work: PDO queries, JSON payloads, uploads, sessions, dates, encodings
- Hardening: escaping per context, password hashing, deserialization, path containment, upload validation
- Not for framework internals — `laravel` owns Eloquent, queues, Blade, and Laravel auth

## Quick Reference

| Situation | Play |
|-----------|------|
| `==` compares wrong, a numeric string misbehaves, floats do not add up | `===` everywhere; `"0e12" == "0e34"` is true → `hash_equals` → `types.md` |
| Keys vanish, order is wrong, a filtered list encodes as a JSON object | `array_filter` keeps keys; `array_values()` before encoding → `arrays.md` |
| Accents break, `strlen` disagrees with what you see, a regex silently fails | `mb_*` for text, `/u` on every pattern, check `preg_last_error()` → `strings.md` |
| Class design: traits, `static::`, readonly, enums, magic methods, clone | `self::` binds at compile time, `static::` at call time → `oop.md` |
| Exceptions, error handlers, warnings you cannot see, fatal errors | Catch `\Throwable`; fatals need `register_shutdown_function` → `errors.md` |
| Injection, XSS, uploads, `unserialize`, passwords, tokens | Bind every value, escape per output context, `random_bytes` for secrets → `security.md` |
| Which PHP 8 feature to use, and how it bites | `match` is strict and exhaustive; named args make parameter names API → `modern.md` |
| Upgrading PHP, a deprecation wall, "which version can I still target" | Run the OLD version with deprecations as errors first → `versions.md` |
| `Class not found`, lock conflicts, `^` vs `~`, slow or huge installs | Commit the lock for apps, never for libraries → `composer.md` |
| White page, silent 500, "it worked yesterday", a hang with no output | Symptom → cause chains, plus the Xdebug 3 setup that actually works → `debugging.md` |
| Slow requests, high memory, "should we turn on JIT" | OPcache first, profile second; JIT does almost nothing for I/O-bound web → `performance.md` |
| A setting you changed has no effect; CLI and web disagree | `php --ini` per SAPI; `.user.ini` is cached for 300s → `php-ini.md` |
| 502, 504, "server reached pm.max_children", workers eating RAM | Size from measured RSS; `slowlog` names the hung function → `fpm.md` |
| Console scripts, daemons, cron, signals, exit codes | `max_execution_time` is 0 on CLI; recycle workers on a job count → `cli.md` |
| PHPUnit setup, flaky or falsely-passing tests, coverage, mocks | `assertSame` not `assertEquals`; static state leaks between tests → `testing.md` |
| PHPStan or Psalm errors, baselines, coding standard, automated refactors | Baseline the legacy, ratchet one level per merge → `static-analysis.md` |
| PDO connections, binding, transactions, "MySQL server has gone away" | `charset=utf8mb4` in the DSN, `EMULATE_PREPARES => false` → `database.md` |
| Request/response handling, JSON bodies, uploads, outbound HTTP calls | JSON bodies live in `php://input`, not `$_POST` → `http.md` |
| Parallel requests from one user run one at a time; logins do not stick | `session_start()` holds an exclusive lock — `session_write_close()` early → `sessions.md` |
| Dates off by a day or an hour, DST, parsing, storage | `DateTimeImmutable` + IANA zones; `createFromFormat` inherits today → `datetime.md` |
| `json_decode` returns null, big IDs lose digits, `json_encode` returns false | Always pass `JSON_THROW_ON_ERROR` → `json.md` |
| Reading or writing files, CSV, streams, temp files, permissions | Stream instead of slurping; write temp then `rename()` → `files.md` |
| Parallel work, queues, locks across processes, long-running runtimes | Share-nothing per request; `proc_open` deadlocks if you read one pipe → `concurrency.md` |
| Anything else | Core Rules below, then reproduce with `php -d error_reporting=E_ALL -d display_errors=1 -r '<five suspect lines>'` and add one thing back at a time |

Each file above is one sub-job and is self-contained: read SKILL.md by default, open exactly one guide when the situation matches.

## Core Rules

1. `declare(strict_types=1);` on line 1 of every file. It is per-file and governs the CALLS made in that file, not the functions declared there — so an untyped legacy caller still passes `"7"` into your `int` parameter. Return values are checked against the mode of the file where the function is DECLARED (`types.md`).
2. `===` and `!==` by default; `==` only where both operand types are proven. Worked case: `"0e12" == "0e34"` is `true` because both are numeric strings equal to 0 — a hash compared with `==` accepts the wrong password. Compare digests with `hash_equals($known, $given)`, which is also constant-time.
3. Check anything that can return `false` with `!== false`, never with truthiness. `strpos($haystack, $needle)` returns `0` for a match at offset 0, and `if (!strpos(...))` reads that correct answer as a miss; the same shape breaks `preg_match` (`0` = no match, `false` = engine error) and `file_get_contents` (`""` is a valid file).
4. Every SQL value is a bound parameter; every identifier comes from an allowlist you wrote. Placeholders cannot stand in for table or column names, and with the MySQL driver's default emulation the "prepared" statement is interpolated client-side — set `PDO::ATTR_EMULATE_PREPARES => false` (`database.md`).
5. Escape at output, per context, never at input. `htmlspecialchars($s, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')` covers HTML body and quoted attributes only; a value going into JavaScript needs `json_encode` with the HEX flags, one going into a URL needs `rawurlencode`, one going into a shell needs `escapeshellarg` (`security.md`).
6. Text is characters, not bytes: `strlen`, `substr`, `str_pad`, `strrev`, and `ucfirst` count bytes and will cut a UTF-8 sequence in half. Use `mb_strlen`/`mb_substr`/`mb_str_pad` (`php >=8.3`) for anything a human reads; keep the byte functions for binary data, where they are the correct tool.
7. `DateTimeImmutable` everywhere. `DateTime::modify()` mutates the object that every reference shares, so a helper that "returns tomorrow" also moves the caller's date. The same call on an immutable returns a new instance and the bug cannot happen (`datetime.md`).
8. Every call that leaves the process gets an explicit timeout: `CURLOPT_TIMEOUT` plus `CURLOPT_CONNECTTIMEOUT`, a stream context `timeout` for `fopen`, `PDO::ATTR_TIMEOUT` for connections. `max_execution_time` will not save you — on Unix it does not count time spent inside system calls, so a hung socket read is only killed by FPM's `request_terminate_timeout` (`fpm.md`).
9. Stream instead of slurping. `file_get_contents` on a 400 MB export needs 400 MB plus copies inside the default 128M `memory_limit`; `fgetcsv` in a loop, or a generator, holds one row. The same rule retires `fetchAll()` on large result sets (`files.md`, `performance.md`).

## Version Floors

The floors that shape everyday code. Individual guides carry more, inline in this same `php >=X.Y` form next to the instruction each one gates. Support windows and the upgrade procedure: `versions.md`.

| Feature | Needs |
|---|---|
| Typed properties, arrow functions `fn() =>`, spread in calls, `??=`, covariant return types | php >=7.4 |
| `match`, named arguments, constructor promotion, `?->`, union types, attributes, `str_contains`/`str_starts_with`/`str_ends_with`, `static` return type, `throw` as an expression, saner string-to-number comparison, PDO defaulting to exception error mode | php >=8.0 |
| Enums, `readonly` properties, fibers, `never`, first-class callables `f(...)`, `new` in initializers, `array_is_list()`, string-keyed array unpacking, overridable interface constants, `htmlspecialchars` escaping single quotes by default | php >=8.1 |
| `readonly` classes, DNF types, `null`/`false`/`true` as standalone types, locale-independent `strtolower`/`strtoupper`, dynamic properties deprecated, `${var}` interpolation deprecated | php >=8.2 |
| Typed class constants, `#[\Override]`, `json_validate()`, `mb_str_pad()`, readonly reinitialization inside `__clone`, stack-overflow detection via `zend.max_allowed_stack_size` | php >=8.3 |
| Property hooks, asymmetric visibility, `new Foo()->m()` without parentheses, lazy objects, `array_find`/`array_any`/`array_all`, `mb_trim`, implicit nullable parameters (`Foo $x = null`) deprecated | php >=8.4 |
| Pipe operator `\|>`, `#[\NoDiscard]` | php >=8.5 |

## Output Gates

Before delivering PHP code, check:

- `declare(strict_types=1);` present, and every parameter, property, and return typed as narrowly as the value allows
- No `==`, `!=`, or `switch` on values whose types are not both proven; `in_array` and `array_search` carry `true` as the strict flag
- Every SQL value bound, every identifier allowlisted, `EMULATE_PREPARES` off
- Every value reaching HTML, an attribute, JavaScript, a URL, or a shell escaped with that context's function, at the point of output
- Nothing user-controlled reaches `unserialize`, `include`/`require`, `eval`, `extract`, a filesystem path, or a `header()` value without validation
- Every outbound call (HTTP, DB, subprocess, lock) has a timeout, and every `false`-returning call has its return inspected
- Dates are `DateTimeImmutable` with an explicit IANA timezone; human-facing text handled with `mb_*`
- `json_encode`/`json_decode` carry `JSON_THROW_ON_ERROR`
- Syntax and functions stay within `min_php`; layout matches `style`; new behavior arrives with a test that was seen failing first

## Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in `~/Clawic/data/php/config.yaml`. Never interview the user — record a preference the moment it is stated.

| Variable | Type | Default | Effect |
|---|---|---|---|
| min_php | 7.4 \| 8.0 \| 8.1 \| 8.2 \| 8.3 \| 8.4 \| 8.5 | 8.2 | Gates which Version Floors features may be emitted unguarded, and which fallback appears instead (`versions.md`) |
| sapi | fpm \| cli \| apache-mod \| swoole \| roadrunner | fpm | Assumptions about request lifetime, static state, timeouts, and where output goes (`fpm.md`, `cli.md`, `concurrency.md`) |
| framework | none \| laravel \| symfony \| wordpress \| slim | none | Whether to emit plain PHP or framework idiom, and when to hand off to a framework skill |
| strict_types | always \| new-files \| never | always | Whether emitted files open with `declare(strict_types=1)`, and how coercion is discussed (`types.md`) |
| style | per-cs \| psr-12 \| custom | per-cs | Layout of emitted code and the fixer ruleset produced (`static-analysis.md`) |
| static_analysis | none \| phpstan \| psalm | phpstan | Which checker's annotations, config file, and baseline commands appear (`static-analysis.md`) |
| analysis_level | number (0-9) | 6 | Strictness assumed when annotating, and whether a docblock is required alongside a native type (`static-analysis.md`) |
| test_framework | phpunit \| pest \| none | phpunit | Shape of emitted tests, assertions, and data providers (`testing.md`) |
| db_layer | pdo \| doctrine \| eloquent \| mysqli | pdo | Which data-access idiom every query example uses (`database.md`) |

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

- **Tooling**: fixer (PHP-CS-Fixer vs PHP_CodeSniffer), Rector adoption, Xdebug vs pcov for coverage, profiler of choice, local runtime (Docker, Homebrew, Valet, WSL) — affects every emitted config block and command
- **Conventions**: namespace and directory layout, DTO style (arrays vs readonly classes vs enums), exception hierarchy, naming, docblock policy — affects generated code and review comments
- **Platform**: deployment target (FPM behind nginx, shared hosting, container, serverless, long-running runtime), OS, extension availability (`ext-intl`, `ext-mbstring`, `ext-pcntl`), private Packagist — affects `composer.md`, `php-ini.md`, `fpm.md`
- **Safety posture**: how aggressively to flag `unserialize`, dynamic `include`, `extract`, `@`, missing timeouts, unpinned dependencies, and emulated prepares — affects `security.md` and review depth
- **Dependencies**: banned or mandated packages (Guzzle vs Symfony HttpClient, Carbon vs native `DateTimeImmutable`), tolerance for new transitive dependencies, stdlib-only constraints — affects every recommendation
- **Output format**: whole file vs minimal diff, how much explanation, whether tests and a changelog entry accompany every change — affects the shape of the answer, never the correctness rules
- **Work order**: which gates run before a change is proposed rather than after — analyzer and suite green first, a plan approved before editing, a profile before any optimization — affects the sequence of every task, never the correctness rules

## Traps

| Trap | Why it fails | Do instead |
|------|-------------|------------|
| `if (!strpos($s, $x))` | Returns `0` for a match at position 0 — the correct answer reads as failure | `strpos($s, $x) !== false`, or `str_contains()` on `php >=8.0` (`strings.md`) |
| `==` to compare a password hash or token | `"0e12" == "0e34"` is `true`; both are numeric strings equal to zero | `hash_equals()`, or `password_verify()` for passwords (`security.md`) |
| `array_filter()` then `json_encode()` | Keys survive, so the gap turns the array into a JSON object and the client's `.map()` fails | `array_values()` after every filter that feeds JSON (`arrays.md`, `json.md`) |
| `json_decode($s)` with no flags | Returns `null` for the input `"null"` AND for a parse error — indistinguishable | Always `JSON_THROW_ON_ERROR` (`json.md`) |
| `$_POST` for a JSON request body | Populated only for form-encoded and multipart bodies | `json_decode(file_get_contents('php://input'), ...)` (`http.md`) |
| Trusting `$_FILES['f']['type']` | The MIME type is supplied by the client and is trivially forged | `finfo_file()` on the temp file plus an extension allowlist (`security.md`) |
| `session_start()` at the top and never closing | The session lock is held for the whole request, so one user's parallel requests execute one at a time | `session_write_close()` as soon as the last write is done (`sessions.md`) |
| `DateTime::createFromFormat('Y-m-d', $d)` | Unspecified fields default to NOW, so the date carries the current time and can roll the day | Prefix the format with `!` to zero them, then check `getLastErrors()` (`datetime.md`) |
| `@` to silence a warning | Hides the diagnosis and leaves the broken value in flight; on `php >=8.0` it no longer even silences fatals | Handle the failure, or narrow `error_reporting` deliberately (`errors.md`) |
| `mt_rand`/`uniqid()` for a token or password reset | Predictable: `uniqid()` is a formatted timestamp, `mt_rand` is a seeded PRNG | `random_bytes()`/`random_int()` (`security.md`) |
| `PDO::ATTR_PERSISTENT` without cleanup | A worker inherits an open transaction, session variables, or temporary tables from the previous request | Non-persistent connections, or an explicit rollback on checkout (`database.md`) |
| A closing `?>` at the end of a PHP file | One trailing newline becomes output, and every later `header()` fails with "headers already sent" | Omit the closing tag in pure-PHP files (`http.md`) |
| `readfile()` for a large download | Fills the output buffer with the whole file before sending | `fpassthru` with buffers flushed, or `X-Accel-Redirect`/`X-Sendfile` (`http.md`) |
| `opcache.validate_timestamps=0` with a deploy that only swaps files | Workers keep executing the previous release's bytecode | Reload FPM (`kill -USR2`) as the last deploy step (`performance.md`, `fpm.md`) |
| `SELECT` then `INSERT` to avoid duplicates | Two workers pass the check in the same millisecond | Unique index plus catching the duplicate-key error (`concurrency.md`) |

## Where Experts Disagree

- **Arrays vs objects for structured data.** The array-shape school keeps everything a `list<array{id:int,…}>` and lets the analyzer verify it: no boilerplate, refactors are grep-based. The value-object school makes each shape a readonly class: constructor validation, no key typos, IDE completion. Boundary: data crossing a module or process boundary earns a class; a shape used in three lines of one function does not (`static-analysis.md`).
- **Active record vs data mapper.** Eloquent-style records are faster to write and let any layer reach the database; Doctrine-style mappers keep the domain persistence-free and make the unit of work explicit. Boundary: how long the codebase must outlive its storage decisions — not how large it is (`database.md`).
- **How strict to run the analyzer.** One camp treats anything below `max` as unfinished; the other stops where the false-positive rate exceeds the bug-catch rate. Boundary: a greenfield typed domain reaches high levels cheaply; a decade-old codebase baselines and ratchets, and measures success as baseline shrinkage rather than level number (`static-analysis.md`).
- **Long-running runtimes.** Swoole, RoadRunner, and FrankenPHP remove per-request bootstrap and can cut latency materially; they also delete PHP's strongest safety property, that every request starts from a clean process. Boundary: adopt when bootstrap is a measured share of p95 AND the team accepts hunting state leaks — never as a default (`concurrency.md`).
- **Framework or none.** A framework supplies routing, DI, migrations, and a hiring pool; plain PHP with a few PSR packages supplies a dependency tree you can read end to end. Boundary: the number of cross-cutting concerns you would otherwise hand-write — auth, queues, and migrations together is the tipping point.

## Related Skills

More Clawic skills, get them at https://clawic.com/skills/php (install if the user confirms):
- `laravel` — Eloquent, queues, Blade, and Laravel-specific auth
- `mysql` — schema design, indexes, and query plans behind PDO
- `nginx` — the server in front of PHP-FPM: buffering, timeouts, static files
- `regex` — PCRE pattern design; this skill's `strings.md` covers only the PHP bindings
- `debugging` — language-agnostic fault isolation; the PHP-specific version is this skill's `debugging.md`

## Feedback

- If useful, star it: https://clawic.com/skills/php
- Latest version: https://clawic.com/skills/php

Part of [Clawic](https://clawic.com), the verified skill library. Get this skill: https://clawic.com/skills/php.