Coding standards

Bounded candidate reference — 2026-10-20: 0.2.0-rc.1 is committed locally through 84f415b3098af5653577b2c65eea31fca21df79c, unpublished and not production-approved; stable PHP >=8.5.11 <8.6.0 is required. This is documentation, not adoption: this knowledge base retains its installed 0.1.0-rc.1 dependency and PHP 8.2.11 local profile. Dated PHP 8.2 evidence is historical; earlier dirty-source reports retain their original test provenance, not retroactive clean-commit proof. Candidate examples are illustrative: API signatures were reviewed, but candidate code was not executed by this editorial update. See current checkpoint, open criteria and adoption boundary.

PHP baseline

The next candidate targets owner-selected PHP >=8.5.11 <8.6.0, permitting later 8.5 patches but not another minor. Actual isolated 8.5.11 CLI/Apache-FPM gates have passed; final-host qualification remains open. The host was not upgraded. See Decision 0003, which supersedes the minor selection in Decision 0002 without rewriting its historical evidence. Every PHP file uses strict types, PSR-4 namespacing, PSR-12 layout, explicit visibility, typed signatures, and one runtime class/interface per file. Concrete infrastructure classes are final unless supported subclassing is deliberate.

The byte-preserved original files under compatibility/prosperous-pairs-legacy/app are a compatibility baseline and may predate these rules. New files and all substantive edits follow this standard; changes to a preserved file also require an intentional manifest-hash update and regression coverage.

Use PHPDoc for generic/collection shapes, callable signatures, resource types, and invariants PHP cannot express. Do not use PHPDoc to repeat obvious scalar types.

Comments

All framework public APIs and example application APIs require concise docblocks. Security-sensitive, transactional, cache, filesystem, and lifecycle code requires comments explaining invariants and failure behavior. Comments must explain why, ownership, or constraints—not narrate syntax.

Keep example code fully commented enough that a new application developer can identify the extension point and safely replace it.

For non-trivial APIs, place a behavioral summary before annotations and explain trust boundaries, side effects, missing/denied behavior, failures, and ownership of lifetimes/transactions/retries where applicable. A type annotation alone is not sufficient for a policy-enforcing constructor or an execution method. Simple collection accessors may keep short shape comments when behavior is obvious. See API_GUIDE.md for examples and the focused automated summary check; passing that check is not a substitute for semantic review.

Naming

• Classes/interfaces: PascalCase.
• Methods/properties/variables: camelCase.
• Environment variables: UPPER_SNAKE_CASE.
• Configuration keys: lowercase dot paths.
• Route names: lowercase dotted names.
• Migration IDs/files: UTC timestamp plus descriptive snake case.
• Database tables/columns: lowercase snake case selected by the application.

Avoid generic names such as Manager, Helper, or Utils when a narrower responsibility exists.

Architecture

• Controllers translate HTTP and call one or more application use cases.
• Domain classes do not depend on requests, responses, routers, templates, or provider SDKs.
• Services coordinate rules and own transaction boundaries.
• Repositories expose application concepts and bind SQL values.
• Provider adapters implement application/framework ports.
• Middleware owns cross-cutting HTTP checks that must precede controllers.
• Views render supplied data only and perform no writes or provider calls.

Dependencies point inward toward contracts and domain behavior. Framework code does not import a consuming application namespace.

Error handling and logging

Use client-safe messages and appropriate HTTP statuses. Unexpected errors get a correlation ID and structured server log metadata. Never log credentials, raw tokens, cookies, authorization headers, request bodies, private media, or SQL parameter values. Logs must not become an alternate database.

SQL and migrations

Bind every value. Select identifiers through a closed allowlist. Use explicit transactions for multi-step use cases and document nontransactional DDL. Applied migrations never change; corrective behavior goes into a new migration.

Views and frontend assets

Use native PHP templates without eval. Escape for HTML, URL, JavaScript, CSS, or JSON according to the exact output context. Keep JavaScript optional unless an application explicitly adopts a documented client contract. Minify CSS/JS at build/deployment time, not on every request.

Tests

Tests must be deterministic, isolated, and free of production connections. Cover success, validation, denial, malformed input, retries/idempotency where applicable, and safe failure. A skipped integration is documented as TO VERIFY with the missing dependency, exact future command, pass criteria, and risk.

Editorial provenance

Source: docs/CODING_STANDARDS.md. Source SHA-256: 3be068b51a6c4f1d0e490cd5c1df6b24e81a710913821767a719ab579f92f6b6.

Framework candidate reference; editorial checkpoint 2026-10-20. See candidate status and adoption boundary.