moonforge/scanforge

Official PHP SDK for the scan-forge OCR service

v1.0.0 2026-04-27 16:18 UTC

Requires

• php: >=8.1
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• Moonforge

• pdf
• document
• barcode
• OCR
• scan-forge

README

Official PHP SDK for the scan-forge OCR service — an on-premise, AI-powered drop-in replacement for ABBYY Recognition Server.

Installation

composer require moonforge/scanforge

Requires PHP 8.1+.

Quick Start

<?php
use Moonforge\ScanForge\Client;

$client = new Client('sf_live_...');

// Extract text from a PDF
$result = $client->ocr('faktura.pdf');
echo $result->text;

// Detect barcodes
$barcodes = $client->barcodes('dokument.pdf');
foreach ($barcodes as $b) {
    echo $b->value . ' ' . $b->type;
}

// Convert a scan to DOCX
$client->convert('skan.png', ['output' => 'wynik.docx']);

API Reference

new Client($apiKey, $baseUrl = 'https://api.scanforge.tech', $httpClient = null)

Creates a new client instance.

Parameter	Type	Required	Default
$apiKey	string	Yes	—
$baseUrl	string	No	https://api.scanforge.tech
$httpClient	GuzzleHttp\Client|null	No	null (auto-created)

$client = new Client(
    apiKey:  'sf_live_...',
    baseUrl: 'https://ocr.your-server.com', // for self-hosted deployments
);

ocr(string $filePath, array $options = []): OcrResult

Extracts text from a PDF or image file.

Options

Key	Type	Default	Description
language	string	'pol'	OCR language code
page_number	int	—	Process a single page (0-indexed)

Returns OcrResult

class OcrResult {
    public readonly string $text;
    public readonly int    $pages;
    public readonly array  $metadata;
}

Example

$result = $client->ocr('invoice.pdf', ['language' => 'eng']);
echo $result->text;    // extracted text
echo $result->pages;   // number of pages processed

barcodes(string $filePath, array $options = []): BarcodeResult[]

Detects and decodes barcodes (1D and 2D) in a document.

Options

Key	Type	Default	Description
page_number	int	0	Page to scan (0 = all pages)

Returns BarcodeResult[]

class BarcodeResult {
    public readonly string $value;  // decoded barcode content
    public readonly string $type;   // symbology e.g. 'EAN-13', 'QR-Code', 'CODE-128'
    public readonly int    $page;   // 1-indexed page number
}

Example

$barcodes = $client->barcodes('shipment.pdf');
foreach ($barcodes as $b) {
    echo $b->value . ' (' . $b->type . ') on page ' . $b->page . PHP_EOL;
}

convert(string $filePath, array $options = []): void

Converts a PDF or image to an editable document format. The output format is determined by the extension of $options['output'] (.docx → DOCX, .xlsx → XLSX).

Options

Key	Type	Required	Description
output	string	Yes	Destination path (.docx or .xlsx)
language	string	No	OCR language code (default 'pol')

Returns void — the converted file is written to output on the server.

Example

// Convert to Word document
$client->convert('scan.pdf', ['output' => 'result.docx']);

// Convert to Excel spreadsheet (preserves table structure)
$client->convert('table.pdf', ['output' => 'data.xlsx']);

Error Handling

All methods throw ScanForgeException on failure.

use Moonforge\ScanForge\Client;
use Moonforge\ScanForge\ScanForgeException;

$client = new Client('sf_live_...');

try {
    $result = $client->ocr('document.pdf');
} catch (ScanForgeException $e) {
    echo $e->getMessage();   // human-readable message
    echo $e->statusCode;     // HTTP status code (int or null for network errors)
    var_dump($e->body);      // raw response body from the server
}

Error condition	$statusCode
Invalid API key	401
Unsupported file type	422
Server error	5xx
Network / connection failure	null

Configuration

Self-hosted deployment

$client = new Client(
    'sf_live_...',
    'https://ocr.internal.example.com',
);

Environment variables (recommended)

$client = new Client(
    apiKey:  $_ENV['SCANFORGE_API_KEY'],
    baseUrl: $_ENV['SCANFORGE_URL'] ?? 'http://localhost:8000',
);

Requirements

• PHP 8.1+
• guzzlehttp/guzzle ^7.0 (installed automatically via Composer)
• A running scan-forge server — see deployment docs

License

MIT © Moonforge