Static Site Bundle Laravel Package

Technical Evaluation

Architecture fit. This is a low-ceremony, opt-in layer over the framework's existing routing and controller stack rather than a parallel templating system. Marking controllers with #[Prerender] at method or class level means the pages we already serve dynamically can be emitted statically without a rewrite — the controller, its DI dependencies, its Blade/Inertia output and its middleware all remain the single source of truth. For a TPM this is the most attractive property of the package: it defers the "do we build a separate static site generator?" decision and keeps one codebase and one review surface. The ParamsProviderInterface and inline parameter-set features cover the catalogue/listing case (blog posts, product pages) that usually forces teams into a second tool.

Integration feasibility. Superficially a same-day spike: install, annotate a handful of controllers, run static-site:list to preview, static-site:generate to write. Output targets a local directory or any Flysystem operator, so S3/FTP delivery reuses disks we almost certainly already have configured, and there is no bespoke deploy code. clean_urls removes a whole class of web-server configuration work (<path>/index.html) and makes the artifact portable across hosts — useful if we ever move off the current CDN/edge provider.

Technical risk. Several items need closing before this is more than a spike:

• Pre-1.0 (v0.1.0). No stability contract. Expect breaking changes to attribute names, command flags and CLI output. Pin exactly.
• Platform constraint. PHP 8.3 plus Symfony 7.4 or 8.x is a narrow, very recent window. Symfony 7.4 is not a widely deployed pin, so this almost certainly requires a current Laravel line and may conflict with the symfony/* versions already locked in our app. This is the single most likely blocker and should be checked first.
• Extension model. Replacing behaviour means redefining internal service IDs (renderer, dumper, URI provider, filesystem). That is an internal API, not a documented contract — any customisation we build becomes upgrade friction.
• Redirects become meta-refresh stubs. Functionally it works, but it loses HTTP status codes, breaks non-HTML consumers and is materially worse for SEO and for anything doing link checking. Any migrated route with a 301 has to be handled at the CDN/edge instead.
• All-or-nothing page semantics. Any non-2xx (other than a redirect) fails the page. There is no stated partial-success or resume policy, which matters for large builds.
• Optional dependency coupling. HTML/XML minification pulls in sensiolabs/minify-bundle; we need to confirm it coexists with our existing asset pipeline rather than double-minifying.

Key questions for the maintainer / spike.

1. Which Laravel versions are supported, and is the Symfony 7.4/8.x constraint hard or advisory?
2. Does prerendering execute the full HTTP stack per page — sessions, CSRF, auth middleware — and how should authenticated or personalised routes be excluded?
3. Is there incremental generation, or is every run a full rebuild? Any caching of rendered fragments?
4. How is the route set determined — annotations only, or can we drive it from a sitemap/route list?
5. How do cache-busting, asset hashing and time-dependent content behave when the build runs on a schedule?
6. What is the release cadence and support expectation pre-1.0? Is there a maintainer bus factor?
7. Interaction with Livewire, Inertia and any client-side hydration?
8. Are 404/410 and other status pages emittable, or only 2xx plus meta-refresh?

Integration Approach

Stack fit. Assumes a modern Laravel app on PHP 8.3 with Flysystem disks already configured (S3 for production, local for CI artifacts). Nothing in the release suggests a need for new infrastructure: the build is a console command, the artifact is a directory tree, delivery is an existing disk. That keeps the change inside the application repo and out of platform work.

Migration path. Do not treat this as a cutover. The natural sequence is:

1. Constraint spike (½ day). In a throwaway branch, composer require and resolve the Symfony/Laravel matrix. If it will not install against our lockfile, the evaluation ends here — that is the cheapest possible failure.
2. Local pilot (1–2 days). Annotate 5–10 representative routes: a static marketing page, a parameterised detail page driven by a provider, and one route with a redirect. Generate to a local directory, diff the output against the live pages, verify absolute links under base_uri and confirm clean_urls output serves correctly from a plain file server.
3. Provider integration (2–3 days). Implement ParamsProviderInterface for the high-cardinality content (posts, products). Measure build wall-clock and output size at realistic cardinality — this is where the package will either scale or not.
4. Delivery wiring (1–2 days). Point the dumper at the S3 disk and add CDN invalidation via PageRenderedEvent/PageDumpedEvent. Use PageFailedEvent to fail the CI job loudly rather than ship a partial site.
5. CI job + shadow traffic. Run the build on a schedule against a preview bucket first; compare against the dynamic site before any origin switch.
6. Cutover by route group, starting with marketing pages, leaving anything authenticated, personalised or high-churn on dynamic rendering indefinitely.

Compatibility. Verify against the actual lockfile, not the release notes. Specifically: symfony/* pins, whether sensiolabs/minify-bundle collides with existing minifiers, whether our controllers depend on request state (session, locale from cookies) that will not exist at build time, and whether base_uri misconfiguration produces silently wrong absolute URLs rather than an error.

Sequencing. The dependency spike gates everything; the parameterised-route pilot gates the business case. If step 3 shows build times that scale badly and there is no incremental mode, the package is still viable for a small marketing site but not as a wholesale replacement for dynamic rendering.

Operational Impact

Maintenance. Pre-1.0 means upgrade churn is a certainty, not a risk. The surface we touch is small (attributes, two commands, optionally one provider), so our own migration cost per bump is bounded — but any custom renderer/dumper/URI-provider/filesystem swaps bind us to internal service IDs and should be treated as a fork we own. Pin the exact version; budget an upgrade review per minor release.

Support. Assume a small maintainer team. Mitigation is favourable: the extension points, the fact that it sits on our own controllers, and the fact that the output is plain files mean we can vendor or fork the package without stranding the site. The artefact is recoverable — worst case we redeploy the dynamic site from the same git SHA.

Scaling. Read path is trivially scalable: static files behind the existing CDN, no runtime PHP, better cache-hit ratio and lower origin cost. Write path is the constraint. Build time is roughly linear in (annotated routes × parameter sets), and there is no stated incremental generation, so every run is a full rebuild. At low hundreds of pages that is minutes; at tens of thousands of product pages it becomes a scheduled job with its own capacity planning. --route/--path globs give partial-run capability, which is the lever we would use to shard builds by content type if needed.

Failure modes to design against.

• Silent misconfiguration of base_uri — wrong absolute links, correct-looking build. Assert on a canonical sample page.
• Partial S3 deploys — a failed run after some files are written leaves a mixed-generation site. Generate to a staging prefix and promote atomically, or version the prefix and flip the CDN origin.
• Meta-refresh redirects — no status codes and no link equity; anything with an SEO or API-consumer dependency needs edge-level 301s instead.
• Parameterised route explosion — a provider returning an unbounded set (soft-deleted records, drafts, locale permutations) can multiply build time and publish unintended pages. Bound the provider's output explicitly and diff the generated file count between runs.
• Dynamic content frozen at build time — prices, stock, timestamps. Needs an explicit "is this page allowed to be stale for N minutes" decision per route, and a rebuild schedule that matches.
• Stale CDN after a successful build — the PageDumpedEvent hook is the place to purge; if it fails, the site is correct on disk and wrong in front of users.

Ramp-up. A competent Laravel developer is productive with the attributes and two commands in under a day; the pilot in the migration path is more about validating assumptions than learning the API. The real ramp-up cost sits outside the package: teaching the team that publishing now depends on a build pipeline, that some content is intentionally stale, and that cache invalidation is part of "done". Plan for one owner of the build job and a documented runbook (how to trigger, how to roll back, how to verify) before the first production route is served statically.