Hot Reload Bundle Laravel Package

Technical Evaluation

Framing correction (important for the assessment): despite the brief describing a "Laravel/PHP package," this is a Symfony bundle with no Laravel integration surface. A TPM must reset stakeholder expectations before any sizing: Laravel teams get zero value from it (Laravel has no bundle registration mechanism, and FrankenPHP hot reload would be wired manually via a Blade partial), and the real addressable audience is Symfony shops that run FrankenPHP in local/dev containers.

Architecture fit

• The bundle's job is narrow and additive: detect FRANKENPHP_HOT_RELOAD and inject the FrankenPHP (Dunglas) hot-reload client asset into rendered pages. That is a Twig/asset-injection concern, well-aligned with Symfony's bundle model (DI extension + optional Twig/kernel listener).
• The value proposition is pure developer experience: it removes a hand-maintained <script> tag and an env-specific template conditional from every application. That is a legitimate but low-leverage scope — one template block of toil eliminated per project.
• It is a dev-only concern leaking into a runtime bundle. The single most important architectural question is whether the injection path is hard-gated to the dev environment. If the bundle has no environment guard and relies solely on env-var presence, the architecture invites a production incident (see failure modes below).

Integration feasibility

• Technically trivial: composer require --dev, register in config/bundles.php under the dev key, set FRANKENPHP_HOT_RELOAD in .env.dev/Docker Compose, done. Realistically a half-day including verification.
• Constraints from the repository's own maintainer rules are a genuine compatibility gate: PHP >=8.1 <8.6, with mandatory Symfony 7.4 / 8.0 / 8.1 minors, while composer.json keeps a broader ^6.0 || ^7.0 || ^8.0. A broad constraint plus an explicitly tested narrow matrix means a Symfony 6.4 LTS shop may resolve successfully but is untested supported, not supported.
• Symfony 8 requires PHP 8.4+, which further fragments the matrix for shops on PHP 8.1/8.2.

Technical risk

• Adoption risk is the dominant risk, not technical risk. 0 stars, 0 dependents, 0 dependents of dependents: there is no community validation whatsoever. For a dev-only asset injection, that is survivable; for anything touching prod boot, it would be disqualifying.
• Provenance/tagging anomaly: the reported last release date (2026-10-13) is in the future. Treat this as a metadata artifact (clock skew, pre-dated tag, or registry inconsistency) and verify against Packagist/composer metadata before pinning. Do not let a version pin be justified by an unverified release date.
• Maintenance concentration: a single-maintainer, zero-signal package. Mitigating factor is that the license is MIT and the surface is a handful of classes — a fork-in-place is cheap insurance.
• Interference risk with the frontend toolchain: the repo's own rules show a Vite + TypeScript pipeline with built assets under src/Resources/public/build. Running a Vite dev server HMR and FrankenPHP hot reload in the same page is a plausible double-reload / conflicting-refresh scenario that must be explicitly tested, not assumed.

Key questions to resolve before commitment

1. Is asset injection hard-gated to kernel.environment === 'dev', or does it key off the env var alone?
2. Does it support CSP nonces / Subresource Integrity, or does it emit a bare <script src> that breaks a strict script-src policy?
3. Is the injector a Twig function, a render event listener, or a kernel.response filter — and does it interact badly with Turbo/HTMX partial swaps?
4. Does it work in both FrankenPHP classic mode and worker mode?
5. Does it collide with Vite/Encore dev-server injection when both are active?
6. What happens when FRANKENPHP_HOT_RELOAD is set but the FrankenPHP dev server is not the one serving the request (stale/404 asset)?
7. Which Symfony minors were actually exercised in CI versus merely permitted by composer.json?
8. Is the release history credible, and is there a tagged, reproducible version we can pin?

Integration Approach

Stack fit

• Fits: Symfony 7.4/8.0/8.1 on PHP 8.1–8.5, running FrankenPHP in local Docker (or bare metal) and using Symfony's native bundle registration.
• Does not fit: Laravel (any version), non-FrankenPHP Symfony apps (zero benefit), Symfony shops that have already solved this with a one-line conditional in their base template — which is the majority of the target audience, and the reason the opportunity score sits at ~48.
• Neutral: Symfony 6.4 LTS shops, who fall outside the tested matrix.

Migration path

1. Baseline first. Confirm the app currently serves FrankenPHP hot reload via a manual template tag. If there is no existing manual wiring, there is nothing to migrate — record this as a net-new DX addition, not a replacement.
2. Add composer require --dev nowo-tech/hot-reload-bundle pinned to an exact verified version (not a range) given the provenance uncertainty.
3. Register the bundle only in the dev array of config/bundles.php; never in the shared array. This is the primary blast-radius control and should be codified in the PR description, not left to reviewer vigilance.
4. Introduce FRANKENPHP_HOT_RELOAD=1 in .env.dev (and the dev service definition), explicitly absent from .env, .env.dist, and any prod image.
5. Delete the manual template script tag in a separate commit from the bundle installation, so rollback is a single revert rather than a mixed diff.
6. Rollback plan: remove the bundle line and restore the template tag. Budget is under 15 minutes; make that explicit to reviewers.

Compatibility and sequencing

• Sequence: verify FrankenPHP version supports hot reload on the target image → verify Symfony minor is inside the tested matrix → install and register dev-only → prove injection in dev → prove absence in a prod-mode smoke run (APP_ENV=prod) → only then open a PR.
• The prod-absence proof is the gate item. Everything else is convenience; this one check prevents the only failure mode that matters.
• If the team runs both Vite HMR and FrankenPHP hot reload, land this behind a feature flag or in a branch and A/B the reload behaviour before adopting. Two reload mechanisms competing in one browser session is a known source of flaky DX that erodes trust in the whole dev container.
• Do not attempt to retrofit this into shared/CI configuration. It is a local developer convenience; CI does not render pages through a browser in dev mode.

Operational Impact

Maintenance

• Near-zero steady-state cost. A dev-only bundle that injects one script tag has no schema, no migration, no data, and no production runtime path.
• The real maintenance line item is dependency drift: with 0 dependents and a single maintainer, an abandoned composer.json constraint can eventually block a Symfony upgrade (composer update conflict on the dev requirement). Assign an owner to check it at each Symfony minor bump and be prepared to fork — MIT license plus a small surface makes a vendored fork the correct default contingency, not a last resort.
• Version pinning is mandatory until the future-dated release anomaly is explained.

Support

• No external support channel exists: 0 stars and 0 dependents mean no community answers, no Stack Overflow corpus, no issue-tracker prior art. Internal teams must own any fix, which is acceptable only because the code surface is small.
• Support burden concentrates on onboarding friction, not breakage: developers who see no reload will blame the bundle, the container, or the volume mounts indiscriminately. Publish a one-page runbook (how to confirm the bundle is registered, how to confirm the env var is present, how to confirm the asset URL resolves) as part of adoption, not after the first incident.

Scaling

• Zero application scaling impact: no request-path work in production, no added latency, no memory footprint, no queue or cache interaction. The only scaling vector is team scaling — number of developers whose local environments must be consistent — and that is handled by committing the dev config, not by the package.

Failure modes

Ramp-up

• Half a day for an engineer already comfortable with Symfony bundles and Docker: install, register, verify, prove prod absence, delete the old template tag.
• Near-zero cognitive ramp for the rest of the team — the desirable outcome is that nobody notices the bundle except that local reloads work. If developers have to think about it, the adoption has failed.
• TPM recommendation: treat this as a low-cost, low-risk developer-experience experiment rather than a platform decision. Approve a timeboxed spike (one engineer, one day) with a hard exit criterion — production-mode smoke test shows no injected asset. If the fork/maintenance contingency is unattractive to the team, the fallback is a three-line conditional in the base template, which delivers the same developer outcome with zero third-party dependency and is a defensible decision to record alongside the spike result.