Official PHP SDK for LeapOCR - Modern PHP client with enums, value objects, and typed exceptions

PHP SDK

Official PHP SDK for LeapOCR - Transform documents into structured data using AI-powered OCR.

Installation

composer require leapocr/leapocr-php

Prerequisites

PHP 8.2 or higher
LeapOCR API key (sign up here)

Quick Start

<?php

require 'vendor/autoload.php';

use LeapOCR\Enums\Format;
use LeapOCR\Enums\Model;
use LeapOCR\LeapOCR;
use LeapOCR\Models\ProcessOptions;

$client = new LeapOCR((string) getenv('LEAPOCR_API_KEY'));

$job = $client->ocr()->processUrl(
    'https://example.com/document.pdf',
    new ProcessOptions(
        format: Format::STRUCTURED,
        model: Model::STANDARD_V2,
        schema: [
            'type' => 'object',
            'properties' => [
                'document_title' => ['type' => 'string'],
                'summary' => ['type' => 'string'],
            ],
            'required' => ['document_title'],
        ],
    ),
);

$result = $client->ocr()->waitUntilDone($job->jobId);

foreach ($result->pages as $page) {
    var_dump($page->result);
}

New to LeapOCR? Check out the Getting Started guide for a complete walkthrough.

Key Features

Idiomatic PHP API - Enums, immutable value objects, and typed exceptions for the public SDK surface
Generated from the live API spec - Uses the real OpenAPI document from the running API
SDK-only public surface - Exposes only operations tagged for the SDK
Direct file upload support - Handles the presigned multipart upload flow for local files
Polling helpers - Wait for completion with a single method call
Webhook verification helper - Verify incoming X-R2-Signature headers with the raw request body

For models, formats, and schemas, see Core Concepts.

Usage Examples

Processing from URL

<?php

use LeapOCR\Enums\Format;
use LeapOCR\Enums\Model;
use LeapOCR\Models\ProcessOptions;

$job = $client->ocr()->processUrl(
    'https://example.com/invoice.pdf',
    new ProcessOptions(
        format: Format::STRUCTURED,
        model: Model::STANDARD_V2,
        schema: [
            'type' => 'object',
            'properties' => [
                'invoice_number' => ['type' => 'string'],
                'invoice_date' => ['type' => 'string'],
                'total' => ['type' => 'number'],
            ],
            'required' => ['invoice_number', 'invoice_date', 'total'],
        ],
    ),
);

$result = $client->ocr()->waitUntilDone($job->jobId);
var_dump($result->pages[0]->result);

Processing a Local File

<?php

use LeapOCR\Enums\Format;
use LeapOCR\Enums\Model;
use LeapOCR\Models\ProcessOptions;

$job = $client->ocr()->processFile(
    __DIR__ . '/invoice.pdf',
    new ProcessOptions(
        format: Format::STRUCTURED,
        model: Model::PRO_V2,
        schema: [
            'type' => 'object',
            'properties' => [
                'invoice_number' => ['type' => 'string'],
                'total_amount' => ['type' => 'number'],
                'invoice_date' => ['type' => 'string'],
                'vendor_name' => ['type' => 'string'],
            ],
            'required' => ['invoice_number', 'total_amount'],
        ],
    ),
);

Using Instructions

Provide natural language instructions to guide the extraction process. Instructions are useful when you need specific formatting, handling of edge cases, or contextual information:

<?php

use LeapOCR\Enums\Format;
use LeapOCR\Models\ProcessOptions;

$job = $client->ocr()->processUrl(
    'https://example.com/invoice.pdf',
    new ProcessOptions(
        format: Format::STRUCTURED,
        schema: [
            'type' => 'object',
            'properties' => [
                'invoice_number' => ['type' => 'string'],
                'invoice_date' => ['type' => 'string'],
                'total_amount' => ['type' => 'number'],
            ],
            'required' => ['invoice_number', 'invoice_date', 'total_amount'],
        ],
        instructions: "Extract invoice number, date, and total amount. If the invoice number is missing, use 'N/A'. Format dates as YYYY-MM-DD.",
    ),
);

$result = $client->ocr()->waitUntilDone($job->jobId);

Using Templates

Use pre-configured templates for common document types. Templates include predefined schemas, instructions, and model settings:

<?php

use LeapOCR\Models\ProcessOptions;

$job = $client->ocr()->processFile(
    __DIR__ . '/invoice.pdf',
    new ProcessOptions(templateSlug: 'invoice-extraction'),
);

$result = $client->ocr()->waitUntilDone($job->jobId);
var_dump($result->pages[0]->result);

Webhook Signature Verification

Use LeapOCR::verifyWebhookSignature() with the raw request body exactly as received:

<?php

use LeapOCR\LeapOCR;

$rawBody = file_get_contents('php://input') ?: '';
$signature = $_SERVER['HTTP_X_R2_SIGNATURE'] ?? '';
$secret = (string) getenv('LEAPOCR_WEBHOOK_SECRET');

if (!LeapOCR::verifyWebhookSignature($rawBody, $signature, $secret)) {
    http_response_code(401);
    echo 'Invalid signature';
    exit;
}

$payload = json_decode($rawBody, true, flags: JSON_THROW_ON_ERROR);

Do not verify against re-encoded JSON. Use the original body string from the HTTP request.

Configuration

<?php

use LeapOCR\Config\ClientConfig;
use LeapOCR\LeapOCR;

$client = new LeapOCR(
    (string) getenv('LEAPOCR_API_KEY'),
    new ClientConfig(
        baseUrl: 'https://api.leapocr.com/api/v1',
        timeoutSeconds: 30.0,
        maxRetries: 3,
        retryDelayMilliseconds: 1000,
        retryMultiplier: 2.0,
    ),
);

Error Handling

The SDK throws typed exceptions for the public API:

AuthenticationException
ValidationException
FileException
JobException
JobFailedException
JobTimeoutException
RateLimitException
NetworkException
ApiException

<?php

use LeapOCR\Exceptions\AuthenticationException;
use LeapOCR\Exceptions\JobFailedException;
use LeapOCR\Exceptions\ValidationException;

try {
    $result = $client->ocr()->waitUntilDone($job->jobId);
} catch (AuthenticationException $exception) {
    // Invalid or missing API key
} catch (ValidationException $exception) {
    // Invalid request options
} catch (JobFailedException $exception) {
    // The job reached a failed terminal state
}

See the Troubleshooting Guide for common issues and solutions.

API Reference

Client Initialization

new LeapOCR(string $apiKey, ?ClientConfig $config = null)

Processing Methods

$client->ocr()->processUrl(string $url, ?ProcessOptions $options = null): Job;
$client->ocr()->processFile(string $filePath, ?ProcessOptions $options = null): Job;
$client->ocr()->getJobStatus(string $jobId): JobStatus;
$client->ocr()->getJobResult(string $jobId): OCRResult;
$client->ocr()->waitUntilDone(string $jobId, ?PollOptions $options = null): OCRResult;
$client->ocr()->deleteJob(string $jobId): void;

Processing Options

new ProcessOptions(
    ?Format $format = null,
    Model|string|null $model = null,
    ?array $schema = null,
    ?string $instructions = null,
    ?string $templateSlug = null,
)

Next Steps

Explore Common Use Cases for real-world examples
Learn about Processing Models
Review Custom Schemas for structured extraction
Check the FAQ for common questions

Resources

Packagist: packagist.org/packages/leapocr/leapocr-php
GitHub: github.com/leapocr/leapocr-php
Issues: GitHub Issues

PHP SDK

On this page