Laravel Anydoc Laravel Package

Getting Started

Install the package via Composer and publish its configuration:

composer require vendor/package
php artisan vendor:publish --tag="package-config"

Since v1.4.0 adds hosted OCR, you must configure credentials for the external OCR service. Add the required API key (and any region/endpoint) to your .env file as instructed by the package’s config file. The package typically exposes a markdown() method through a facade or an injectable service.

Your first use case: convert a digital (text-based) PDF to Markdown for search indexing or content extraction.

use Vendor\Package\Facades\Pdf;

$markdown = Pdf::markdown(storage_path('app/contracts/terms.pdf'));

For scanned PDFs, opt in to OCR:

$markdown = Pdf::markdown(
    storage_path('app/scans/invoice.pdf'),
    ocr: true
);

Check the package README for the exact method signature and facade alias, as naming may vary.

Implementation Patterns

Conditional OCR based on content detection. Most workflows should first attempt a normal conversion. If the resulting Markdown is empty or contains only whitespace, retry with ocr: true. This avoids unnecessary cost and latency for digital PDFs.

$markdown = Pdf::markdown($path);

if (trim($markdown) === '') {
    $markdown = Pdf::markdown($path, ocr: true);
}

Queue long-running conversions. Hosted OCR can take several seconds per page. Dispatch conversion jobs to a queue and store the result in the database or filesystem.

ProcessPdf::dispatch($pdfPath);

Integrate with Laravel storage. Use Storage::path() for local disks or Storage::url() / temporary URLs for remote disks. Ensure the hosted OCR service can access any URL you pass.

Cache OCR results. Markdown output from OCR is deterministic for a given file. Store it (e.g., in a markdown column or a cache key) to avoid repeated charges and slow calls.

Batch processing with chunking. When converting many PDFs, chunk the work and use Bus::batch() to monitor progress. Avoid running OCR on hundreds of pages in a single request.

Configuration over hard-coding. Set default OCR behavior, HTTP timeout, and retry counts in config/package.php. Use environment variables for API keys and endpoints.

Gotchas and Tips

• OCR is opt-in by design. Do not enable ocr: true globally. Default conversion is faster and cheaper; only scanned PDFs need OCR.
• Hosted OCR introduces a network dependency. Handle timeouts, rate limits, and service outages. Wrap calls in try/catch and consider exponential backoff retries.
• Cost and quota. Hosted OCR is often billed per page. Monitor usage, split large PDFs if the provider enforces page limits per request, and log page counts.
• PHP 8+ required for named arguments. The markdown(ocr: true) syntax uses named arguments, so the package requires PHP 8.0 or later. If you support older PHP versions, use an options array instead (if the package provides one).
• File accessibility. The hosted service must be able to reach the PDF. For private local files, the package may upload them automatically; for remote files, ensure the URL is publicly accessible or use a signed temporary URL.
• OCR accuracy varies. Scanned documents with poor resolution, handwriting, or complex layouts may produce imperfect Markdown. Post-process or flag low-confidence results for manual review.
• Debugging. Log the raw API response (redacting sensitive data) and check the package’s log channel. Common failures are invalid API keys, expired tokens, and unsupported PDF encryption.
• Extension points. Look for config options to swap the OCR provider, customize the HTTP client, or listen to events around conversion. These are useful for testing and for adding observability.
• Version awareness. This assessment reflects v1.4.0. Pin the version in composer.json if you depend on the new OCR behavior, and review the changelog for future breaking changes.