Pdf Merger Bundle Laravel Package

Technical Evaluation

What is actually being evaluated. tomsgu/pdf-merger-bundle is a Symfony bundle — a packaging convention whose entire value is kernel integration: bundle registration in bundles.php, DI service definitions, a configuration tree, parameter injection. Laravel exposes none of those seams. Laravel's PackageManifest reads extra.laravel.providers; this package advertises nothing there. Installed in Laravel, the bundle is inert. The reusable asset is the transitive dependency tomsgu/pdf-merge — a plain-PHP merger class — plus the bundle's YAML as a working configuration reference. Treat the bundle as documentation and integration precedent, not as a dependency.

Architecture fit. Poor for the bundle, good for the underlying library. The library is framework-agnostic and will drop into Laravel behind a thin adapter. The bundle adds a Symfony-coupling layer you would immediately have to bypass.

Integration feasibility. Moderate, and the difficulty is not technical. Composer resolution is clean; Laravel already ships several Symfony components, so incremental weight is modest. The work is roughly a 50-line service provider plus an interface. The actual risk is choosing the wrong abstraction level — binding call sites to library classes instead of to a contract you own.

Technical risk.

• Adoption signal: 8 stars, 0 dependents, scored 4.48. For a small utility this is not disqualifying, but you will be among the first serious consumers and you inherit all edge-case discovery.
• Underlying engine: tomsgu/pdf-merge sits on an FPDI/FPDF-family parsing layer. Free FPDI has documented limits on compressed PDFs and object streams, and no encrypted-PDF support. This single fact determines whether the tool works on your document corpus — verify empirically before committing.
• Bus factor 1. MIT is clean, but audit the transitive chain (FPDF permissive, TCPDF LGPL, FPDI MIT plus paid add-ons). LGPL in an unmodified SaaS context is usually fine; get a legal sign-off rather than assuming.
• Attack surface. PDF ingestion is a classic DoS vector: malformed files, object-stream bombs, unbounded page counts.
• The 39.92 opportunity score reads as "immature space with room to improve" — which cuts both ways. It justifies building your own adapter layer; it does not justify betting a customer-facing workflow on an unproven dependency.

Key questions to close in a spike.

1. Which PDF engine, and does it handle our corpus (compression, encryption, forms)?
2. Peak memory and wall time at our p95 and p99 file size/page count.
3. Full PHP and Laravel version support matrix; does it pin symfony/* in a way that conflicts?
4. Does the library have constructor arguments reachable only through Symfony config?
5. Are AcroForms, bookmarks, outlines, and metadata preserved or silently flattened?
6. Is output byte-deterministic across runs?
7. Is there a SECURITY.md, and what is the issue-response reality?

Integration Approach

Stack fit. Consume tomsgu/pdf-merge directly. Do not composer require the bundle into a Laravel application — it would be unregistered dead weight carrying Symfony contracts you do not exercise.

Migration path.

1. Spike branch. Install the library only. Push 20 representative real-world PDFs from your corpus through it. Record peak memory, wall time, and output fidelity against the source documents.
2. Define the contract. App\Contracts\PdfMerger with merge(array $paths, array $options): string. This interface is the actual deliverable; the vendor behind it is an implementation detail.
3. Implement the adapter. TomsguPdfMerger implements PdfMerger, bound in a small PdfServiceProvider.
4. Optional facade — only if call-site ergonomics justify it.
5. Enforce the boundary. No library class names in controllers, jobs, or domain services. Contract tests around the adapter.

The adapter is roughly one engineering day. Everything after that is reversibility insurance.

Compatibility. Pin an exact version and constrain <next-major. Confirm PHP 8.2/8.3 and Laravel 10/11/12 support before the spike concludes. Watch for Symfony component version ranges that conflict with what Laravel already resolves.

Sequencing. Library spike → adapter plus contract tests → queue-based execution for anything above a size threshold → observability (merge duration, page count, input bytes) → canary on one low-risk internal export path. Do not put this in a synchronous request handler first.

Operational Impact

Maintenance. Single maintainer, no dependents, no commercial backing. Plan on owning fixes rather than receiving them. Containment: one adapter class, a contract test suite, a documented fallback (Stirling PDF sidecar, direct setasign/fpdi, or a managed PDF API), and an annual re-evaluation budget — not an ongoing patch budget.

Support. GitHub issues only. Verify a security policy and realistic response latency before this touches a customer-facing download path. Internal batch tooling is a far safer first home than a user-triggered request.

Scaling. Merging is CPU- and memory-bound, roughly linear in total page count with a large constant from font and object parsing. It does not scale by adding web workers cheaply. Put it on a dedicated queue with raised memory_limit and max_execution_time, cap input count and total bytes, and stream to disk via tempnam plus the storage abstraction rather than holding bytes in memory. At sustained volume, a dedicated worker pool or sidecar service beats in-process merging.

Failure modes to instrument.

• OOM on oversized or page-count-bomb inputs
• Corrupt or encrypted source PDFs throwing uncaught exceptions
• Temp file leakage across failed or retried jobs
• Request timeouts when invoked outside a queue
• Silent fidelity loss (forms, bookmarks, metadata) producing output that is "successful" and wrong
• Upstream engine drift across patch bumps

Ramp-up. Low for a competent PHP developer — the library API is small. The real trap is scope creep: the Symfony bundle's configuration surface invites config-driven thinking that does not apply here. Record a one-line ADR — "we use the library, not the bundle, behind PdfMerger" — so the next engineer does not re-litigate it.

Verdict. Adopt the library, not the bundle. Wrap it in a contract, keep a tested exit. Approve for internal and background document workflows; gate any customer-facing use on the spike results, and re-evaluate if the corpus surfaces FPDI-family limitations.