Staccato Bundle Laravel Package

Technical Evaluation

Architecture fit. The first thing a TPM must flag: despite being scoped as a Laravel/PHP package review, cristianradulescu/staccato-bundle is a Symfony bundle, not a Laravel package. It registers an AbstractBundle (Symfony 6.1+ bundle API), ships a Symfony configuration tree (staccato:), depends on Twig templates resolved through the @Staccato namespace, and exposes a Symfony console command (site:build). None of these primitives are recognised by Laravel's service container, config/*.php loader, Blade compiler, or Illuminate\Console. Architecturally it fits a Symfony application (or a standalone Symfony CLI app) cleanly; inside a Laravel codebase it fits only as a decoupled sidecar process, not as an installed library.

Integration feasibility. Three viable routes, in ascending cost:

1. Sidecar CLI (low effort). Keep Staccato in its own Symfony project (the shipped bin/create-blog.sh scaffolds exactly this) and invoke site:build from the Laravel CI pipeline or a scheduled job, publishing the output to a CDN/static host. Zero coupling to Laravel internals.
2. Selective reuse (medium effort). Take the framework-agnostic pieces — tempest/markdown, tempest/highlight, and the front-matter/OutputPathResolver logic — and drive them from an Artisan command. This forfeits the bundle's templates, config tree, and build-safety validation unless re-implemented.
3. Full port (high effort). Reimplement the bundle as a Laravel package: service provider, config/staccato.php, Blade or Twig-bridge templates, artisan staccato:build. The override convention (templates/bundles/StaccatoBundle/<file>.twig) and Twig namespace semantics have no direct Laravel analogue, so template parity is the bulk of the work.

Technical risk.

• Pre-1.0 maturity. v0.1.0 is a first release with no BC guarantees, no deprecation policy, and no published support window. Treat every minor bump as potentially breaking.
• Bus factor. Single-maintainer OSS (cristianradulescu). A build-critical dependency on one person's side project is a continuity risk.
• Framework coupling. The value is concentrated in the Symfony-specific surface (config tree, templates, command), which is precisely the part that does not transfer to Laravel.
• Dependency provenance. tempest/markdown and tempest/highlight belong to the Tempest ecosystem — well-suited libraries, but their release cadence is outside our control and independent of Staccato's.
• Mitigating signals. The quality posture is unusually strong for a v0.1.0: PHPStan level 7, PHPUnit, PHP CS Fixer, a composer qa gate, and — most importantly — build safety that validates config, content, duplicate output paths, and pagination conflicts before the build directory is cleaned, so a failed build preserves the previous output. That is the single most reassuring line in the release notes for a TPM.

Key questions.

• What PHP and Symfony version constraints does composer.json declare? Does it support Symfony 6.4 LTS and 7.x?
• Is there any intent to publish a framework-agnostic core (or a Laravel adapter), or is Symfony-only a permanent stance?
• What is the support/versioning commitment post-1.0? Is there a roadmap to 1.0?
• Is the CLI invocation documented as a stable contract, or is the console command considered internal?
• Does site:build read APP_ENV/kernel environment only, or is there an explicit flag for draft inclusion? Environment-aware drafts need mapping in a non-Symfony pipeline.
• How are asset and stylesheet paths resolved when the package is vendored rather than installed at app root?

Integration Approach

Stack fit. Poor as an installed dependency in Laravel; good as a build tool invoked out-of-process. If the target is genuinely Symfony (or the team is framework-agnostic and just wants a static site generator), the fit is high — the bundle ships complete default templates (base, page, home, 404, rss.xml, sitemap.xml), so a site builds out of the box with no templates of its own.

Migration path. Nothing to migrate from — this is a greenfield adoption and, at v0.1.0, an evaluation-grade commitment. Recommend a time-boxed spike (1–2 days) proving the sidecar route before any decision to port.

Compatibility. Confirmed by the notes: PHP with Composer, Twig, tempest/markdown, tempest/highlight, optional fakerphp/faker for --use-fixtures. Unconfirmed: exact PHP/Symfony version floors, Twig major version, and whether fakerphp/faker being a suggestion means fixture builds fail closed with a clear message or fail obscurely. Sub-path hosting is explicitly handled (base_url path applied to every internal link and stylesheet) — relevant if we publish to GitHub Pages project sites or a nested CDN prefix.

Sequencing.

1. Spike — scaffold via bin/create-blog.sh in a throwaway repo; build twice, once with a deliberately broken front-matter file, to verify the "failed build keeps previous output" claim empirically. Verify sub-path hosting by deploying under a non-root path.
2. Decide — sidecar vs. port, priced against the spike findings.
3. Pilot — one low-risk surface: internal docs, a changelog, or a marketing microsite. Not the primary product site.
4. Harden — pin the exact version, vendor-lock the transitive tempest/* versions, add a CI contract test that the build output matches expectations.
5. Adopt or exit — revisit at Staccato 1.0 or if the maintainer signals abandonment.

Operational Impact

Maintenance. Modest but non-zero. The static-output model means no runtime to patch — big operational win. The maintenance cost is in the dependency itself: pre-1.0 version pinning, watching for breaking releases, and periodically re-evaluating the bus factor. Budget a small recurring review, not a standing owner.

Support. Community OSS with a single maintainer and no commercial backing. Escalation path is upstream issues. Because the build is invoked in CI rather than serving production traffic, a maintenance stall is a velocity problem, not an availability problem — which materially lowers the risk of adopting it for a secondary site.

Scaling. Effectively unbounded and cheap: output is static HTML, RSS, sitemap, and mirrored assets (build/assets/), all cacheable and CDN-servable. Build time scales linearly with content volume and is the only real ceiling; pagination (articles_per_page) and asset mirroring on every build are the two knobs to watch as content grows. No database, no runtime services, no session state.

Failure modes.

• Misconfigured base_url — silent link and stylesheet breakage under sub-path hosting. Highest-likelihood failure; needs a post-build link check in CI.
• Content parse errors — malformed YAML front matter (the loader tolerates CRLF, BOM, and trailing-whitespace edge cases, but not arbitrary YAML). Caught pre-clean by validation, so output is preserved.
• Path collisions — duplicate output paths and pagination conflicts are validated before cleaning, so these fail safely rather than producing a half-written site.
• Reserved-path surprises — index.md or any slug resolving to / is rejected by design, since / is the generated homepage. Content authors will hit this; document it.
• Draft leakage — environment-aware draft handling (dev includes, prod excludes) is correct in spirit but is a config-inference risk. Verify explicitly in the pipeline rather than trusting environment detection.
• Missing optional dependency — --use-fixtures without fakerphp/faker installed; confirm the error is legible.
• Asset mirroring regressions — the default theme is recopied on every build; if include_default_styles is toggled or custom stylesheets/highlighter_css are added, verify the link/copy behaviour holds.

Ramp-up. Low for content authors — Markdown plus a six-key front-matter contract (title, slug, date, excerpt, draft), directory-style URLs that map intuitively (content/docs.md → /docs/). Moderate for engineers: Symfony bundle conventions, Twig template overrides, and the config tree are unfamiliar territory for a Laravel team, which is exactly why the sidecar route is preferred over embedding. The default theme and out-of-the-box templates mean a demo site is achievable on day one; production confidence is a week of spike work.