README

Official PHP SDK for the PDFen.com API v2.

Features

✅ Full V2 API support
✅ AI-powered data extraction (invoice, email, form, table, legal, floor plan)
✅ Laravel Sanctum authentication
✅ Type-safe responses
✅ Fluent API interface
✅ Async & sync conversion modes
✅ File upload helpers
✅ Exception handling
✅ PSR-4 compliant

Installation

composer require pdfen/php-sdk

Quick Start

use Pdfen\Sdk\PdfenClient;

// Initialize client with API token
$client = new PdfenClient('your-api-token');

// Get user info
$user = $client->user()->get();
echo "Available credits: {$user->credits}\n";

// Convert a file (async mode)
$conversion = $client->convert()
    ->files(['document.docx'])
    ->workflow(1) // workflow ID
    ->async()
    ->execute();

echo "Execution ID: {$conversion->executionId}\n";

// Check status
$status = $client->executions()->get($conversion->executionId);
echo "Status: {$status->status}\n";

// Download when complete
if ($status->isCompleted()) {
    $client->executions()->download($conversion->executionId, 'output.pdf');
    echo "Downloaded to output.pdf\n";
}

Usage Examples

Synchronous Conversion

$conversion = $client->convert()
    ->files(['image.jpg'])
    ->workflow(2)
    ->sync() // Wait for completion
    ->execute();

if ($conversion->isCompleted()) {
    $client->executions()->download($conversion->executionId, 'result.pdf');
}

Multiple Files with Options

$conversion = $client->convert()
    ->files(['doc1.docx', 'doc2.docx', 'image.jpg'])
    ->workflow(1)
    ->options([
        'convert_metadata' => true,
        'page_size' => 'a4'
    ])
    ->async()
    ->execute();

echo "Credits charged: {$conversion->creditsCharged}\n";
echo "Credits remaining: {$conversion->creditsRemaining}\n";

Conversion with Advanced Options

// PDF to Word with page range and password
$conversion = $client->convert()
    ->files(['document.pdf'])
    ->workflow(10) // PDF to Word workflow
    ->options([
        'page_range' => '1-10,15-20',
        'output_format' => 'docx',
        'password' => 'secret123', // If PDF is password-protected
        'ocr' => true,
        'ocr_language' => 'nld'
    ])
    ->async()
    ->execute();

// Get available options for a workflow
$options = $client->workflows()->options(10);
foreach ($options->options as $option) {
    echo "{$option->key}: {$option->name}\n";
}

Cover Page Templates

// Get available cover templates
$templates = $client->user()->coverTemplates();

foreach ($templates->templates as $template) {
    echo "Template: {$template->name} (ID: {$template->template_id})\n";
}

// Use cover template in conversion
$conversion = $client->convert()
    ->files(['document.pdf'])
    ->workflow(5)
    ->coverTemplateId(123) // Use cover template ID 123
    ->execute();

List Available Workflows

$workflows = $client->user()->workflows();

foreach ($workflows->userWorkflows as $workflow) {
    echo "- {$workflow->name} (ID: {$workflow->id})\n";
}

Check Credits

$credits = $client->user()->credits();

echo "Personal credits: {$credits->personalCredits}\n";
echo "Organization credits: {$credits->organizationCredits}\n";
echo "Total available: {$credits->totalAvailable}\n";

Data Extraction

Extract structured data from documents using AI. Each extraction type returns JSON by default, or can download as CSV/Excel.

Invoice Extraction

$result = $client->extract()
    ->files(['invoice.pdf'])
    ->locale('nl')
    ->invoice();

echo "Credits charged: {$result->creditsCharged}\n";

foreach ($result->results as $file) {
    foreach ($file['invoices'] as $invoice) {
        echo "{$invoice['vendor_name']}: {$invoice['total']}\n";
    }
}

// Download as CSV
$client->extract()
    ->files(['invoice.pdf'])
    ->format('csv')
    ->invoiceDownload('/tmp/invoices.csv');

Email Extraction

$result = $client->extract()
    ->files(['message.eml'])
    ->email();

foreach ($result->results as $file) {
    foreach ($file['emails'] as $email) {
        echo "{$email['subject']}: {$email['from']['email']}\n";
    }
}

Form, Table, Legal Extraction

// Forms - extracts field names and values
$result = $client->extract()->files(['form.pdf'])->form();

// Tables - extracts tabular data
$result = $client->extract()->files(['report.pdf'])->table();

// Legal - extracts clauses, parties, dates
$result = $client->extract()->files(['contract.pdf'])->legal();

Floor Plan Extraction

$result = $client->extract()
    ->files(['floorplan.pdf'])
    ->template('full_detail') // room_overview, dimensions, or full_detail
    ->floorPlan();

foreach ($result->results as $file) {
    foreach ($file['rooms'] ?? [] as $room) {
        echo "{$room['name']}: {$room['area']} m²\n";
    }
}

Download Formats

All extraction types support binary download (CSV, Excel). Invoice also supports UBL:

$client->extract()->files(['data.pdf'])->format('excel')->tableDownload('/tmp/tables.xlsx');
$client->extract()->files(['invoice.pdf'])->format('ubl')->invoiceDownload('/tmp/invoice.xml');

Error Handling

use Pdfen\Sdk\Exceptions\InsufficientCreditsException;
use Pdfen\Sdk\Exceptions\ValidationException;
use Pdfen\Sdk\Exceptions\AuthenticationException;

try {
    $conversion = $client->convert()
        ->files(['large-file.pdf'])
        ->workflow(1)
        ->execute();

} catch (InsufficientCreditsException $e) {
    echo "Not enough credits: {$e->getMessage()}\n";
    echo "Credits needed: {$e->getCreditsNeeded()}\n";
    echo "Credits available: {$e->getCreditsAvailable()}\n";

} catch (ValidationException $e) {
    echo "Validation error: {$e->getMessage()}\n";
    print_r($e->getErrors());

} catch (AuthenticationException $e) {
    echo "Authentication failed: {$e->getMessage()}\n";
}

Configuration

Custom Base URL

$client = new PdfenClient(
    apiToken: 'your-token',
    baseUrl: 'https://custom-domain.com'
);

Custom HTTP Client Options

$client = new PdfenClient(
    apiToken: 'your-token',
    httpOptions: [
        'timeout' => 120,
        'verify' => true,
        'proxy' => 'tcp://localhost:8125'
    ]
);

API Reference

User Resource

$client->user()->get() - Get current user info
$client->user()->credits() - Get credits breakdown
$client->user()->workflows() - List available workflows (user, organization, system)
$client->user()->coverTemplates() - List cover page templates

Convert Resource

$client->convert() - Start conversion builder
->files(array $paths) - Set files to convert
->workflow(int $id) - Set workflow ID (required)
->coverTemplateId(int $id) - Set cover page template ID (optional)
->options(array $options) - Set conversion options
- Options vary by workflow/conversion type
- Common: password, page_range, page_size, orientation
- Use $client->workflows()->options($id) to discover available options
- See API v2 Options Documentation for full list
->async() - Use async mode (default)
->sync() - Use sync mode (wait for completion)
->execute() - Execute conversion

Workflow Resource

$client->workflows()->options(int $id) - Get available options for a workflow

Extraction Resource

$client->extract() - Start extraction builder
->files(array $paths) - Set files to extract data from
->locale(string $locale) - Set language hint (en or nl)
->format(string $format) - Set output format (json, csv, excel, ubl)
->template(string $template) - Set floor plan template (room_overview, dimensions, full_detail)
->invoice() / ->invoiceDownload($path) - Invoice extraction
->email() / ->emailDownload($path) - Email extraction
->form() / ->formDownload($path) - Form field extraction
->table() / ->tableDownload($path) - Table extraction
->legal() / ->legalDownload($path) - Legal document extraction
->floorPlan() / ->floorPlanDownload($path) - Floor plan extraction

Execution Resource

$client->executions()->get(int $id) - Get execution status
$client->executions()->download(int $id, string $path) - Download result

Testing

# Run all tests
composer test

# Run unit tests only
composer test-unit

# Run integration tests only
composer test-integration

Requirements

PHP 8.1 or higher
ext-json
Guzzle 7.x

License

MIT License - see LICENSE file for details.

Support

Documentation: https://pdfen.com/api/docs/v2
Postman: Import the OpenAPI spec directly in Postman via Import → URL
Email: support@pdfen.com
Issues: https://github.com/pdfen/php-sdk/issues

Changelog

See CHANGELOG.md for version history.

pdfen / php-sdk

Maintainers

Package info

Statistics

Security