sabioweb/ocr-space-package

A pure PHP OCR package using OCR.Space API - Developed by Sabioweb Team

dev-main 2025-12-02 10:46 UTC

Requires

• php: ^8.3
• guzzlehttp/guzzle: ^7.8

Requires (Dev)

• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^11.0

MIT

• Ramezanzadeh

• OCR
• pdf-to-text
• text-recognition
• image-to-text
• ocr-space
• sabioweb

README

A pure PHP OCR package for extracting text from images and PDF files using OCR.Space API.

Developer: Sabioweb
Author: Ramezanzadeh

🇮🇷 Read in Persian / خواندن به فارسی

Installation

Install via Composer

composer require sabioweb/ocr-space-package

Install via Git

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/sabioweb/OcrSpace-Package.git"
        }
    ],
    "require": {
        "sabioweb/ocr-space-package": "dev-main"
    }
}

Features

• ✅ Extract text from images (JPG, PNG)
• ✅ Extract text from PDF files
• ✅ Extract text from image and PDF URLs
• ✅ Support for multiple languages (Persian, English, Arabic, etc.)
• ✅ Advanced OCR settings
• ✅ Error handling and exceptions
• ✅ Compatible with PHP 8.3+
• ✅ Framework-independent (Pure PHP)

Usage

Basic Usage: Extract Text from Image File

<?php

require 'vendor/autoload.php';

use Sabioweb\Ocr\SBOClient;
use Sabioweb\Ocr\SBORequestBuilder;

// Create client (API Key is optional)
$client = new SBOClient('YOUR_API_KEY');

// Extract text from image file
$builder = new SBORequestBuilder();
$response = $client->recognizeFromFile(
    $builder
        ->setFile('/path/to/image.jpg')
        ->setLanguage('fas+eng')
        ->build()
);

echo $response->getText();
echo "\nConfidence: " . $response->getConfidence();

Extract Text from URL

$builder = new SBORequestBuilder();
$response = $client->recognizeFromUrl(
    $builder
        ->setUrl('https://example.com/image.png')
        ->setLanguage('eng')
        ->build()
);

echo $response->getText();

Extract Text from PDF File

$builder = new SBORequestBuilder();
$response = $client->recognizeFromFile(
    $builder
        ->setFile('/path/to/document.pdf')
        ->setLanguage('fas+eng')
        ->build()
);

// Get text from all pages
echo $response->getText();

// Get text from specific page
echo $response->getTextByPage(0); // First page
echo $response->getTextByPage(1); // Second page

// Page count
echo "Total pages: " . $response->getPageCount();

Advanced Settings

$builder = new SBORequestBuilder();
$response = $client->recognizeFromFile(
    $builder
        ->setFile('/path/to/image.jpg')
        ->setLanguage('fas+eng')
        ->setOcrEngine(2) // OCR Engine (1-3)
        ->setIsOverlayRequired(true) // Get overlay information
        ->setScale('2') // Image scale
        ->setDetectOrientation('true') // Detect image orientation
        ->build()
);

// Get overlay for first page
$overlay = $response->getOverlayByPage(0);

Error Handling

use Sabioweb\Ocr\Exception\NetworkException;
use Sabioweb\Ocr\Exception\OcrApiException;
use Sabioweb\Ocr\Exception\ValidationException;

try {
    $response = $client->recognizeFromFile($request);
    echo $response->getText();
} catch (ValidationException $e) {
    echo "Validation error: " . $e->getMessage();
} catch (NetworkException $e) {
    echo "Network error: " . $e->getMessage();
} catch (OcrApiException $e) {
    echo "API error: " . $e->getMessage();
    $errorDetails = $e->getErrorDetails();
}

Laravel Usage

Controller Example

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Sabioweb\Ocr\SBOClient;
use Sabioweb\Ocr\SBORequestBuilder;
use Sabioweb\Ocr\Exception\OcrApiException;

class OcrController extends Controller
{
    public function recognizeImage(Request $request)
    {
        $request->validate([
            'image' => 'required|image|mimes:jpeg,png,jpg|max:10240',
        ]);

        try {
            $client = new SBOClient(config('services.ocr.api_key'));
            
            $builder = new SBORequestBuilder();
            $response = $client->recognizeFromFile(
                $builder
                    ->setFile($request->file('image')->getRealPath())
                    ->setLanguage('fas+eng')
                    ->setIsOverlayRequired(false)
                    ->build()
            );
            
            return response()->json([
                'success' => true,
                'text' => $response->getText(),
                'confidence' => $response->getConfidence(),
                'processing_time' => $response->getProcessingTimeInMilliseconds(),
            ]);
        } catch (OcrApiException $e) {
            return response()->json([
                'success' => false,
                'error' => $e->getMessage(),
            ], 400);
        }
    }

    public function recognizeFromUrl(Request $request)
    {
        $request->validate([
            'url' => 'required|url',
        ]);

        $client = new SBOClient(config('services.ocr.api_key'));
        
        $builder = new SBORequestBuilder();
        $response = $client->recognizeFromUrl(
            $builder
                ->setUrl($request->input('url'))
                ->setLanguage('fas+eng')
                ->build()
        );
        
        return response()->json([
            'success' => true,
            'text' => $response->getText(),
            'confidence' => $response->getConfidence(),
        ]);
    }
}

Service Class Example

<?php

namespace App\Services;

use Sabioweb\Ocr\SBOClient;
use Sabioweb\Ocr\SBORequestBuilder;

final class OcrService
{
    public function __construct(
        private readonly SBOClient $client
    ) {}

    public function extractTextFromFile(string $filePath, string $language = 'fas+eng'): string
    {
        $builder = new SBORequestBuilder();
        $request = $builder
            ->setFile($filePath)
            ->setLanguage($language)
            ->build();

        $response = $this->client->recognizeFromFile($request);
        
        return $response->getText();
    }

    public function extractTextFromUrl(string $url, string $language = 'fas+eng'): string
    {
        $builder = new SBORequestBuilder();
        $request = $builder
            ->setUrl($url)
            ->setLanguage($language)
            ->build();

        $response = $this->client->recognizeFromUrl($request);
        
        return $response->getText();
    }
}

API Reference

SBOClient

Main client class for communicating with OCR.Space API.

Methods

• recognizeFromFile(SBORequest $request): SBOResponse
  Extract text from file (image or PDF)

• recognizeFromUrl(SBORequest $request): SBOResponse
  Extract text from URL (image or PDF)

SBORequestBuilder

Builder class for creating OCR requests using Fluent Interface.

Methods

• setFile(string $filePath): self - Set file path
• setUrl(string $url): self - Set URL
• setLanguage(string $language): self - Set language (e.g., 'eng', 'fas', 'fas+eng')
• setOcrEngine(int $ocrEngine): self - Set OCR engine (1-3)
• setIsOverlayRequired(bool $isOverlayRequired): self - Get overlay information
• setScale(string $scale): self - Set image scale
• setDetectOrientation(string $detectOrientation): self - Detect image orientation
• setIsCreateSearchablePdf(bool $isCreateSearchablePdf): self - Create searchable PDF
• setIsSearchablePdfHideTextLayer(bool $isSearchablePdfHideTextLayer): self - Hide text layer in PDF
• build(): SBORequest - Build and return request

SBOResponse

Response class for managing OCR results.

Methods

• getText(): string - Get extracted text from all pages
• getTextByPage(int $pageIndex): ?string - Get text from specific page
• getConfidence(): float - Get average confidence
• getConfidenceByPage(int $pageIndex): ?float - Get confidence for specific page
• getPageCount(): int - Get page count
• getOverlayByPage(int $pageIndex): ?array - Get overlay for specific page
• getAllOverlays(): array - Get all overlays
• getProcessingTimeInMilliseconds(): int - Get processing time in milliseconds
• getSearchablePdfOutput(): ?string - Get searchable PDF output (base64)
• isErroredOnProcessing(): bool - Check if error occurred
• getErrorMessage(): string - Get error message
• getErrorDetails(): string - Get error details

Exception Classes

• OcrException - Base exception class
• NetworkException - Network error
• OcrApiException - API error
• ValidationException - Validation error

Supported Languages

• eng - English
• fas - Persian/Farsi
• ara - Arabic
• deu - German
• fra - French
• spa - Spanish
• And other languages supported by OCR.Space

To use multiple languages, separate them with +: 'fas+eng'

Testing

To run tests:

composer install
vendor/bin/phpunit

License

This package is released under the MIT License.

Support

For support and bug reports, visit Sabioweb or GitHub Repository.