Pdfparser Laravel Package

Technical Evaluation

Architecture fit

• smalot/pdfparser is a pure-PHP, dependency-free PDF reader that surfaces a small, stable façade: Parser::parseFile() / parseContent() → Document → getText(), getPages(), getDetails(). For a TPM this is the ideal shape: a single seam (DocumentTextExtractor interface) that can sit behind an adapter and be swapped for pdftotext, Tika, or a cloud OCR API without touching call sites.
• Best fit is text-layer extraction from born-digital PDFs inside an existing PHP/Laravel ingestion pipeline — upload → extract → normalize → index/search/summarize. It removes a system dependency (no Poppler binary, no Java/Tika, no sidecar service), which materially simplifies container images, shared hosting, and CI.
• Poor fit for: scanned documents (no OCR), encrypted/secured PDFs (explicitly unsupported; v2.8 only added a workaround to ignore encryption), form-field/AcroForm extraction, and layout-sensitive reconstruction (tables, multi-column ordering, positional semantics). getText() is a text stream, not a document model — do not scope "structured parsing" onto it.

Integration feasibility

• Trivial to adopt: composer require smalot/pdfparser, PHP 7.1+ (works on 8.x per the 2.7/2.8 release notes), no config, no services, no migrations. A working prototype is a few lines.
• Configuration levers are minimal but the important one exists: Config::setRetainImageContent(false) (added v1.1.0) drops image payloads from memory — this is the single highest-value performance setting for image-heavy corpora and should be the default in our wrapper.
• The v2.0.0 typed-signature break and the v2.8.0 PDFObject.php rewrite (~20 issues) confirm the internal API is churny; internal classes (Font, PDFObject, Header) are not a safe extension surface. Consume only the public façade.

Technical risk

• Capability gap, not a bug: no OCR. Any meaningful corpus will contain scans; extraction will silently return empty or near-empty strings rather than failing. This is the top product risk because it produces plausible-looking bad data downstream.
• Resource behavior: pure-PHP parsing is CPU- and memory-bound with no streaming and no user-facing timeout. Large or adversarial PDFs can exhaust memory_limit or max_execution_time, and gzuncompress() on corrupt streams has historically produced fatal errors. Mitigation is architectural (queue + hard worker timeout), not configurable.
• Parsing fragility: a long release history of encoding/font/xref/hex-octal edge-case fixes (v2.9.0, v2.8.0, v1.0.1, v1.0.2) is a signal that malformed or non-standard producer output still bites. Expect a non-trivial long tail of "works for 95% of files" failures that require per-file investigation.
• Maintenance status is the headline risk: the README states limited maintenance — compatible with supported PHP versions, but no active feature development and no guarantee PRs are reviewed or merged. We must own the fork. Budget: pin exact version, maintain a patch branch, and accept that a novel CVE or PHP 8.x/9 break may require in-house fixes.
• Licensing: LGPL-3.0 is generally workable for proprietary applications when used as an unmodified Composer dependency, but modification of the library itself triggers source-disclosure obligations. Legal should confirm before we fork — and forking is precisely what the maintenance status implies we may need.
• Data-quality caveat: the supplied metadata reports Dependents: 0, which contradicts the package's real-world ubiquity (it underpins several popular Laravel PDF-to-text wrappers). Treat dependency/stars telemetry as unreliable inputs; verify against Packagist and our own composer audit.

Key questions

1. What percentage of the target corpus is born-digital vs. scanned, and what is our defined behavior when extraction returns empty text (hard fail, flag, route to OCR)?
2. Is structured output (tables, fields, page-level coordinates) in scope, or is plain concatenated text sufficient? If structured, this package is the wrong tier.
3. What are the max file size / page count / latency SLOs, and do they fit a synchronous web request or does this require a queued worker?
4. Do we accept a forked-vendor maintenance obligation, and is there an owner with PHP internals willingness to patch it?
5. Has legal signed off on LGPL-3.0 given our distribution model (SaaS vs. on-prem binary)?
6. What is the acceptance threshold — precision/recall on a labeled sample — that justifies this over pdftotext, which is faster and more battle-tested but adds a system dependency?

Integration Approach

Stack fit

• Native fit for Laravel: Composer package, PSR-4, no service container bindings required. Wrap it in a PdfTextExtractor contract bound in a service provider so the implementation is swappable and testable (fakes for unit tests, no real PDF fixtures needed in the fast suite).
• Avoid running parsing in the HTTP request path. Target architecture: UploadController → store original to disk/S3 → dispatch ExtractPdfText job → queued worker parses → persist document_text (raw + normalized) + extraction metadata → downstream index/summarize.
• Isolate parsing in a dedicated queue (pdf-extraction) with its own worker pool, its own memory_limit, and --timeout set below the job's retry_after to prevent duplicate execution on timeout.
• Persist extraction telemetry alongside the text: parser version, page count, character count, per-page empty flags, duration, peak memory, and a needs_ocr boolean. This is what makes the swap decision reversible later.

Migration path

• Phase 0 (spike, ~2–3 days): stand up the adapter, run it against a stratified sample (n≈200–500) of real files. Record char/page yield, empty-page rate, encoding artifacts, and failures. This single artifact determines whether we proceed, proceed-with-OCR, or switch to pdftotext/Tika.
• Phase 1: ship behind feature flag on a single low-risk document class (e.g., vendor invoices for internal search only), with manual spot-check of output before any user-visible surface.
• Phase 2: add the OCR fallback path for needs_ocr documents; backfill previously flagged documents via a replayable job (keep originals, never discard them — extraction must always be re-runnable after a parser upgrade).
• Phase 3: only after yield is stable, expose to user-facing features (search, summarization, Q&A).

Compatibility

• Pin the exact minor ("smalot/pdfparser": "2.9.*") and commit the lockfile; do not float. The v2.x internal churn plus limited upstream responsiveness makes silent minor drift an unnecessary gamble.
• Verify PHP version support against our runtime matrix before pinning; the README states 7.1+ but the practical baseline is 8.1+ given our framework version. Add a CI matrix job that runs the adapter against a fixture corpus on our actual PHP target.
• If we fork for LGPL reasons or to carry patches, keep the fork as a VCS repository dependency with a clean upstream-merge branch and document the diff.

Sequencing

1. Contract + adapter + config defaults (setRetainImageContent(false)).
2. Benchmark harness and corpus labeling (this is the real work; the code is trivial).
3. Queue/job/worker topology with timeouts and memory ceilings.
4. Detection + OCR fallback.
5. Persistence model with versioning and replay.
6. Swap-in evaluation (pdftotext behind the same contract) — keep the interface honest by proving a second implementation fits.

Operational Impact

Maintenance

• Ongoing cost is low in code volume and moderate in ownership: expect to carry the fork. Allocate a named maintainer and a quarterly review of upstream releases; assume we merge security patches ourselves.
• Two recurring chores: (a) re-benchmark the corpus after every parser upgrade — extraction output is not covered by semantic versioning guarantees; (b) keep the fixture corpus in-repo as a regression suite, since upstream's tests won't cover our file shapes.
• LGPL hygiene: track whether we modify the library; if we do, publish the modified source and keep the license notice intact.

Support

• Failure triage is inherently per-document and labor-intensive — "this one PDF extracts garbage" tickets have no generic fix. Budget support capacity for file-level investigation and a documented "we cannot extract this" outcome.
• Expect user confusion between "document has no text" and "our system failed." Empty extraction must be surfaced explicitly in the UI with a distinct state, not rendered as an empty document.

Scaling

• Scales horizontally with queue workers, but each worker is a fork-bound PHP process; memory is the binding constraint, not CPU throughput per se. Right-size worker concurrency to container memory and cap document size (reject >N MB or >M pages at upload with a clear error) rather than trying to parse everything.
• No caching layer inside the library of consequence; the durable win is caching extraction results keyed by file hash + parser version. Reprocessing without that key will silently produce mixed-version corpora.
• Text output is typically small relative to input; storage growth is dominated by retaining originals, which we should do anyway for replay.

Failure modes

• Silent empty extraction on scanned/encrypted PDFs — highest-impact, because it corrupts downstream index quality without an alarm. Mitigate with char-per-page thresholds and a needs_ocr flag.
• Memory exhaustion on large/image-heavy PDFs — mitigate with setRetainImageContent(false), worker memory_limit, and pre-flight size gating.
• Worker timeout / silent kill — mitigate with job timeout < retry_after, idempotent jobs, and a failed_at-style terminal state so a document isn't retried forever.
• Unhandled exception or fatal on malformed streams (e.g., gzuncompress on corrupt data) — wrap every parse in try/catch with a broad catch; treat the library as untrusted input processing.
• Text-order/encoding corruption — CJK, custom font encodings, and multi-column layouts can yield mojibake or scrambled reading order. Detect via encoding heuristics and flag rather than index blindly.
• Untrusted input surface — arbitrary PDFs from users; ensure the worker runs with least privilege, no network egress, and isolated temp storage.

Ramp-up

• Low engineering ramp-up: the API is one class, and a competent Laravel developer is productive in an hour. The README's "Maintenance status" notice and the absence of a formal API-stability statement should be read aloud to the team so nobody builds on internals.
• The real ramp-up is on the quality side: someone must own corpus curation, quality metrics, and the OCR boundary. Budget that as a part-time role, not a sprint task.
• Overall verdict: adopt with conditions — approved as a text-layer extractor behind an adapter, in a queued worker, pinned to an exact version, with an OCR fallback and an explicit empty-extraction state. Not approved as the sole document-understanding strategy.