Asset Composer Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for vendor asset delivery. Referencing CSS/JS that ships inside Composer packages (internal bundles, third-party UI libs) is a small but security-sensitive piece of glue: path resolution, containment checks, traversal rejection. Adopting this package removes ~100–200 lines of in-house code that we would otherwise own and have to security-review forever. The 1.2.0 hardening is exactly the kind of maintenance we avoid by buying.
• Frontend toolchain scope. Supports the decision to not stand up Node/Vite/Encore for teams whose asset needs are "serve files from vendor packages into Twig." Reduces CI surface (no npm audit, no lockfile drift) for internal-tool and back-office products.
• Platform baseline / roadmap. 1.2.0 requires PHP ≥ 8.4 and adds Symfony 8 constraints. This package version is now a forcing function tied to our PHP runtime upgrade — it should be sequenced with, not ahead of, the platform upgrade. Conversely, Symfony 8 readiness extends the dependency's usable life and lowers future upgrade debt.
• Security posture. Deterministic, up-front rejection of .. in asset paths plus a single assertFileInsideProjectDir() containment check is a materially better answer than ad-hoc realpath() comparisons. Supports signing off on a path-traversal class of risk without bespoke code.
• Repository topology / developer workflow. Symlinked Composer path repository support makes monorepo-style local development viable without tripping the containment check. This informs the monorepo-vs-split-repos decision and the "private package via path repo" pattern for internal bundles.
• Use cases it unlocks: internal Symfony bundles shipping their own templates assets; Twig-based admin/back-office apps; air-gapped or vendor-locked deployments where pulling from a CDN or a JS build step is undesirable.

When to Consider This Package

Consider it when:

• You are on Symfony 6.4, 7.x, or 8.x with Twig, and can commit to PHP ≥ 8.4.
• Your front-end assets live inside Composer packages and you want them referenced from templates without copying to public/ or introducing a bundler.
• You develop internal packages via symlinked Composer path repositories (1.2.0 makes this work correctly; earlier versions produced false security violations).
• Asset paths may be influenced by configuration or user-supplied parameters — the hardened traversal checks are the differentiator.
• You want a single, small, auditable integration point (essentially one Twig function) rather than a pipeline.

Look elsewhere when:

• You are on Laravel. This is a Symfony bundle, not a Laravel package — no service provider, no Laravel auto-discovery. Laravel teams should use Vite/@vite or a small custom resolver instead. This is the single most important caveat.
• You are pinned to PHP 8.1–8.3. 1.2.0 is a hard breaking change; 1.1.7 remains the option, but you inherit the weaker pre-hardening path validation.
• You already use Symfony AssetMapper, Webpack Encore, or Vite — overlapping responsibility, and mixing asset resolvers creates confusing precedence.
• You need compilation, minification, cache-busting/versioned filenames, CDN origin rewriting, or Subresource Integrity — this package resolves filenames, it does not build or transform assets.
• Single-maintainer risk is unacceptable for a critical path: the package is small (thin fork/replace cost) but has no vendor SLA.

How to Pitch It (Stakeholders)

For executives: A small, free, open-source Symfony component that lets our templates serve front-end assets directly out of Composer packages, so internal teams don't need a JavaScript build pipeline for back-office and internal tools. The 1.2.0 release is a security and longevity release: it blocks directory-traversal attempts earlier and more reliably, and it declares compatibility with the next major Symfony version — meaning we're not adopting something that strands us at the next platform upgrade. Cost is zero licence; the only cost is the PHP 8.4 runtime upgrade we already have on the platform roadmap.

For engineering leadership: 1.2.0 is a breaking release — PHP ≥ 8.4 required (8.1–8.3 dropped), Symfony ^6.4|^7.0|^8.0 supported. Plan it as part of the PHP 8.4 rollout, not before. Gains: hardened getAssetFileName() (rejects .. up front with BadRequestHttpException), consistent containment checks via assertFileInsideProjectDir(), normalized path comparison so symlinked path repositories resolve, and expanded EN/DE docs for local asset workflows. Integration surface is one Twig function, so rollback and replacement cost are low.

Risk and ask:

• Risk: single-maintainer dependency. Mitigation: tiny API surface, trivially forkable, no runtime data storage.
• Risk: PHP 8.4 is a platform-wide prerequisite. Mitigation: stay on 1.1.7 until the runtime lands; treat 1.2.0 as the target version.
• Ask: approve ~0.5 engineer-day to bump the dependency and regression-test asset links in staging once PHP 8.4 is available; confirm whether any Laravel services were mistakenly scoped in — they are out of scope for this bundle.