README

Official PHP SDK for the PDFGate HTTP API.

PDFGate lets you generate, process, and secure PDFs via a simple API:

• HTML or URL to PDF
• Fillable forms
• Create signing envelopes from source documents
• Flatten, compress, watermark, protect PDFs
• Extract PDF form data

🚀 SDK Documentation: https://pdfgate.github.io/pdfgate-sdk-php
🧭 API Reference: https://pdfgate.github.io/pdfgate-sdk-php/api/
📘 API Documentation: https://pdfgate.com/documentation
🔑 Dashboard & API keys: https://dashboard.pdfgate.com

Requirements

• PHP 7.4+
• ext-curl
• ext-json

Installation

composer require pdfgate/pdfgate-sdk-php

Quick Start

<?php

use PdfGate\PdfGateClient;

$client = new PdfGateClient('live_your_api_key');

$generated = $client->generatePdf([
    'url' => 'https://example.com',
    'pageSizeType' => 'a4',
    'preSignedUrlExpiresIn' => 1200
]);

echo $generated->getFileUrl();

Usage Examples

Generate PDF

$client->generatePdf([
    'html' => '<h1>Hello</h1>',
    'pageSizeType' => 'a4',
    'metadata' => ['source' => 'sdk'],
]);

Upload PDF

$client->uploadFile([
    'file' => new \CURLFile('/absolute/path/source.pdf', 'application/pdf', 'source.pdf'),
    'preSignedUrlExpiresIn' => 1200,
]);

Create Envelope

use PdfGate\Enum\EnvelopeStatus;

$envelope = $client->createEnvelope([
    'requesterName' => 'John Doe',
    'documents' => [
        [
            'sourceDocumentId' => '6642381c5c61',
            'name' => 'Employment Agreement',
            'recipients' => [
                [
                    'email' => 'anna@example.com',
                    'name' => 'Anna Smith',
                ],
            ],
        ],
    ],
    'metadata' => ['customerId' => 'cus_123'],
]);

if ($envelope->getStatus() === EnvelopeStatus::CREATED) {
    echo $envelope->getId();
}

Send Envelope

use PdfGate\Enum\EnvelopeStatus;

$sentEnvelope = $client->sendEnvelope('69c0fa44f83ca6a7015f1c8c');

if ($sentEnvelope->getStatus() === EnvelopeStatus::IN_PROGRESS) {
    echo 'Envelope emails have been sent.';
}

Get Envelope

use PdfGate\Enum\EnvelopeStatus;

$envelope = $client->getEnvelope('69c0fa44f83ca6a7015f1c8c');

if ($envelope->getStatus() === EnvelopeStatus::IN_PROGRESS) {
    echo 'Envelope is still awaiting signatures.';
}

Download File

$stream = $client->getFile($documentId);
$output = fopen('output.pdf', 'wb');
stream_copy_to_stream($stream, $output);
fclose($output);
fclose($stream);

For complete operation examples (flattenPdf, compressPdf, protectPdf, watermarkPdf, extractPdfFormData, getDocument, createEnvelope, sendEnvelope, getEnvelope), see API.

To download generated files, enable Save files for one month in PDFGate Dashboard settings.

Error Handling

Non-2xx responses throw PdfGate\Exception\ApiException with:

• getStatusCode()
• getResponseBody() (truncated)

Transport and parsing failures throw PdfGate\Exception\TransportException and preserve original causes. Webhook verification failures throw PdfGate\Exception\SignatureVerificationException.

See Error handling guide for patterns and retry guidance.

Webhook Verification

Use WebhookSignatureVerifier to verify the x-pdfgate-signature header against the raw request body and your webhook secret.

use PdfGate\Exception\SignatureVerificationException;
use PdfGate\Webhook\WebhookSignatureVerifier;

$secret = 'whsecret_...';
$signatureHeader = $_SERVER['HTTP_X_PDFGATE_SIGNATURE'] ?? null;
$rawBody = file_get_contents('php://input');

try {
    WebhookSignatureVerifier::verify($secret, $signatureHeader, $rawBody === false ? '' : $rawBody);
    http_response_code(200);
} catch (SignatureVerificationException $e) {
    error_log($e->getMessage());
    http_response_code(400);
}

Development

This section is the source of truth for setup and test commands.

Local setup

composer install

Run tests

Unit tests:

composer run test:unit

Acceptance tests (real API calls):

PDFGATE_API_KEY=your_key composer run test:acceptance

Static analysis

composer run stan

Build documentation

Generate API docs (requires phpDocumentor in PATH, or PHPDOC_BIN):

composer run docs:api

Render the curated guides into the published site layout:

composer run docs:site

Validate markdown links:

composer run docs:check-links

Run both:

composer run docs:build

The combined docs site is generated into build/docs/site, with curated guides at the site root and API reference under build/docs/site/api. GitHub Pages publishes that combined artifact.

Generate the changelog manually

If you want to update CHANGELOG.md before or after making a release, run the generator manually. It reads commit subjects since the previous semver tag and updates CHANGELOG.md for the release version you provide.

Generate changelog content for a release version:

RELEASE_VERSION=1.2.3 php scripts/prepare-release.php

Preview the update without writing CHANGELOG.md:

DRY_RUN=1 RELEASE_VERSION=1.2.3 php scripts/prepare-release.php

If there are no updates since the previous release, the script generates a fallback Changed note instead of failing.