Download the PHP package mayaram/laravel-ocr without Composer

Laravel OCR & Document Intelligence

Turn any image or PDF into structured, actionable data.

A powerful, developer-friendly Laravel package that reads text from images and PDFs, understands the content, fixes scanning errors with AI, and delivers clean, structured data directly to your application.

Why this package? Most OCR tools just give you a dump of raw text. This package gives you typed DTOs, structured fields, and confidence scores. It knows the difference between an Invoice Number and a Phone Number.

📸 Demo

📑 Table of Contents

• ✨ Features
• 📐 Architecture
• 🚀 Installation
  • Compatibility Matrix
  • Quick Start
  • Install via Composer
  • Publish Configuration & Assets
  • Publish Views (Optional)
  • Install Tesseract (Default Driver)
• ⚙️ Configuration
  • OCR Driver Selection
  • Tesseract
  • Google Cloud Vision
  • AWS Textract
  • Azure Computer Vision
  • AI Cleanup (via Laravel AI SDK)
  • Queue Configuration
  • Troubleshooting Setup
  • Storage & Security
• 📖 Usage
  • Simple Text Extraction
  • Smart Parsing (Structured Data via OcrResult DTO)
  • Batch Processing
  • Working with Line Items & Tables
  • Templates
  • Workflows
  • Switching Drivers at Runtime
  • Document Metadata Extraction
  • Working with Processed Documents
• 🖥️ Artisan Commands
  • Create a Template
  • Process a Document
• 🎨 Blade Component
• 🗄️ Database Schema
• 🧩 OCR Driver Interface
  • Supported Formats by Driver
  • Building a Custom Driver
• 🤖 AI Cleanup Details
  • Basic Rules (No API Required)
  • AI-Powered Cleanup (via Laravel AI SDK)
• 🧪 Testing
• 📄 API Reference
  • LaravelOcr Facade
  • DocumentParser
  • OcrResult DTO
  • TemplateManager
• 📄 License

✨ Features

• 🧠 Multi-Driver OCR Engine: Seamlessly switch between Tesseract (offline/privacy-first), Google Cloud Vision, AWS Textract, or Azure Computer Vision drivers.
• 🤖 Optional AI Cleanup: Can use the laravel/ai SDK with the CleanupAgent to fix OCR typos (e.g., arnount → amount, nurnber → number) and normalize data formats. Supports OpenAI, Anthropic, Gemini, Ollama, DeepSeek, Groq, Mistral, and more when the AI stack is installed.
• 📦 Typed DTOs: Returns an OcrResult data transfer object with text, confidence, bounds, and metadata properties — not just raw arrays.
• 📑 Advanced Invoice Extraction: Specialized algorithms to extract line items (quantity, description, unit price, total), subtotals, tax, shipping, and totals from complex invoice layouts.
• 🔍 Auto-Classification: Automatically detects document types (Invoice, Receipt, Contract, Purchase Order, Shipping, General) using keyword scoring.
• 📋 Reusable Templates: Define document templates with regex patterns and positional extraction to target specific fields. Supports template creation, import/export, and auto-matching.
• ⚡ Workflows: Define custom processing pipelines per document type in your config (e.g., "If Invoice → Extract Tables → Verify Required Fields").
• 🎨 Blade Component: Built-in <x-laravel-ocr::document-preview> component to visualize results with bounding box overlays, inline editing, and data export.
• 🖥️ Artisan Commands: CLI tools for environment diagnostics (laravel-ocr:doctor), template creation (laravel-ocr:create-template), and document processing (laravel-ocr:process).
• 💾 Database Persistence: Optionally save processed results to the ocr_processed_documents table with template associations, confidence scores, and processing times.
• 🔒 Enterprise Security: Encrypted storage options, MIME-type validation, malware scanning, and full offline support for sensitive data.

📐 Architecture

🚀 Installation

Requires PHP 8.2+.

Core OCR features support Laravel 9 / 10 / 11 / 12 / 13. AI cleanup is optional and depends on the laravel/ai package version you install.

Compatibility Matrix

If you need the widest compatibility, keep AI cleanup on provider=basic.

Quick Start

Install the package, publish the config and migrations, verify the runtime, then process a document:

For AI cleanup, install laravel/ai separately and configure your provider credentials before using --ai-cleanup.

1. Install via Composer

Optional: Install AI Cleanup Support

laravel/ai has its own PHP/Laravel constraints. Check the version you install if you need AI cleanup on top of the core OCR package.

2. Publish Configuration & Assets

3. Publish Views (Optional)

4. Install Tesseract (Default Driver)

⚙️ Configuration

Set your preferred driver and credentials in your .env file.

OCR Driver Selection

Tesseract (Offline / Privacy-First — Default)

All processing happens on your server. No data leaves your infrastructure.

Google Cloud Vision

Requires: composer require google/cloud-vision

AWS Textract

Included: aws/aws-sdk-php is a core dependency.

Azure Computer Vision

AI Cleanup (via Laravel AI SDK)

Enable AI-powered OCR post-processing to fix scanning errors and normalize data formats. This feature is optional and requires laravel/ai to be installed in the host app. The package uses a dedicated CleanupAgent that supports multiple LLM providers.

Supported AI Providers

Set the API key for your chosen provider:

Queue Configuration

Process documents asynchronously:

🩺 Doctor Command

Use the doctor command to verify the package runtime setup before processing documents:

It checks:

• PHP version compatibility
• The configured default OCR driver
• Tesseract binary availability when Tesseract is the active driver
• Optional AI cleanup readiness

Troubleshooting Setup

Use these checks before debugging extraction quality:

Common setup issues:

• Tesseract binary not found: set TESSERACT_BINARY to the real binary path on your machine.
• AI cleanup warning: install laravel/ai, then configure LARAVEL_OCR_AI_PROVIDER and the matching API key.
• PDF conversion issues: ensure the host has the extensions and system tools required by your PDF/image pipeline.
• Laravel install conflicts: check the PHP/Laravel constraints of laravel/ai separately from the core package.

Storage & Security

📖 Usage

1. Simple Text Extraction

The LaravelOcr facade provides a simple entry point via the OCRManager.

If you only need OCR text and not structured parsing, this is the simplest integration point.

2. Smart Parsing (Structured Data via OcrResult DTO)

For powerful data extraction, use the DocumentParser. It returns a typed OcrResult DTO with text, confidence, bounds, and metadata properties.

Use DocumentParser when you want document classification, template support, field extraction, metadata, or optional cleanup in one pipeline.

3. Batch Processing

Process multiple documents at once:

4. Working with Line Items & Tables

The package includes an Advanced Invoice Extractor capable of parsing complex invoice tables into structured arrays.

5. Templates

Define reusable templates to target specific fields using regex patterns. Templates are stored in the database and support import/export.

6. Workflows

Configure processing pipelines in config/laravel-ocr.php to standardize how different document types are handled.

7. Switching Drivers at Runtime

8. Document Metadata Extraction

9. Working with Processed Documents

🖥️ Artisan Commands

Create a Template

Process a Document

Flags:

Check Environment Health

Run this first on a new machine, server, or CI environment.

🎨 Blade Component

Preview extracted documents and data directly in your UI with the built-in Alpine.js component.

Props:

Expected Document Structure:

Features:

• Click fields to highlight them on the document
• Inline editing of extracted values
• Confidence badges: 🟢 High (≥80%), 🟡 Medium (≥60%), 🔴 Low (<60%)
• Export extracted data as JSON
• Reprocess documents with one click

🗄️ Database Schema

The package creates three tables:

ocr_templates

ocr_template_fields

ocr_processed_documents

🧩 OCR Driver Interface

All drivers implement the Mayaram\LaravelOcr\Contracts\OCRDriver interface:

Supported Formats by Driver

Building a Custom Driver

🤖 AI Cleanup Details

The AICleanupService provides two modes:

Basic Rules (No API Required)

Set provider to basic to use built-in typo correction and field normalization without any AI provider:

Built-in corrections:

• Common OCR typos: invOice → invoice, arnount → amount, nurnber → number, custorner → customer, payrnent → payment
• OCR pattern fixes: rn → m, O before numbers → 0, l before numbers → 1
• Field normalization by type: numeric, date (→ Y-m-d), currency, email, phone

AI-Powered Cleanup (via Laravel AI SDK)

Uses the CleanupAgent with your configured LLM provider for intelligent correction:

The agent is instructed to:

1. Fix typos and OCR errors contextually
2. Standardize formats (dates to YYYY-MM-DD, currency to decimal)
3. Preserve values it can't confidently fix
4. Return valid JSON matching the input structure

Custom Prompt

You can pass additional instructions to the AI cleanup agent to customize its behavior:

Or set a default custom prompt in config/laravel-ocr.php:

The custom prompt is appended as "Additional Instructions" to the default cleanup prompt, so the base OCR correction behavior is always preserved.

🧪 Testing

The package uses Pest for testing with three test suites:

Tests use SQLite in-memory database automatically via phpunit.xml configuration.

Current coverage includes:

• parsing and template application
• console commands
• AI cleanup flow with mocked AI responses
• end-to-end package flow through integration tests

📄 API Reference

LaravelOcr Facade (via OCRManager)

DocumentParser (via app('laravel-ocr.parser'))

OcrResult DTO

TemplateManager (via app('laravel-ocr.templates'))

📄 License

The MIT License (MIT). Please see License File for more information.