PHPackages                             abduns/laravel-ocr - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF & Document Generation](/categories/documents)
4. /
5. abduns/laravel-ocr

ActiveLibrary[PDF & Document Generation](/categories/documents)

abduns/laravel-ocr
==================

Laravel-first wrapper around Tesseract 5 OCR.

v1.0.0(1mo ago)046↓86.7%MITPHPPHP ^8.2CI passing

Since May 26Pushed 1mo agoCompare

[ Source](https://github.com/abduns/laravel-ocr)[ Packagist](https://packagist.org/packages/abduns/laravel-ocr)[ RSS](/packages/abduns-laravel-ocr/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (10)Versions (2)Used By (0)

laravel-ocr
===========

[](#laravel-ocr)

Laravel-first wrapper around Tesseract 5 OCR for images and PDFs.

[![Tests](https://github.com/abduns/laravel-ocr/actions/workflows/tests.yml/badge.svg)](https://github.com/abduns/laravel-ocr/actions)[![Version](https://camo.githubusercontent.com/0cc7ea4b2d7da9c06eae993f1cbd788987247825121e9a927046afd390ab9ea0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616264756e732f6c61726176656c2d6f63722e737667)](https://packagist.org/packages/abduns/laravel-ocr)[![Downloads](https://camo.githubusercontent.com/a769f7563ccb9e1587b4d965b110029dd8e3731d45bb42fab5f129bda3c5f2aa/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616264756e732f6c61726176656c2d6f63722e737667)](https://packagist.org/packages/abduns/laravel-ocr)[![License](https://camo.githubusercontent.com/3ea4bfaa6097e4faaf7e7cfe17a2e8440a7a7118f067529e902e5a3aab2c2427/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616264756e732f6c61726176656c2d6f63722e737667)](LICENSE)

---

Features
--------

[](#features)

- Modern PHP support
- Fluent Laravel API for image and PDF OCR
- Queueable OCR jobs
- Lifecycle events for started, completed, and failed runs
- Filesystem disk support, including remote source disks
- Publishable config file
- Artisan command for direct scans
- Setup check command for Tesseract, language data, temp storage, and PDF tooling
- Lazy validation so apps can boot without a local OCR binary
- AI agent instructions included for common coding assistants
- Laravel Boost guidelines and skill included for AI-assisted Laravel development

---

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 10, 11, 12, or 13
- Tesseract 5.0+
- For PDF input: Imagick PHP extension or Ghostscript

Install system dependencies first:

```
# Ubuntu/Debian
sudo apt-get install tesseract-ocr tesseract-ocr-eng ghostscript

# macOS with Homebrew
brew install tesseract ghostscript
```

---

Installation
------------

[](#installation)

```
composer require abduns/laravel-ocr
```

Publish the config file when you need to customize paths, defaults, queues, or PDF rasterization:

```
php artisan vendor:publish --tag=ocr-config
```

The package is auto-discovered by Laravel. The facade alias is `Ocr`.

The Composer package and GitHub repository are `abduns/laravel-ocr`. The PHP namespace intentionally remains `Dunn\LaravelOcr`.

---

Quick Start
-----------

[](#quick-start)

```
use Dunn\LaravelOcr\Facades\Ocr;

$text = Ocr::image(storage_path('app/invoices/invoice.png'))
    ->language('eng')
    ->run();
```

PDF output is keyed by page number:

```
$pages = Ocr::pdf(storage_path('app/contracts/contract.pdf'))
    ->language('eng')
    ->runAll();

// [1 => '...', 2 => '...', 3 => '...']
```

---

Why This Package?
-----------------

[](#why-this-package)

- OCR packages often hide the local binary details that matter in production
- PDF handling usually needs predictable temporary files and cleanup
- Queue and event integration should feel native in Laravel applications

This package focuses on a small, headless Laravel surface around the local Tesseract CLI. It ships no routes, views, frontend assets, cloud OCR SDKs, or language-pack downloaders.

---

Usage
-----

[](#usage)

### Image OCR

[](#image-ocr)

```
use Dunn\LaravelOcr\Facades\Ocr;

$text = Ocr::image(storage_path('app/invoices/invoice.png'))
    ->language('eng')
    ->psm(6)
    ->timeout(30)
    ->run();
```

Multiple languages are supported and passed to Tesseract in order:

```
$text = Ocr::image($path)
    ->languages(['eng', 'ind'])
    ->run();
```

### PDF OCR

[](#pdf-ocr)

```
$pages = Ocr::pdf(storage_path('app/contracts/contract.pdf'))
    ->language('eng')
    ->dpi(300)
    ->pages([1, 2, 3])
    ->runAll();
```

If `pages()` is omitted, every page is OCRed in ascending order. Temporary rasterized page images are deleted after success or failure.

### Storage Disks

[](#storage-disks)

Use `disk()` when the source lives on a configured Laravel filesystem disk:

```
$text = Ocr::image('uploads/receipt.png')
    ->disk('s3')
    ->language('eng')
    ->run();
```

Non-local source disks are streamed to the configured local temp disk before OCR.

### Queues

[](#queues)

Dispatch a queued OCR job with `onQueue()`:

```
Ocr::pdf('documents/report.pdf')
    ->disk('s3')
    ->language('eng')
    ->onQueue('ocr')
    ->dispatch();
```

The queue connection comes from `ocr.queue.connection`. The queue name comes from the explicit `onQueue('name')` value, then `ocr.queue.name`, then Laravel's default queue.

### Events

[](#events)

Each OCR invocation dispatches lifecycle events:

- `Dunn\LaravelOcr\Events\OcrStarted`
- `Dunn\LaravelOcr\Events\OcrCompleted`
- `Dunn\LaravelOcr\Events\OcrFailed`

PDF OCR emits one event sequence per page.

```
use Dunn\LaravelOcr\Events\OcrCompleted;
use Illuminate\Support\Facades\Event;

Event::listen(OcrCompleted::class, function (OcrCompleted $event) {
    logger()->info('OCR completed', [
        'job_id' => $event->jobId,
        'length' => strlen($event->text),
    ]);
});
```

### Artisan

[](#artisan)

```
php artisan ocr:check
php artisan ocr:check --lang=eng,ind
php artisan ocr:check --skip-pdf
php artisan ocr:scan storage/app/invoice.png --lang=eng --psm=6
php artisan ocr:scan storage/app/report.pdf --lang=eng --dpi=300
```

Use `ocr:check` before wiring OCR into production or queue workers. It verifies the configured Tesseract binary, Tesseract 5 version, requested language data, local temp disk, and PDF backend. Use `--skip-pdf` when the app only needs image OCR.

For PDFs, page output is separated by a form-feed character.

---

Advanced Usage
--------------

[](#advanced-usage)

### Configuration

[](#configuration)

Published config lives at `config/ocr.php`.

```
return [
    'binary' => env('TESSERACT_BIN', '/usr/bin/tesseract'),
    'default_language' => env('OCR_LANG', 'eng'),
    'default_psm' => 3,
    'default_oem' => 3,
    'tessdata_path' => env('TESSDATA_PREFIX'),
    'temp_disk' => 'local',
    'temp_path' => 'ocr/tmp',
    'timeout' => 120,
    'pdf' => [
        'driver' => env('OCR_PDF_DRIVER', 'auto'),
        'default_dpi' => 300,
    ],
    'queue' => [
        'connection' => env('OCR_QUEUE_CONNECTION'),
        'name' => env('OCR_QUEUE_NAME', 'ocr'),
    ],
];
```

`temp_disk` must be a local filesystem disk because Tesseract and the PDF rasterizers need real local file paths.

### Tesseract Options

[](#tesseract-options)

MethodDescription`language('eng')`Use one Tesseract language`languages(['eng', 'ind'])`Use multiple Tesseract languages in order`psm(6)`Set page segmentation mode, `0..13``oem(3)`Set OCR engine mode, `0..3``timeout(30)`Override process timeout in seconds`tessdataPath('/path/to/tessdata')`Override traineddata lookup path`dpi(300)`Set PDF rasterization DPI`pages([1, 2, 3])`Limit PDF OCR to selected pages### Error Handling

[](#error-handling)

The package exposes typed runtime exceptions:

- `Dunn\LaravelOcr\Exceptions\TesseractNotFoundException`
- `Dunn\LaravelOcr\Exceptions\UnsupportedLanguageException`
- `Dunn\LaravelOcr\Exceptions\OcrProcessingException`

Configuration validation is lazy. The service provider can boot even if Tesseract is missing; failures surface when OCR is executed.

### AI Agent Instructions

[](#ai-agent-instructions)

This package includes AI coding-agent instructions for common tools:

- `resources/boost/guidelines/core.blade.php` for Laravel Boost package guidelines
- `resources/boost/skills/laravel-ocr-development/SKILL.md` for the Laravel Boost package skill
- `AGENTS.md` for generic repository-wide agent guidance
- `.github/copilot-instructions.md` for GitHub Copilot
- `.cursor/rules/laravel-ocr.mdc` for Cursor
- `.windsurfrules` for Windsurf
- `GEMINI.md` for Gemini
- `CLAUDE.md` and `.claude/skills/laravel-ocr` for Claude Code

Use these when an AI agent needs to add OCR to a Laravel app, configure local Tesseract, wire image or PDF OCR, dispatch queued OCR jobs, listen for lifecycle events, or debug system dependency failures.

In apps using Laravel Boost, the package guidelines and `laravel-ocr-development` skill can be installed by running:

```
php artisan boost:install
```

If the package was added after Boost resources were already installed, run:

```
php artisan boost:update --discover
```

---

Standards / Specifications
--------------------------

[](#standards--specifications)

References:

-
-

---

Supported Features
------------------

[](#supported-features)

FeatureSupportImage OCRYesPDF OCRYesMultiple LanguagesYesLaravel Filesystem DisksYesQueued JobsYesLifecycle EventsYesArtisan ScansYesSetup DiagnosticsYes---

Compatibility
-------------

[](#compatibility)

PlatformSupportedPHP 8.2+YesLaravel 10.0+YesTesseract 5.0+YesSymfony Process 6.0+Yes---

Design Goals
------------

[](#design-goals)

- Laravel-native API
- Predictable local-process execution
- Explicit configuration
- Safe temporary file handling
- Minimal runtime dependencies
- Strong validation
- Testable internals

---

Architecture
------------

[](#architecture)

- Facade-backed `OcrManager`
- Immutable builder state for image and PDF workflows
- Symfony Process execution through the local Tesseract binary
- PDF rasterization through Ghostscript or Imagick
- Laravel queue payload rebuild for deferred OCR jobs
- Events emitted around each OCR operation

---

Performance
-----------

[](#performance)

OperationConstraintImage OCRBound by Tesseract and source image sizePDF OCRBound by page count, rasterization DPI, and TesseractRemote disk sourceStreamed once to a local temp fileCleanupTemporary files removed after success or failure---

Testing
-------

[](#testing)

```
vendor/bin/phpunit
vendor/bin/phpstan analyse --configuration=phpstan.neon.dist
vendor/bin/pint --test
```

Real Tesseract integration tests are opt-in:

```
OCR_INTEGRATION=1 TESSERACT_BIN=/usr/bin/tesseract vendor/bin/phpunit --testsuite Integration
```

PDF integration also needs Ghostscript or a working Imagick PDF policy.

---

Roadmap
-------

[](#roadmap)

- Add optional cloud OCR driver integrations while keeping local Tesseract as the default engine
- Add more CLI output format options
- Add per-page PDF progress callbacks
- Add richer queue result handling examples

---

Contributing
------------

[](#contributing)

Contributions, issues, and discussions are welcome.

---

Security
--------

[](#security)

If you discover security issues, please report them responsibly.

---

License
-------

[](#license)

The MIT License (MIT). Please see [LICENSE](LICENSE) for more information.

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance88

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

59d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/28977075?v=4)[Abdun](/maintainers/abduns)[@abduns](https://github.com/abduns)

---

Top Contributors

[![abduns](https://avatars.githubusercontent.com/u/28977075?v=4)](https://github.com/abduns "abduns (5 commits)")

---

Tags

laravelpdfimageOCRTesseract

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/abduns-laravel-ocr/health.svg)

```
[![Health](https://phpackages.com/badges/abduns-laravel-ocr/health.svg)](https://phpackages.com/packages/abduns-laravel-ocr)
```

###  Alternatives

[laravel/horizon

Dashboard and code-driven configuration for Laravel queues.

4.2k95.4M321](/packages/laravel-horizon)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M246](/packages/laravel-ai)[illuminate/queue

The Illuminate Queue package.

20432.6M1.7k](/packages/illuminate-queue)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M133](/packages/roots-acorn)[illuminate/notifications

The Illuminate Notifications package.

483.1M1.2k](/packages/illuminate-notifications)[tightenco/jigsaw

Simple static sites with Laravel's Blade.

2.3k453.6k30](/packages/tightenco-jigsaw)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)