Page Scanner Laravel Package

Technical Evaluation

Architecture fit. Despite the package label "Laravel/PHP package," the repository is Pushword, a Symfony CMS, distributed as a monorepo of Symfony bundles (core + extensions) rather than a Composer library you require into an existing app. That distinction drives the whole evaluation: its integration surface is a Symfony application (kernel, bundles, Twig, EasyAdmin, Doctrine), not a Laravel service provider. The package name pushword/page-scanner does not match the repository description, so scope is unconfirmed — we must clarify whether we are evaluating a page-scanning capability or the entire CMS platform. Until then, plan against the full CMS.

Key architectural facts a TPM should have on record:

• Persistence: Doctrine ORM; SQLite by default, PostgreSQL and MariaDB supported. No migrations — schema is applied with doctrine:schema:update --force. This is a deliberate design choice, not an oversight, and it has direct production implications (no versioned schema history, no clean rollback).
• Modularity: Bundle-based extension model, so capability is composed rather than configured. Extensions are discovered through tagged services; the AGENTS.md files document the seams.
• Content pipeline: Pages and Media entities; Markdown rendering cached in var/cache/pushword-pools, which intentionally survives deploys and is invalidated only via MarkdownParser::CACHE_VERSION (and SplitContent::TOC_CACHE_VERSION for TOCs). Static builds additionally skip unchanged pages, and both mechanisms depend on byte-deterministic renders.
• Admin: EasyAdmin + EditorJS block editor. Block-editor tools are registered at build time and the committed dist is what ships, so admin customization is a source-build-and-rebuild workflow, not a config change.
• Agent orientation: Commands expose --format=agent (compact single-line JSON) via AgentOutputTrait; docs ship downstream as vendor/pushword/docs/AGENTS.md. This is genuinely unusual and relevant if we intend to drive the CMS from automation.

Integration feasibility. Under a Laravel stack, a direct integration is not feasible; EasyAdmin, Twig, Symfony routing/security, and Doctrine have no bridge to Laravel's Eloquent/Blade/HTTP kernel. Realistic options are: (a) run Pushword as a separate Symfony service and consume its output over HTTP or as a published static build, (b) treat it as a reference implementation for a content pipeline we build ourselves, or (c) only adopt it if the surrounding platform is Symfony. Within Symfony, integration is feasible and conventional: bundle registration, Doctrine connection, prebuilt front-end assets.

Technical risk.

• Ecosystem risk (high): 30 stars, 0 dependents, single-maintainer signal. Bus factor is the dominant risk regardless of code quality.
• Schema risk (medium-high): schema:update --force in production means no migration ledger; changes are applied destructively against a live database.
• Cache correctness risk (medium): the Markdown pool cache persists across deploys and is invalidated by a manually bumped constant. A forgotten bump ships stale renders; entropy in a render path (random()) silently breaks both the pool and the static build's skip-unchanged logic.
• Metadata anomaly (low but flag): last release dated 2026-10-30 (future-dated) and a composite score of 20.28 against an opportunity score of 28.87 — the scoring inputs should not be treated as decision-grade without verification.
• Positive signal: the repository enforces composer stan, rector, test, deprecation ceilings (max[self]=0&max[direct]=0), and a mandatory post-change review with scoped commits. That is a disciplined repo, which materially offsets some ecosystem risk.

Key questions.

1. What is page-scanner relative to the CMS — a sub-package, a feature, or a naming error? This changes effort by an order of magnitude.
2. Is there a supported headless/read API for external consumers, or is the only integration surface static output and Git?
3. What is the official PHP/Symfony support matrix, and what is the upgrade cadence (docs imply one upgrade/<version>.md note per release)?
4. Do we need multi-site/multi-tenant? If so, is that supported or is one install per site expected?
5. Who owns the schema-update step in a deployment, and is --force acceptable to our DBAs?
6. Is the org's target stack Symfony anywhere, or is this evaluation Laravel-only?

Integration Approach

Stack fit. Treat Pushword as a content service, not a dependency. There are two viable shapes:

• Symfony-hosted: Pushword is the CMS for a site; our application consumes pages via Twig rendering or a static export. Lowest friction, but confines us to Symfony for that surface.
• Satellite/headless: Pushword runs in its own container; the Laravel app consumes either (i) a static build published to object storage/CDN, or (ii) a thin read-only HTTP/JSON layer over the Page entity. This preserves our Laravel investment and isolates the CMS lifecycle.

The satellite pattern is the recommendation for a Laravel shop; the Symfony-hosted pattern is correct only if Symfony is already present.

Migration path. There is no incremental adoption path from Laravel — this is greenfield deployment of a second runtime. Content migration is tractable because Pushword accepts content from Git as a first-class source, so existing Markdown can be brought in as files before any admin authoring begins. Media and redirects need mapping (the docs indicate redirects are row-based, which is a signal that URL continuity is handled explicitly and should be migrated deliberately).

Compatibility. Confirm PHP minor version, Symfony LTS line, and Doctrine DBAL version against our base image before committing. On the database side, choose PostgreSQL over the SQLite default if more than one editor or any concurrent write workload is expected; SQLite is acceptable only for a single-author, read-heavy site.

Sequencing.

1. Scope spike (1 week): resolve what page-scanner is; stand up the bundled dev app (packages/dev-app/, composer dev) and produce one page end-to-end.
2. Integration proof (1–2 weeks): prove the handoff — static build published and consumed by the Laravel app, or the read API returning a page payload. Prove cache invalidation works across two deploys.
3. Operational proof (1 week): run doctrine:schema:update --force against a Postgres clone with a schema change; confirm backup/restore and rollback procedure.
4. Admin customization spike (only if needed): any EditorJS tool or EasyAdmin form change is a TypeScript build plus a PHP service tag plus a rebuilt dist. Budget it explicitly; do not assume CSS-level tweaks.
5. Pilot: one low-traffic site, one author, measured over a full release cycle of upstream.
6. Decision gate: adopt / fork-pin / build-our-own, based on pilot findings — not on the star count.

Pin the upstream version and vendor the built assets; do not track main while the project is single-maintainer.

Operational Impact

Maintenance. The absence of migrations is the largest recurring cost: every schema-affecting upgrade must be planned with a manual --force invocation, a pre-change snapshot, and an explicit rollback (restore, not down-migration). Upgrade notes are per-release under upgrade/, so the process is documented — but the burden is on us to execute it. The Markdown pool cache surviving deploys is operationally correct and also a trap: any change to rendered output requires bumping a constant, which means renderer changes are a coordinated deploy, not a hotfix. Cache clears are required after changes (composer console cache:clear) but deliberately do not reach the pool.

Support. With 30 stars and 0 dependents, there is effectively no third-party support market. Upstream is one maintainer; our team is the first line, and a fork is the contingency. Mitigate with a pinned fork in our org, an internal runbook, and a named owner. The upside is a permissive MIT license and a repo whose own quality gates (static analysis, Rector, deprecation ceilings, no-skip test policy) suggest the code will be readable and maintainable by a competent Symfony developer.

Scaling. The scale-out lever is static publishing, which is architecturally sound: the CMS is the write path, the CDN is the read path. Dynamic scaling of the admin/runtime is the constrained path — SQLite caps write concurrency, and the admin depends on prebuilt assets (Monaco is fetched on demand, editor bundles ship as committed dist). Plan for Postgres before multiple editors, and treat the admin as an internal tool that does not need to scale with public traffic.

Failure modes to instrument.

• Stale renders: pool cache not invalidated after a renderer change. Detect by hashing a rendered page against a known-good fixture post-deploy.
• Skip-unchanged static build silently breaking: non-deterministic output (any random() in a render path) makes the content hash miss every time, inflating build time rather than corrupting content — a slow, quiet failure. Alert on build artifact count anomalies.
• Missing admin assets: the build order matters (one package's Vite build empties Resources/public/, so Monaco's package must build after), and EasyAdmin's form-theme precedence and hidden-panel Monaco mounting (0×0 measurement) are known failure shapes. Any admin change gets a rendered-HTML assertion, not a 200 check.
• Schema drift between environments after a --force run that partially applied.
• Agent-mode drift: only some commands support --format=agent; automation built on undocumented commands will break on output-format changes.

Ramp-up. A developer strong in PHP but new to Symfony bundles needs roughly 1–2 weeks to be productive and 3–4 weeks to be safe in the admin/EditorJS layer. The shipped AGENTS.md files and per-package extension docs meaningfully shorten this — they are unusually good onboarding material and encode exactly the non-obvious seams (build-time tool registration, form-theme precedence, cache versioning, scoped-commit discipline) that would otherwise cost days. Budget separately for the front-end toolchain (TypeScript, Vite, committed dist), which is a distinct skill from the PHP side.

TPM recommendation. Do not adopt as a platform dependency on current evidence. Run the four-week spike-and-pilot above, behind a clean interface (static output or read API), with a pinned fork. The decision criterion is not code quality — which looks solid — but whether we can absorb single-maintainer risk plus the no-migrations operational model. If page-scanner turns out to be a narrow, separable capability, re-scope this evaluation around it; the cost profile could improve substantially.