README

Official PHP SDK for the PDFen.com API v2.

Features

• ✅ Full V2 API support
• ✅ 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([
        'pdf_type' => '2B',
        'ocr' => true,
        'ocr_language' => 'eng'
    ])
    ->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";

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
  • Common options: ocr, ocr_language, pdf_type, compression
  • Conversion-specific: password, page_range, output_format, etc.
  • 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

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
• Email: support@pdfen.com
• Issues: https://github.com/pdfen/php-sdk/issues

Changelog

See CHANGELOG.md for version history.