Public assets and image derivatives

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.

The optional asset module serves public assets only. It is not protected storage and performs no user authorization.

Construct AssetManager with a real source directory, separate cache and lock directories, a cache toggle, and a public prefix. URLs are generated from an existing source below that root.

$css = $assets->url('/assets/css/app.css', ['type' => 'css']);
$hero = $assets->url('/assets/images/hero.jpg', [
    'type' => 'image',
    'width' => 1280,
    'height' => 720,
    'fit' => 'cover',
    'format' => 'webp',
    'quality' => 82,
]);

CSS/JavaScript retain their original public path. With cache disabled, a source fingerprint query is added for cache busting; that does not set cache headers on files served directly by Apache. The manager marks image responses that it actually serves with caching disabled as no-store. Configure the web server's static-file cache policy separately and verify actual response headers. Runtime text minification is rejected; minify CSS/JavaScript in a deployment build.

Image derivative names encode the source stem, width, height, fit, format, quality, optional upscale policy, and a query fingerprint, for example:

/assets/images/hero_1280_720_cover_webp_82.webp?v=<source-fingerprint>

The manager accepts cover, contain, or stretch; JPG, PNG, WebP, or AVIF; quality 40–95; width/height up to 2400; and at most 12 million requested pixels. Upscaling defaults off. Availability of WebP/AVIF depends on the local GD build and fails explicitly when absent.

Source decode is additionally limited before GD allocation: <=20 MiB compressed, <=12,000 per dimension and <=12 million source pixels. This is not native hostile-codec/scanner qualification. Existing scoped GD/HTTP checks do not imply AVIF availability on every host. Native videos/scanners stay disabled until their own sandbox/resource/version checks pass.

Canonical missing derivative requests reach AssetController. The source is found by stem and fingerprint, the request is recomputed and compared to the canonical URL, generation is locked, and a temporary output is atomically renamed into a fingerprinted cache. Existing files bypass PHP under Apache. Traversal, backslashes, null bytes, malformed options, source/type mismatches, and noncanonical paths are rejected.

warm() may generate known derivatives during deployment or background work. The module does not parse CSS to infer dimensions; templates/controllers must request explicit sizes. CSS analysis and responsive-variant automation would be a separate build tool, not a request-time feature.

The supplied Apache rules protect executable extensions inside public/assets and route nonexistent paths through the main front controller. The isolated PHP 8.5.11/Apache-FPM profile is tested; every other final host remains TO VERIFY. Long-lived instances now rehash source bytes and clear PHP's stat cache instead of retaining stale fingerprints. Generation verifies the loaded bytes match the planned version before atomic publication. Malformed array-valued HTTP asset identities return a non-cacheable 404 without coercion.

Editorial provenance

Source: docs/ASSETS.md. Source SHA-256: 6461065a4a8bb068b786d21dc2271e03a9e22bc75d3aacef6c8f129f921f3cb3.

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