Apache Tika Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package, so "getting started" in a Laravel app really means deciding whether the bundle wrapper adds anything over its only real dependency, vaites/php-apache-tika. In practice it doesn't: the bundle is mostly a service definition plus a host/port config block. The v1.1.0 release (Symfony >= 4.0 compatibility) doesn't change that calculus one bit — there is still no Laravel service provider, facade, or config publishing. For a Laravel codebase the pragmatic first step is:

composer require vaites/php-apache-tika

and skip the bundle unless you're embedding this in a Symfony component. If you do install the bundle, run composer require jolicode/apache-tika-bundle and expect Symfony DI components to come along for the ride even though Laravel won't use them.

You still need a running Tika server — the PHP library is only a client:

docker run -d -p 9998:9998 --name tika apache/tika:latest

First use case worth proving out: extract plain text from a PDF upload.

$client = new \Vaites\ApacheTika\Client('http://localhost', 9998);
$text = $client->getText('/path/to/upload.pdf');

Where to look first inside the bundle repo: DependencyInjection/Configuration.php and Resources/config/services.xml. That's the whole contract — a TikaClient service wired from the host and port parameters. Once you've seen it, you'll understand there's nothing to port; re-implement that wiring in a Laravel service provider.

Implementation Patterns

Wrap the client in a service provider + facade. Bind a singleton so connection reuse and config are centralised:

// AppServiceProvider
$this->app->singleton(\Vaites\ApacheTika\Client::class, fn () => new \Vaites\ApacheTika\Client(
    config('services.tika.host', 'http://localhost'),
    config('services.tika.port', 9998),
));

Queue extraction, never do it inline on upload. Tika text extraction on a 50-page PDF or a scanned image (OCR) routinely takes seconds to minutes. Dispatch a ExtractDocumentText job, store the result on the model, and use broadcasting/polling to surface progress.

ExtractDocumentText::dispatch($document)->onQueue('documents');

Separate the three Tika operations. getText() for plain text, getMetadata() for EXIF/author/created-date, detect() for MIME type. They're independent calls; don't fetch metadata if you only need searchable text.

Cache aggressively by content hash. Tika is deterministic per file and version. Hash the file with sha1_file() and store extracted text keyed on that — re-uploading the same PDF costs nothing.

Use the typed clients for special cases. The library exposes App\Client, PdfClient, OfficeClient, ImageClient, HtmlClient, TextClient, MlClient. For OCR specifically, ImageClient::getText() is what triggers the Tesseract path.

Multi-tenant routing. If different tenants have different Tika servers (compliance, on-prem), bind a resolver rather than a singleton — $this->app->bind(Client::class, fn ($app) => new Client(tenant()->tikaHost())).

Gotchas and Tips

No Laravel auto-discovery. Symfony bundles are invisible to Laravel. Nothing will register itself; there's no facade, no config publishing. Any "installation steps" from the bundle README assume AppKernel/bundles.php and will not work.

v1.1.0 is a one-line compatibility bump, not a revival. The only change is a relaxed Symfony constraint (>= 4.0, thanks to @Baachi). It adds no features, no new client API, no Laravel support, and no docs. The package still sits at ~10 stars with no dependents. Read the vaites/php-apache-tika README instead — it's where all the actual API surface lives.

PHP version constraints (partially relaxed). v1.1.0 loosens the Symfony constraint, so Composer resolution on PHP 8.2+ is less likely to explode than it was on the 2019 tag. That doesn't make it useful — you'll still pull down Symfony DI machinery Laravel never instantiates. Another reason to use the underlying client directly.

Tika server is a real operational dependency. Timeouts, OOM on huge files, and 415/422 responses are your common failures. Set explicit HTTP timeouts on the client, cap upload size before it reaches Tika, and wrap calls in try/catch that maps to a domain exception — don't let a Tika 500 bubble up as a raw Guzzle error.

Encoding. Tika returns UTF-8, but PDFs with broken embedded fonts can produce mojibake. Run mb_check_encoding() on the output and log the file hash when it fails; there's no config knob that fixes bad source fonts.

Large file handling. The client supports streaming PUT for Client::put()-style operations, but getText() still buffers the response. For anything over ~50MB, extract to a temp file, not to a model field.

Extension points are Symfony-shaped. The bundle's only extension points are services.xml overrides and constructor args — neither of which Laravel consumes, and v1.1.0 adds none. Your real extension points are the service provider, a facade, and a TikaExtractor interface you own so you can swap to a different backend later.

Debugging checklist when extraction returns empty: (1) is Tika reachable — curl http://localhost:9998/tika; (2) is the file readable by the PHP process; (3) does detect() return the MIME type you expect; (4) for scanned PDFs, is OCR enabled on the server image (apache/tika full image, not the slim one).