Lara Pdf Merger Laravel Package

Technical Evaluation

Architecture fit

• daltcore/lara-pdf-merger is a thin Laravel service-provider wrapper around a lower-level PDF merge engine (typically FPDI/TCPDF-class libraries). It contributes a facade, a config binding, and a merge API — not merge logic itself. That means the package's real architectural weight is in its transitive dependencies, which we inherit and must patch ourselves.
• It presumes a traditional Laravel app structure (auto-discovered provider, facade alias, config publish). It fits a monolith or a job-driven service cleanly; it does not fit an event-driven or serverless PDF pipeline well, since merging is synchronous and in-memory.
• The scope is narrow (concatenate N PDFs into one). If our requirement is ever "merge + stamp + reorder + encrypt + optimize," the abstraction will leak immediately and we will end up reaching into the underlying library anyway.
• Repository is archived. Effective upstream is the fork we create. Treat this as sourcing a code snippet, not adopting a maintained dependency.

Integration feasibility

• Low-to-moderate, and entirely gated on our Laravel/PHP version. The stated support matrix is Laravel 7.0 / PHP 7.4 with a last release of 2020-05-06. Any modern target (Laravel 10/11/12, PHP 8.1+) will require forking composer.json constraints and validating runtime behavior on PHP 8.x, including deprecations around dynamic properties and non-nullable internal function arguments.
• Composer will likely refuse installation outright on a current stack due to php and laravel/framework constraints. The workaround is a VCS/path repository fork plus constraint widening — a change we own forever.
• Facade/alias registration risks collisions in apps that already alias a PDF or PDFMerger facade; this is a config-time annoyance, not a blocker.
• Integration is genuinely cheap if we are staying on Laravel 7/PHP 7.4 for other reasons. On that stack, it is a same-day spike.

Technical risk

• High, and concentrated in abandonment. No security patching, no PHP minor-version fixes, no CVE response. PDF parsing libraries are historically a meaningful attack surface (malformed/parsed untrusted input), and we would be pinning an unpatched transitive tree.
• Supply-chain exposure: the wrapper's own code is small and auditable, but its pinned merge engine and PDF dependencies are not. Auditing the full resolved tree is mandatory before any production use.
• Correctness risk: encrypted/password-protected inputs, malformed files, AcroForm fields, bookmarks/outlines, and mixed page geometries all tend to degrade silently rather than error. Expect output that "works" but drops structure.
• Bus factor / support risk: 28 stars, archived, single-maintainer provenance. No upstream to escalate to.
• Opportunity score 3.16 vs. overall 2.53 suggests the problem space (PDF merging in Laravel) is worth more than this package. That gap is an argument for solving the problem with a different artifact.

Key questions

1. What is our committed Laravel/PHP floor and ceiling for the next 18 months? If it includes PHP 8.2+, this package is disqualified without a fork.
2. Are any input PDFs user-supplied or untrusted? If yes, unpatched PDF parsers are a hard stop pending a dependency audit.
3. Do we need only concatenation, or stamping, reordering, watermarking, compression, and encryption? Scope creep here changes the build-vs-buy answer entirely.
4. What are the largest realistic inputs (page count, file size) and the latency budget?
5. Who owns a vendored fork — named engineer, not a team — and what is the review cadence?
6. Is there an existing internal PDF utility (Ghostscript, qpdf, a Java/Python service) we should call instead of embedding a PHP parser?
7. Does licensing (MIT here, but check the transitive tree — some PDF libs are LGPL) impose obligations on our distribution model?

Integration Approach

Stack fit

• Only a clean fit for Laravel 7 / PHP 7.4. On Laravel 8–9 it is plausible with constraint work; on Laravel 10+ and PHP 8.1+ assume a fork and a PHP 8 compatibility pass.
• Fits a queue-worker or synchronous controller path where the app already has ext-gd/ext-mbstring and comfortable memory_limit headroom. Does not fit a stateless FaaS runtime without re-architecting uploads and temp storage.
• It is a leaf dependency: no schema, no migrations, no persistence, no auth surface. That containment is the main thing that makes it tolerable.

Migration path

• Preferred: do not install the package. Take its merge call shape and implement a PdfMerger interface in-house over a maintained engine (setasign/fpdi + TCPDF/FPDI, or iio/libmergepdf if it still resolves), or shell out to qpdf/Ghostscript if our runtime permits. This preserves the ergonomics without inheriting an archived repo.
• Acceptable: fork to our-org/lara-pdf-merger, widen constraints, add PHP 8 CI, pin and audit transitive PDF deps, and publish internally. Budget a maintenance line item.
• Discouraged: install as-is on PHP 7.4 and defer. That converts a known risk into a scheduled outage.
• Either way, wrap it — never call the facade directly from controllers. A single PdfMergerContract with one implementation means swapping engines later is a one-file change, which is the whole point of not caring whether this package survives.

Compatibility

• Verify Composer resolution against our actual lockfile before estimating; conflicting php/laravel/framework constraints usually surface in minutes and are decisive.
• Test matrix must include: modern PHP 8.x (deprecations), Laravel's current facade auto-discovery, and the underlying engine version — the wrapper's pinned engine is likely older than what we would choose today.
• Check for facade-alias and config-key collisions with existing packages during the spike, not during rollout.

Sequencing

1. Spike (1–2 days): confirm whether it installs on our target stack at all; if not, stop and evaluate the in-house wrapper immediately.
2. Dependency audit: resolve the full tree, run a scanner, review transitive licenses and advisories. Gate here — this is the go/no-go.
3. Interface-first design: define the merger contract, error taxonomy (encrypted input, malformed file, size limit), and output guarantees before writing the adapter.
4. Fork or replace: pick fork-vs-reimplement based on audit outcome; the interface makes this reversible.
5. Golden-file test suite: a corpus of real PDFs (encrypted, scanned, form-filled, large, single-page, zero-page) with hash/structural assertions on output.
6. Load characterization: measure peak memory and wall time vs. page count and file size; derive the guardrails.
7. Async by default: put merging behind a queued job with explicit timeout and memory settings, never in a request path.
8. Rollout + watch: ship behind a flag; instrument merge duration, memory peak, failure rate by error class.

Operational Impact

Maintenance

• The package itself will never update. Every Laravel major upgrade becomes our problem: provider signature changes, facade changes, PHP deprecations. Expect a small but recurring tax — order of a few engineer-days per platform upgrade cycle, plus unplanned work when the transitive PDF engine conflicts with another dependency.
• A vendored fork needs a named owner, an internal release process, and CI on our supported PHP versions. Without that, the fork silently rots and we are back where we started, minus the illusion of support.
• The in-house-over-a-maintained-engine path has the lowest steady-state cost and should be the default recommendation for anything beyond a throwaway internal tool.

Support

• No upstream support channel. Escalation is internal only. Document that explicitly so on-call does not waste time searching for a maintainer.
• Debugging is awkward because failures often originate in the transitive engine, not the wrapper. Plan for engineers to read the underlying library's source, which is why the interface boundary matters.
• The small API surface keeps ramp-up genuinely fast — a new engineer can be productive with the merge call in under an hour. The cost is concentrated in the unknown behaviors, not the API.

Scaling

• Merging is memory-bound and in-process: peak memory scales roughly with the sum of input sizes plus parser overhead, often a multiple of the raw bytes. Large or many-page PDFs will hit memory_limit before they hit CPU limits.
• No streaming or incremental output — this does not scale horizontally within a single request. Scale by queue workers, each with a generous memory ceiling, not by adding web containers.
• Concurrency interacts badly with memory ceilings: N workers × per-merge peak can exhaust the host. Set worker counts against measured peak, not against vCPU count.
• If volume grows into the thousands per hour, the right answer is a dedicated merge service (Ghostscript/qpdf) rather than tuning PHP limits.

Failure modes

• Install/resolution failure on modern stacks — surfaces early, low blast radius, high certainty.
• OOM kill / timeout on large inputs — silent worker death, job retries, possible duplicate processing. Needs explicit size caps and a distinct error class.
• Encrypted or permission-restricted PDFs — either hard error or, worse, silently empty/garbled pages in output.
• Malformed/adversarial PDFs — parser exceptions at best; unpatched-parser exposure at worst.
• Silent structural loss — bookmarks, form fields, annotations, and metadata dropped without error. The most dangerous class, because verification requires content assertions, not status codes.
• Dependency conflict after an unrelated upgrade — build breaks when another package pulls a different version of the PDF engine; typically discovered at deploy time.
• Unpatched-dependency exposure — no CVE response path; risk accrues continuously and is invisible until exploited or flagged by a scanner.

Ramp-up

• Days, not weeks: install/verify, publish config, exercise the merge API against a real corpus.
• The real ramp-up cost is organizational, not technical: establishing the audit gate, naming a fork owner, defining error taxonomy, building the golden-file test suite, and setting memory/timeout guardrails. Budget ~1–2 engineer-weeks for a production-grade adoption, most of it in the safety scaffolding rather than the integration.
• Recommendation: treat daltcore/lara-pdf-merger as reference material, not a dependency. Ship an internal PdfMerger contract over a maintained engine or an external tool, and revisit only if a constraint pins us to Laravel 7/PHP 7.4 and the merge is a non-critical, internal-only convenience.