Laravel Anydoc Laravel Package

Technical Evaluation

Scope of this release. v1.4.0 adds an opt-in hosted OCR path for scanned PDFs, exposed as markdown(ocr: true). The minor version bump and the explicit opt-in flag indicate this is additive rather than breaking: existing callers of markdown() retain current behaviour, and no deprecations are signalled. Assessment below assumes the package is a document-to-Markdown extraction library used inside Laravel applications, with markdown() as the primary extraction entry point.

Architecture fit. The change preserves the package's existing shape — a single fluent call site plus configuration — so it slots into the same layer of the stack as current extraction: application services or, more realistically, queued jobs. The flag-in, string-out contract means callers do not need to branch on document type themselves if the package auto-detects an absent text layer. That is the single most important architectural unknown; if detection is the caller's responsibility, the ergonomic benefit largely evaporates and every integration grows a pre-flight check.

Integration feasibility. Low effort on the happy path: publish/merge config, add credentials to the environment, flip the flag. The real cost sits outside the code — this release introduces a third-party data processor into a path that previously may have been entirely local. Documents now leave the application boundary, which pulls in vendor onboarding, a data processing agreement, and a privacy review before production enablement in any regulated or customer-data context.

Technical risk. Three areas concentrate risk:

• Data egress and residency. Scanned PDFs skew toward contracts, invoices, identity documents, and medical records — exactly the content class most likely to be governed. Opt-in reduces blast radius but does not remove the obligation to know what is being sent.
• Silent degradation. OCR failures that surface as empty or truncated Markdown are far more damaging than a thrown exception, because downstream indexing and retrieval will happily consume the empty result. Error semantics must be explicit and documented.
• Cost and latency variance. Per-page hosted pricing plus multi-second per-page processing converts a previously CPU-bound, predictable operation into a metered, variable-latency one.

Key questions.

1. Which vendor provides the hosted OCR, and what are its retention, residency, and subprocessor terms?
2. Is OCR triggered automatically when no text layer is detected, or must the caller determine that first?
3. What is the pricing model per page/document, and is there a hard quota we can configure?
4. What are the file-size, page-count, and timeout limits, and how are they surfaced as exceptions?
5. Does it function in queue workers and CLI contexts with no HTTP request lifecycle, and does it respect Laravel's configured HTTP client timeouts and retries?
6. Is there a self-hosted or local OCR fallback (e.g. Tesseract) for documents that cannot leave our infrastructure?
7. How is output quality characterised — is there a confidence signal, and what accuracy should we expect on poor-quality scans?

Integration Approach

Stack fit. Standard Laravel package conventions apply: a service provider, mergeable config, environment-driven credentials, and compatibility with config:cache. Confirm the supported Laravel and PHP ranges on the release before pinning; the HTTP dependency should route through Laravel's HTTP client so that existing global timeout, retry, and proxy settings apply rather than being bypassed by a bundled SDK.

Migration path. Effectively zero-migration. Because the feature is opt-in and default-off, upgrading the constraint to ^1.4 is safe for existing behaviour. The upgrade and the feature enablement should be treated as two separate changes with two separate approvals — do not let a routine dependency bump silently introduce a new data processor.

Compatibility. Verify: PHP and Laravel version support; whether new extensions or binaries are required; whether the config file needs republishing (a merged-config release means config:cache must be cleared on deploy); and whether any new environment variables are required at boot or fail lazily at call time. Lazy failure is preferable for an opt-in feature but must be documented.

Sequencing.

1. Pin ^1.4, deploy with the flag off, confirm no behavioural change.
2. Complete vendor/security/privacy review; obtain the DPA; define the data classification policy for documents permitted to use OCR.
3. Provision credentials per environment; store in the secret manager, not in .env files in the repository.
4. Enable in staging against a representative corpus of real scanned documents; measure extraction accuracy, p95 latency, and cost per 1,000 documents.
5. Roll out behind a per-tenant or per-document-type feature flag, starting with the lowest-sensitivity content class.
6. Instrument and review before broadening.

Operational Impact

Maintenance. Adds a credential to the rotation roster and a vendor relationship to the dependency register — the latter being the heavier long-term cost. Hosted API versions drift; a vendor-side deprecation becomes our upgrade work. Watch for pinning: an unpinned HTTP call to a third-party endpoint is a latent production incident.

Support. The failure taxonomy expands. Support staff will now need to distinguish "document genuinely has no text" from "OCR was not enabled," "OCR quota exhausted," and "vendor outage" — four states that may present identically to an end user as empty output. Investment in distinguishable error types and log context pays for itself quickly here.

Scaling. Cost scales linearly and directly with document volume, which is a meaningfully different scaling curve from CPU-bound extraction and should be modelled before broad enablement. Throughput is bounded by vendor rate limits and per-page processing time, so OCR calls belong in queued jobs with dedicated queue workers, concurrency caps, and backoff — never in a synchronous request path. Bulk backfills of an existing scanned-document corpus should be treated as a separate, budgeted project rather than a side effect of enabling the flag.

Failure modes. Vendor 5xx and 429 responses under load; request timeouts on large or image-heavy documents; quota exhaustion mid-batch; malformed or password-protected PDFs; and — most dangerous — successful HTTP responses containing low-quality or empty text that propagate silently into downstream search and retrieval. Mitigations: explicit timeout and retry policy with jitter, bounded concurrency, a documented empty-output sentinel, monitoring on OCR invocation rate and failure rate, and an alert on cost-per-day thresholds.

Ramp-up. Engineering ramp-up is genuinely small — a flag and configuration. The critical path is organisational: privacy, legal, and security review of sending customer documents to a third party, plus finance sign-off on metered spend. Sequence those early, in parallel with the staging evaluation, or they will gate the release.