Static Generator Laravel Package

Technical Evaluation

Architecture fit. Pushword is a Symfony CMS delivered as a monorepo of bundles, not a standalone library. The static generator is one surface of that CMS: it consumes the Page/Media entities, the Twig render pipeline, the PushwordEvents event system, and Doctrine-backed content. That makes it a strong fit if we are adopting Pushword as the content system, and a poor fit as a generic "export my existing site to HTML" utility. The README-level claim ("create, manage and maintain your websites — from the admin, from Git, or from your AI agent") describes an opinionated authoring model, so the integration cost is concentrated in content modeling and workflow, not in the generator itself.

Integration feasibility. Two paths, materially different in cost:

• Adopt Pushword as CMS + static output. Feasible. We get admin UI, Git-based authoring, Markdown/EditorJS content, and the static build in one stack.
• Bolt static export onto an existing Laravel or bespoke PHP app. Not feasible as a library dependency. The realistic pattern is a build-time Symfony container that renders our content and emits files, with Laravel remaining the runtime for everything else. That is a second runtime, a second content store, and a second set of conventions to maintain.

Note the brief describes this as a "Laravel/PHP package." It is Symfony. Any plan assuming Laravel service-provider drop-in should be discarded before estimation.

Technical risk. Ranked:

1. Adoption signal. 30 stars, 0 dependents. No downstream production users to absorb upgrade friction, and no community answers when something breaks. Assume we are the largest consumer.
2. No migrations. Schema changes go through doctrine:schema:update --force. That is safe in dev and hostile in production unless we own snapshot/restore and a pre-deploy schema diff.
3. Non-hermetic builds. The static build's skip-unchanged logic depends on byte-deterministic renders and a content-hash cache, plus a Markdown fragment pool at var/cache/pushword-pools that is deliberately kept across deploys. Correctness therefore depends on cache-version discipline: a render-path change that does not bump MarkdownParser::CACHE_VERSION (or SplitContent::TOC_CACHE_VERSION for TOC) ships stale HTML silently. Any entropy in a render path — timestamps, random(), unstable ordering — turns the incremental cache into a full rebuild with no error.
4. Release metadata. Last release is listed as 2026-10-30, which postdates the assessment date. Treat the field as unreliable until verified against tags and Packagist; do not plan a cadence around it.
5. Silent template failures. The project's own admin UI rules call out blocks that are silently dropped with a 200 response. The same class of failure — output missing, status green — is the dominant risk in a generated site.

Key questions.

• What exactly does the static generator emit: full tree, incremental, or skip-unchanged into an existing directory? What is the CLI contract and does it support --format=agent?
• Supported Symfony and PHP ranges, and is there an LTS-aligned branch or only main?
• Does it handle multi-site and multi-locale in one build, and how are routes and redirects tracked (content/redirection.csv is referenced for doc slugs — is there an equivalent for site content)?
• Deployment target assumptions: plain directory, S3, CDN invalidation hooks?
• Who is the maintainer, and what is the bus factor? Is a fork expected to be routine?
• Is there a published upgrade-note convention we can rely on per release (upgrade/<version>.md)?

Integration Approach

Stack fit. Symfony-first, Doctrine-first, Twig-first. In a Laravel estate, treat Pushword as a build tool in CI, not an application dependency: a container runs bin/console commands, produces a static artifact, and the artifact is deployed independently of the Laravel app. Accept that content authoring then happens in Pushword's admin or in Git, not in Laravel's Eloquent models.

Migration path.

1. Content extraction from the current system into Page/Media entities, mapped deliberately — this is the largest single line item.
2. Redirect preservation. Slugs are path-derived, so any moved or renamed page needs a 301 row; the docs slug/redirection.csv mechanism is the pattern to replicate for site content.
3. Schema bring-up in non-prod with doctrine:schema:update --force, then a captured schema snapshot as the production baseline.
4. Cutover per section, not big-bang, with the old and new sites served from separate paths behind the CDN.

Compatibility. Verify three axes before committing: PHP version against our platform images, Symfony version against anything else we run, and database engine. SQLite is the default and the dev-app path; production on PostgreSQL or MariaDB introduces engine-difference risk precisely because there are no migrations to normalize it. Run the build against the production engine in CI, not SQLite.

Sequencing.

1. Spike (timeboxed). Five pages, one image, one redirect, built twice from clean caches. Confirm byte-identical output on the second run. If that fails, the incremental story is not real and the value proposition changes.
2. Pin. Lock the commit or tag; the package is a monorepo member, so pin the whole tree, not a subpackage version.
3. CI build job. Cache the fragment pool, assert artifact diff is empty on a no-op rebuild, publish a build manifest.
4. Authoring workflow decision. Admin vs Git vs agent-driven. This determines who owns content review and is a people decision, not a technical one.
5. Pilot section, then rollout.
6. Schema snapshot and restore drill before the first production schema change.

Operational Impact

Maintenance. Two obligations fall on us that a normal package would absorb: schema management (no migrations) and cache-version discipline (bumping the Markdown and TOC cache constants whenever rendered output changes). Both are small, both are easy to forget, both fail silently. Add a checklist item to the PR template for rendering changes.

Support. Zero dependents means no external backstop: no Stack Overflow corpus, no third-party tutorials, no ecosystem of plugins to lean on. MIT licensing is the mitigation — budget for the ability to fork and patch, and confirm the team can read the Symfony bundle wiring well enough to do so. The repo's AGENTS.md and shipped vendor/pushword/docs/AGENTS.md are genuinely useful for agent-assisted maintenance, but they encode their conventions (composer stan, composer rector, never vendor/bin/phpunit, scoped git commit --only). Those gates do not exist in our repo and must be built or explicitly waived.

Scaling. Serving scales trivially — static files on a CDN. Build time is the real constraint. The skip-unchanged cache is what makes large sites tractable, which means the shared fragment pool becomes a scaling dependency: it must persist between builds, and it must not be written by two concurrent builds. Serialize builds per site or shard the pool per branch.

Failure modes to instrument.

• Stale content shipped green. Cache version not bumped. Detect with a canary page whose expected text is asserted post-deploy.
• Full rebuild every time. Entropy in a render path or a cache that never hits. Detect by alerting on build duration and on changed-file counts exceeding a threshold for a no-op commit.
• Content silently absent. Dropped Twig blocks or unregistered editor tools render nothing and return 200. Detect by asserting on rendered HTML in smoke tests, never on status codes alone.
• Schema drift. schema:update against production without a snapshot. Gate deploys on a schema diff check and a restore-tested backup.
• Lost redirects. Slug moves without a 301 row. Crawl the old sitemap against the new build in CI.

Ramp-up. Expect two to three weeks for a Symfony-competent engineer to be productive across the content model, the build pipeline, and the cache invariants; longer for anyone coming from Laravel, because the mental model (bundles, services, Doctrine entities, Twig inheritance) does not transfer. Assign a single named owner for the Pushword integration — with 0 dependents and one upstream, an unowned integration decays into an unupgradeable pinned fork within two release cycles.

Recommendation posture. Worth a timeboxed spike if we are prepared to adopt Pushword's content model and Symfony as a build-time runtime. Not worth pursuing as a bolt-on exporter for a Laravel application. The go/no-go gate is the determinism test in step 1, not the feature list.