🐘PHP SDK

Official PHP client library for the Docs-Dispatcher API. Build document generation, email dispatch, SMS, invoicing, and e-signature workflows in modern PHP applications.

Requirements

PHP: 8.1 or higher
Composer: 2.0+

Versions

SDK Version

PHP Version

Branch

v0.2.x

8.1+

develop

v0.1.x

7.2+

php-7x

PHP 7.x Support: If you're still using PHP 7.2-7.4, use SDK v0.1.x from the php-7x branch. However, we strongly recommend upgrading to PHP 8.1+ for better performance and security.

Installation

Install via Composer:

composer require docs-dispatcher.io/sdk

Core Concepts

Understanding these concepts will help you use the SDK effectively:

Authentication

Two authentication methods are supported:

Bearer Token (JWT) - Recommended:

use DocsDispatcherIo\Sdk\Authentication\BearerTokenAuthentication;

$authentication = new BearerTokenAuthentication('your-jwt-token-here');

Basic Auth:

use DocsDispatcherIo\Sdk\Authentication\BasicAuthAuthentication;

$authentication = new BasicAuthAuthentication('username', 'password');

Get Your API Token: Log in to the Docs-Dispatcher dashboard and navigate to Settings → API Tokens to generate a new token.

Service

A service represents an API endpoint with its own parameters. Each service corresponds to a Docs-Dispatcher capability:

EmailService: Send emails with attachments
FileService: Generate documents from templates
SmsService: Send SMS messages
PostalService: Send postal mail
ESignService: Handle electronic signatures
UploadService: Upload files to external services
InvoicingService: Create invoices, quotes, or credit notes

For detailed service parameters, see the API documentation or Swagger format.

ServiceMediator

The ServiceMediator class manages your defined services and their configurations. It temporarily stores services before building the API request.

use DocsDispatcherIo\Sdk\ServiceMediator;

$serviceMediator = new ServiceMediator([$service1, $service2]);

Client

The Client class triggers API calls. It decorates a GuzzleHttp\Client instance and handles HTTP communication:

use DocsDispatcherIo\Sdk\Client;

$client = new Client($authentication);
$response = $client->executeRequest($serviceMediator, 'application/json');

Quick Start

Basic Setup

<?php

require_once 'vendor/autoload.php';

use DocsDispatcherIo\Sdk\Authentication\BearerTokenAuthentication;
use DocsDispatcherIo\Sdk\Client;
use DocsDispatcherIo\Sdk\Service\FileService;
use DocsDispatcherIo\Sdk\ServiceMediator;

// 1. Authenticate
$authentication = new BearerTokenAuthentication('your-jwt-token');
$client = new Client($authentication);

// 2. Create a service
$fileService = new FileService();
$fileService
    ->setTemplateName('contract-template')
    ->setData([
        'clientName' => 'John Doe',
        'contractDate' => '2025-01-15'
    ]);

// 3. Execute request
$serviceMediator = new ServiceMediator([$fileService]);
$response = $client->executeRequest($serviceMediator, 'application/pdf');

// 4. Handle response
file_put_contents('contract.pdf', $response);

Service Examples

Email Service

Send templated emails with dynamic content:

use DocsDispatcherIo\Sdk\Service\EmailService;

$emailService = new EmailService();
$emailService
    ->setFrom('[email protected]')
    ->setTo(['[email protected]'])
    ->setSubject('Welcome to Our Service')
    ->setTemplateName('welcome-email')
    ->setData([
        'username' => 'John Doe',
        'activationLink' => 'https://example.com/activate'
    ]);

$serviceMediator = new ServiceMediator([$emailService]);
$response = $client->executeRequest($serviceMediator, 'application/json');

Common Use Cases:

Welcome emails
Password reset notifications
Order confirmations
Invoice delivery

File Service

Generate documents from templates in various formats:

use DocsDispatcherIo\Sdk\Service\FileService;

$fileService = new FileService();
$fileService
    ->setTemplateName('report-template')
    ->setResultFileName('monthly-report.pdf')
    ->setData([
        'reportMonth' => 'January 2025',
        'totalRevenue' => 150000,
        'totalExpenses' => 75000
    ]);

$serviceMediator = new ServiceMediator([$fileService]);
$response = $client->executeRequest($serviceMediator, 'application/pdf');

// Save the PDF
file_put_contents('monthly-report.pdf', $response);

Supported Formats:

PDF
DOCX (Microsoft Word)
XLSX (Microsoft Excel)
HTML
PNG/JPG/SVG images

See Template Management for template creation.

SMS Service

Send SMS messages via configured providers:

use DocsDispatcherIo\Sdk\Service\SmsService;

$smsService = new SmsService();
$smsService
    ->setTo('+1234567890')
    ->setContent('Your verification code is: 123456')
    ->setProvider('SMS_FACTOR');

$serviceMediator = new ServiceMediator([$smsService]);
$response = $client->executeRequest($serviceMediator, 'application/json');

Supported Providers:

SMS Factor
Twilio
AWS SNS
Others (see SMS Providers)

Postal Service

Send physical mail via postal services:

use DocsDispatcherIo\Sdk\Service\PostalService;
use DocsDispatcherIo\Sdk\Argument\Address;

$recipient = new Address(
    'John Doe',
    '123 Main Street',
    '10001',
    'New York',
    'US'
);

$postalService = new PostalService();
$postalService
    ->setRecipient($recipient)
    ->setTemplateName('letter-template')
    ->setData([
        'message' => 'Thank you for your business!'
    ]);

$serviceMediator = new ServiceMediator([$postalService]);
$response = $client->executeRequest($serviceMediator, 'application/json');

E-Signature Service

Request electronic signatures:

use DocsDispatcherIo\Sdk\Service\ESignService;

$esignService = new ESignService();
$esignService
    ->setDocumentName('Service Agreement')
    ->setSignatureType('ADVANCED') // SIMPLE, ADVANCED, or QUALIFIED
    ->setSigners([
        [
            'firstname' => 'John',
            'lastname' => 'Doe',
            'email' => '[email protected]',
            'phoneNumber' => '+1234567890'
        ]
    ])
    ->setTemplateName('agreement-template')
    ->setData([
        'agreementDate' => '2025-01-15'
    ]);

$serviceMediator = new ServiceMediator([$esignService]);
$response = $client->executeRequest($serviceMediator, 'application/json');

Signature Types:

SIMPLE: Basic electronic signature
ADVANCED: Identity-verified signature
QUALIFIED: Legally binding qualified signature (eIDAS compliant)

See E-Signature Providers for provider configuration.

Invoicing Service

Create invoices, quotes, or credit notes with full customization.

Complete Invoicing Example

use DocsDispatcherIo\Sdk\Argument\Address;
use DocsDispatcherIo\Sdk\Argument\Enums\CustomerTypes;
use DocsDispatcherIo\Sdk\Argument\Enums\DiscountTypes;
use DocsDispatcherIo\Sdk\Argument\Enums\InvoiceDocumentTypes;
use DocsDispatcherIo\Sdk\Argument\InvoiceCustomer;
use DocsDispatcherIo\Sdk\Argument\InvoiceItem;
use DocsDispatcherIo\Sdk\Service\InvoicingService;
use DocsDispatcherIo\Sdk\ServiceMediator;

// 1. Create billing address
$billingAddress = new Address(
    'Acme Corp',           // Name
    '123 Main Street',     // Address
    '75001',               // Postal code
    'Paris',               // City
    'FR'                   // Country code (ISO 3166-1 alpha-2)
);

// 2. Create customer
$customer = new InvoiceCustomer(
    CustomerTypes::COMPANY,
    '[email protected]',
    $billingAddress
);
$customer
    ->setName('Acme Corporation')
    ->setVatNumber('FR12345678901')
    ->setRegistrationNumber('123456789')
    ->setPhone('+33123456789');

// 3. Create invoice items
$item1 = new InvoiceItem('Consulting Services', 150.00);
$item1
    ->setQuantity(10.0)
    ->setTaxPercent(20.0)
    ->setAdditionalInfo('Monthly retainer');

$item2 = new InvoiceItem('Development Services', 200.00);
$item2
    ->setQuantity(5.0)
    ->setTaxPercent(20.0)
    ->setDiscount(DiscountTypes::PERCENTAGE, 10.0, 'Volume discount');

// 4. Create invoicing service
$invoicingService = new InvoicingService(
    $customer,
    [$item1, $item2],
    InvoiceDocumentTypes::INVOICE,
    '2025-11-20'  // Issue date (YYYY-MM-DD)
);

$invoicingService
    ->setProvider('ipaidthat')  // or 'qonto', 'stripe'
    ->setTitle('Monthly Services Invoice')
    ->setExternalId('INV-2025-001')
    ->setCurrency('EUR')
    ->setLocale('fr_FR')
    ->setDueDate('2025-12-31')
    ->setShipping(25.50)
    ->setDiscount(DiscountTypes::PERCENTAGE, 5.0, 'Early payment discount')
    ->setSendByEmail(true)
    ->addRecipientEmail('[email protected]')
    ->setSendCopy(true);

// 5. Execute request
$serviceMediator = new ServiceMediator([$invoicingService]);
$response = $client->executeRequest($serviceMediator, 'application/json');

// Response contains invoice ID and metadata
$invoiceData = json_decode($response, true);
echo "Invoice created: " . $invoiceData['invoiceId'];

Customer Types

The SDK supports three customer types for different business scenarios:

Company Customer

For B2B transactions with businesses:

use DocsDispatcherIo\Sdk\Argument\Enums\CustomerTypes;
use DocsDispatcherIo\Sdk\Argument\InvoiceCustomer;

$customer = new InvoiceCustomer(
    CustomerTypes::COMPANY,
    '[email protected]',
    $billingAddress
);
$customer
    ->setName('Tech Solutions Inc')
    ->setRegistrationNumber('123456789')
    ->setVatNumber('US123456789');

Required Fields:

Company name (setName())
Registration number (setRegistrationNumber())
VAT number (setVatNumber())
Email
Billing address

Individual Customer

For B2C transactions with consumers:

use DocsDispatcherIo\Sdk\Argument\Enums\CustomerTypes;
use DocsDispatcherIo\Sdk\Argument\InvoiceCustomer;

$customer = new InvoiceCustomer(
    CustomerTypes::INDIVIDUAL,
    '[email protected]',
    $billingAddress
);
$customer
    ->setFirstname('John')
    ->setLastname('Doe')
    ->setDisplayName('John Doe');

Required Fields:

First name (setFirstname())
Last name (setLastname())
Email
Billing address

Freelance Customer

For transactions with freelancers/self-employed:

use DocsDispatcherIo\Sdk\Argument\Enums\CustomerTypes;
use DocsDispatcherIo\Sdk\Argument\InvoiceCustomer;

$customer = new InvoiceCustomer(
    CustomerTypes::FREELANCE,
    '[email protected]',
    $billingAddress
);
$customer
    ->setFirstname('Jane')
    ->setLastname('Smith')
    ->setBusinessName('Jane Smith Consulting')
    ->setRegistrationNumber('987654321')
    ->setVatNumber('FR987654321');

Required Fields:

First name (setFirstname())
Last name (setLastname())
Email
Billing address
Business name (optional)
Registration number (optional)
VAT number (optional)

Document Types

Choose the appropriate document type:

use DocsDispatcherIo\Sdk\Argument\Enums\InvoiceDocumentTypes;

// Standard invoice
InvoiceDocumentTypes::INVOICE

// Electronic invoice (e-facture, for French businesses)
InvoiceDocumentTypes::E_INVOICE

// Quote/Estimate
InvoiceDocumentTypes::QUOTE

// Credit note
InvoiceDocumentTypes::CREDIT

Discount Types

Apply discounts at item or invoice level:

use DocsDispatcherIo\Sdk\Argument\Enums\DiscountTypes;

// Percentage discount (e.g., 10%)
$item->setDiscount(DiscountTypes::PERCENTAGE, 10.0, 'Volume discount');

// Absolute discount (e.g., $50 off)
$item->setDiscount(DiscountTypes::ABSOLUTE, 50.0, 'Early payment discount');

Invoice Providers

iPaidThat (French invoicing platform):

$invoicingService->setProvider('ipaidthat');

Qonto (European business banking):

$invoicingService->setProvider('qonto');

Stripe (Payment processing with invoicing):

$invoicingService->setProvider('stripe');

See Invoice Providers for configuration details.

Service Composition

Chain multiple services in a single API call:

use DocsDispatcherIo\Sdk\Service\FileService;
use DocsDispatcherIo\Sdk\Service\EmailService;

// Generate document
$fileService = new FileService();
$fileService
    ->setTemplateName('proposal-template')
    ->setData(['proposalId' => 'PROP-2025-001']);

// Send via email
$emailService = new EmailService();
$emailService
    ->setFrom('[email protected]')
    ->setTo(['[email protected]'])
    ->setSubject('Your Proposal');

// Execute both services
$serviceMediator = new ServiceMediator([$fileService, $emailService]);
$response = $client->executeRequest($serviceMediator, 'application/json');

Error Handling

The SDK uses standard PHP exceptions for error handling:

use DocsDispatcherIo\Sdk\Exception\ApiException;

try {
    $response = $client->executeRequest($serviceMediator, 'application/json');
} catch (ApiException $e) {
    // Handle API errors
    if ($e->getCode() === 401) {
        echo "Authentication failed: Invalid token\n";
    } elseif ($e->getCode() === 400) {
        echo "Validation error: " . $e->getMessage() . "\n";
    } elseif ($e->getCode() === 404) {
        echo "Template not found\n";
    } else {
        echo "Unexpected error: " . $e->getMessage() . "\n";
    }

    // Log the full error
    error_log($e->getTraceAsString());
} catch (\Exception $e) {
    // Handle unexpected errors
    echo "System error: " . $e->getMessage() . "\n";
    error_log($e->getTraceAsString());
}

See Troubleshooting for common errors and solutions.

Available Services

Service

Class

Description

EmailService

Send emails with attachments

File

FileService

Generate documents from templates

SMS

SmsService

Send SMS messages

Postal

PostalService

Send postal mail

E-Sign

ESignService

Handle electronic signatures

Upload

UploadService

Upload files to external services

Invoicing

InvoicingService

Create invoices, quotes, credit notes

Advanced Usage

Custom Base URL

Override the default API endpoint:

$client = new Client($authentication, 'https://custom-api.example.com');

Custom HTTP Client

Provide your own Guzzle client instance:

use GuzzleHttp\Client as GuzzleClient;

$guzzle = new GuzzleClient([
    'timeout' => 30,
    'verify' => true,
    'headers' => [
        'User-Agent' => 'MyApp/1.0'
    ]
]);

$client = new Client($authentication, null, $guzzle);

Environment-Specific Configuration

// Load credentials from environment
$token = getenv('DOCSDISPATCHER_API_TOKEN');
$authentication = new BearerTokenAuthentication($token);

// Different endpoints per environment
$baseUrl = getenv('APP_ENV') === 'production'
    ? 'https://api.docs-dispatcher.io'
    : 'https://api.staging.docs-dispatcher.io';

$client = new Client($authentication, $baseUrl);

Example File

A complete usage example is available in the SDK repository:

exemple.php - Realistic usage scenarios

Documentation

API Documentation: https://api.docs-dispatcher.io/docs
Swagger UI: https://api.docs-dispatcher.io/docs/swagger

Repository

GitLab: https://gitlab.com/docs-dispatcher-clients/docsdispatcher-php-client
Pipeline:
Coverage:

Framework Integration

Laravel

// config/services.php
'docsdispatcher' => [
    'token' => env('DOCSDISPATCHER_TOKEN'),
],

// app/Services/DocumentService.php
use DocsDispatcherIo\Sdk\Authentication\BearerTokenAuthentication;
use DocsDispatcherIo\Sdk\Client;

class DocumentService
{
    private Client $client;

    public function __construct()
    {
        $auth = new BearerTokenAuthentication(config('services.docsdispatcher.token'));
        $this->client = new Client($auth);
    }

    // Your document methods...
}

Symfony

// config/services.yaml
services:
    DocsDispatcherIo\Sdk\Client:
        factory: ['App\Factory\DocsDispatcherFactory', 'create']
        arguments:
            $token: '%env(DOCSDISPATCHER_TOKEN)%'

// src/Factory/DocsDispatcherFactory.php
namespace App\Factory;

use DocsDispatcherIo\Sdk\Authentication\BearerTokenAuthentication;
use DocsDispatcherIo\Sdk\Client;

class DocsDispatcherFactory
{
    public static function create(string $token): Client
    {
        $auth = new BearerTokenAuthentication($token);
        return new Client($auth);
    }
}

Next Steps

Learn from Examples

Recipes & Use Cases

Configure Providers

Service Providers

Troubleshoot Issues

SDK Troubleshooting

Manage Templates

Template Management

Support

Issues: GitLab Issues
Email: [email protected]
Documentation: https://docs-dispatcher.io/docs

PreviousNode SDK NextJava SDK

Last updated 5 days ago

hashtagRequirements

hashtagVersions

hashtagInstallation

hashtagCore Concepts

hashtagAuthentication

hashtagService

hashtagServiceMediator

hashtagClient

hashtagQuick Start

hashtagBasic Setup

hashtagService Examples

hashtagEmail Service

hashtagFile Service

hashtagSMS Service

hashtagPostal Service

hashtagE-Signature Service

hashtagInvoicing Service

hashtagComplete Invoicing Example

hashtagCustomer Types

hashtagCompany Customer

hashtagIndividual Customer

hashtagFreelance Customer

hashtagDocument Types

hashtagDiscount Types

hashtagInvoice Providers

hashtagService Composition

hashtagError Handling

hashtagAvailable Services

hashtagAdvanced Usage

hashtagCustom Base URL

hashtagCustom HTTP Client

hashtagEnvironment-Specific Configuration

hashtagExample File

hashtagDocumentation

hashtagRepository

hashtagFramework Integration

hashtagLaravel

hashtagSymfony

hashtagNext Steps

hashtagSupport

Requirements

Versions

Installation

Core Concepts

Authentication

Service

ServiceMediator

Client

Quick Start

Basic Setup

Service Examples

Email Service

File Service

SMS Service

Postal Service

E-Signature Service

Invoicing Service

Complete Invoicing Example

Customer Types

Company Customer

Individual Customer

Freelance Customer

Document Types

Discount Types

Invoice Providers

Service Composition

Error Handling

Available Services

Advanced Usage

Custom Base URL

Custom HTTP Client

Environment-Specific Configuration

Example File

Documentation

Repository

Framework Integration

Laravel

Symfony

Next Steps

Support