Dynamicpdf Plugin Laravel Package

Technical Evaluation

Architecture fit

• This is still not a Laravel package — it is an October CMS plugin (renatio/dynamicpdf), installed into plugins/ and bootstrapped through October's Plugin.php registration lifecycle. It assumes october/system + october/rain and will not resolve or function in a vanilla Laravel application.
• Fit remains binary: current October CMS estate → strong fit; Laravel-only estate → not reusable, with barryvdh/laravel-dompdf or spatie/laravel-pdf as the in-house alternative.
• Where October is in play, the value proposition is unchanged and now better supported: PDF templates are backend-managed content (layouts, partials, Twig) with page numbering, password protection, and file output handled by the plugin. The 9.x dynamicpdf:check command plus Reset to Default materially improves the architecture: templates that ship in code can be treated as the source of truth, with backend edits as tracked overrides rather than the only copy. That converts a former governance weakness into a managed override model.
• New in 9.x: a sandbox that governs what template expressions can reach (model methods, relations, accessors). This is a genuine architectural improvement — template authoring is no longer implicitly full-trust PHP-adjacent code — but it introduces a silent-coercion contract we must design around (see risk).
• Coupling is still to October Twig and the Backend UI, not Blade. Any shared web/PDF template strategy needs an explicit Twig/Blade boundary decision.

Integration feasibility

• Happy path remains low effort: composer require, plugin registration, define Template/Layout records, call the PDF facade with a data array, receive a stream/download/response.
• New precondition: we must land on 9.x, not 8.x or earlier. 9.0.0 was a breaking release with migrations and an UPGRADE.md; 9.0.1 is explicitly described as "fixes after the 9.0.0 upgrade." Treat 9.0.1 as the floor and 9.0.0 as a version to skip.
• Real effort still sits in data assembly and asset resolution: fonts, logos, CSS, images must resolve in a headless render context, and remote fetching is a latency and SSRF surface.
• Rendering engine question (DomPDF vs wkhtmltopdf) is unanswered by these notes and still determines our CSS ceiling and container story.
• Testability improved: PDF::fake()->throwOnRender($exception) lets us assert render-failure handling in CI rather than discovering it in production. This lowers integration risk for the queue/error-surfacing work.

Technical risk

• Adoption risk is materially downgraded from the prior assessment. The issue references (#349–#353), an UPGRADE.md, a maintenance artisan command, and a testing fake indicate active maintenance, a real user base, and release hygiene — not an abandoned 30-star plugin. The earlier "unverified maintenance signal / anomalous future release date" concern is superseded; the current signal is active, responsive maintenance at major version 9.
• But the maintenance model changed shape. A mature package at v9 with breaking majors means upgrade cadence is now the risk, not abandonment. We must budget for periodic majors with migrations and an upgrade guide, and pin versions deliberately.
• Security regression shipped in 9.0.0 — highest-priority finding. allowSelfSignedCertificates() / DYNAMICPDF_ALLOW_SELF_SIGNED silently disabled TLS certificate verification in production during 9.0.0 and is only restored in 9.0.1. Two conclusions: (a) 9.0.0 must be treated as a security-defective release and blocked in any pinned-version policy; (b) the production-only security gate is evidently under-tested upstream, so we need our own regression assertion that TLS verification is on in production, not just a version pin.
• Silent data loss via the sandbox. When the sandbox blocks a model method, an unloaded relation, or an accessor outside $appends, it substitutes an empty value and emits only a log warning naming template and line. The PDF still renders — with a blank field. For invoices, statements, or shipping labels this is a correctness failure that passes every smoke test and every assertSee check unless we specifically assert on content. This is the single most dangerous behaviour change for us.
• Governance risk is now partially mitigated, not eliminated. Customization is detected precisely (whitespace/indentation-only layout differences no longer flagged as customized), so we can distinguish "shipped default" from "locally edited." That supports a real policy — but DB-stored overrides still sit outside version control unless we adopt the check command and a reset convention.
• Documented behaviour change: byCode() semantics when no database row exists are now specified in UPGRADE.md. Any code path relying on implicit creation or fallback must be re-verified; this is exactly the kind of subtle change that produces "works on staging, empty template on prod."

Key questions

1. Are we on October CMS today, or is this being evaluated as a Laravel package? (If the latter: stop, re-scope.)
2. Which October and PHP versions does 9.x require, and does it force an October v3 / Laravel 10+ upgrade we haven't scheduled?
3. What does the 9.0.0 UPGRADE.md list as breaking, and does our template set rely on any of it (particularly byCode() with no DB row)?
4. Which PDF engine, and does it meet our CSS/layout requirements (headers, page breaks, tables, custom fonts)?
5. Do we ship template defaults in code and treat DB rows as overrides, or are templates DB-only? (Determines deploy, rollback, and review story — and whether dynamicpdf:check is useful to us.)
6. Does the sandbox warn on a log channel we actually monitor and alert on?
7. Does it support queued/background generation, or is rendering synchronous in the request?
8. Is password protection a genuine requirement, or complexity we would pay for and never use?

Integration Approach

Stack fit

• Only viable inside an October CMS application. Prerequisites now include: October version compatible with plugin 9.x, write access to plugins/, a storage disk for generated artifacts, and a monitored log channel for sandbox warnings.
• October is Laravel underneath, so queue workers, storage disks, config, env handling, and Eloquent all behave as expected. Plugin migrations (introduced in 9.0.0) run through the standard October update path.
• PDF::fake() / throwOnRender() aligns the plugin with our normal Laravel testing conventions — render-failure paths become unit-testable, which removes a common objection to adopting third-party rendering code.

Migration path

• Pin 9.0.1 or later explicitly; exclude 9.0.0. Add a lockfile assertion so a transitive or manual upgrade cannot land on the TLS-defective release.
• Add a production security regression test: config the self-signed switch off (default), render in a production-equivalent environment, and assert certificate verification is enforced. Do not rely on the changelog as our control.
• Adopt dynamicpdf:check in CI from day one. Ship canonical template defaults in code, let backend edits be overrides, and treat the check output as a drift report rather than a curiosity.
• Start with one low-stakes document (receipt, packing slip, internal report) rather than invoices or contracts, to validate engine fidelity, asset resolution, and — critically — that sandbox coercion doesn't blank required fields.
• If we generate PDFs today via a hand-rolled library, keep both paths live behind a feature flag and diff output for a release cycle before cutover.

Compatibility

• Verify October major-version support explicitly for 9.x; a plugin pinned to October v2 blocks a v3 upgrade and should be flagged as upgrade tax at adoption.
• Check the PHP constraint and whether the engine pulls a system binary (wkhtmltopdf) — that decides whether container images and CI runners change.
• 9.0.1 adds no new migrations, but 9.0.0 did; plan a controlled migration window and confirm rollback behaviour for the plugin tables.
• Font/locale support: validate with a real document containing non-Latin content and currency glyphs, not "Hello World."

Sequencing

1. Spike (1–2 days): install 9.0.1 in a scratch October instance, render one real template, confirm engine and CSS fidelity, and deliberately trigger a sandbox warning to see how it surfaces.
2. Production-parity security check: assert TLS verification is enforced; assert the self-signed toggle is ignored in production.
3. Hardening: queue-backed generation, storage disk wiring, asset absolutization, error surfacing to the Backend UI, log alerting on sandbox warnings.
4. Template governance: seed/export command, dynamicpdf:check in CI, explicit Reset to Default policy, staging-first editing.
5. Production cutover: feature flag, output diffing, then retire the legacy path.
6. Upgrade runway: read UPGRADE.md before every major, pin deliberately, budget a maintenance window per major. Fork contingency remains a pre-approved fallback, but is now a lower-probability scenario.

Operational Impact

Maintenance

• Steady-state cost is now clearly not abandonment risk — the package is actively maintained with an upgrade guide, a maintenance command, and a responsive issue tracker. The cost is upgrade cadence: majors with migrations and behaviour changes must be scheduled, tested, and rolled out rather than floated.
• Version pinning discipline becomes an operational control. A floating constraint would have auto-adopted the 9.0.0 TLS regression.
• Template drift is the recurring cost, but it is now measurable: the customized-vs-default check turns an invisible risk into a reviewable report. Assign an owner and a reset convention.

Support

• Support still splits into (a) template authoring help for business users and (b) rendering defects for engineering. The sandbox raises the stakes on (a): an author who references a relation that isn't loaded gets a blank field in a customer-facing PDF and no visible error. A written authoring guide covering sandbox rules and $appends is now mandatory, not nice-to-have.
• External community is now a credible escalation path, unlike the prior assessment — but an internal runbook and named owner are still required.

Scaling

• Rendering remains CPU- and memory-bound; large image-heavy HTML can exhaust PHP memory limits.
• Move all non-interactive generation to queues. Synchronous rendering inside a request surfaces as timeouts and inflated p95 latency under month-end batch load.
• Cache compiled templates where the engine allows and pre-warm fonts to avoid per-request parsing cost.
• Sandbox warning logging adds a small but non-zero write volume per render; ensure it goes to a sampled or rate-limited channel under bulk load or it becomes log noise that nobody reads.

Failure modes

• Silent blank fields from sandbox coercion — new, highest likelihood, lowest visibility. Renders "successfully," passes smoke tests, ships a PDF missing a customer name or amount. Mitigate with content assertions on critical fields in CI, a sandbox-warning alert, and a post-deploy log review of the first production batch.
• TLS verification silently disabled in production — a 9.0.0 defect corrected in 9.0.1, but evidence that this path is under-tested upstream. Mitigate with a version floor plus our own production-parity assertion.
• Memory/execution timeout on large or image-heavy documents — queue workers, raised limits on the worker pool only, documented size caps.
• Asset resolution failures — missing logos or blocked egress produce degraded PDFs; fail loudly rather than emitting blank headers.
• Binary dependency absence (if wkhtmltopdf) — works locally, dies in a slim container; pin in the image and smoke-test in CI.
• Disk/queue saturation — generated files accumulate; enforce retention and cleanup.
• byCode() with no DB row — behaviour is now documented rather than implicit; verify any code path that assumed a fallback, or a missing template surfaces as an empty document in an environment where seeding didn't run.
• Major-upgrade breakage — 9.0.1 exists specifically because 9.0.0 needed fixes; assume every future major needs a stabilisation window and never auto-merge a major.
• Password-protected output cannot be indexed or text-extracted downstream — confirm no archival or invoice-processing pipeline depends on parsing those files.

Ramp-up

• An engineer familiar with Laravel picks up October plugin conventions in ~3–5 days; the PDF engine's CSS quirks remain the longer tail.
• Add half a day for the 9.x specifics: sandbox semantics, $appends requirements, dynamicpdf:check, and the testing fake.
• Business users need a short written guide plus 2–3 canonical examples, now explicitly covering sandbox restrictions — otherwise self-service inverts into support load and silent data defects.
• Recommend a single named owner for the PDF domain, with the version-pin policy, template governance convention, and log-alerting configuration agreed before the first production document ships.