docraptor-php

docraptor-php is DocRaptor’s native PHP client, generated from the service’s OpenAPI specification and wrapped around Guzzle for HTTP transport. It gives PHP applications a typed interface to DocRaptor’s Prince-powered rendering engine, letting developers turn arbitrary HTML content or URLs into PDF or XLSX documents without managing raw API requests, multipart payloads, or response parsing by hand.

The library covers DocRaptor’s full feature surface: synchronous and asynchronous document creation, test-mode watermarked documents for development, document hosting with expiring download links, and fine-grained Prince rendering options such as media type, page size, and JavaScript execution. Because the client is regenerated from the same OpenAPI document that drives DocRaptor’s other official SDKs, its method and model shapes stay consistent with the service’s documented API reference.

What You Get

• A DocApi client class exposing createDoc() for synchronous conversion and async equivalents for long-running jobs
• Typed Doc and AsyncDoc model classes covering every DocRaptor request option (document type, test mode, JavaScript rendering, tagging, callbacks)
• A PrinceOptions model for fine-tuning the underlying Prince XML rendering engine (media type, page size, base URL, and more)
• Built-in support for document hosting, including expiring hosted-download URLs and download limits
• Runnable example scripts for synchronous, asynchronous, and hosted-document workflows

Common Use Cases

• Generating downloadable PDF invoices, receipts, or reports from server-rendered HTML templates
• Converting HTML reports to XLSX spreadsheets for finance or export workflows
• Queuing large or high-volume document conversions asynchronously with a callback URL instead of blocking a request
• Serving time-limited, hosted document download links to end users without storing files in application storage

Under The Hood

Architecture The client follows a generated-SDK shape: a central DocApi class (lib/DocApi.php) owns a Guzzle ClientInterface and a Configuration object, and exposes createDoc()/createAsyncDoc()-style methods that serialize typed model objects (Doc, AsyncDoc, PrinceOptions in lib/) into multipart or JSON request bodies via a shared ObjectSerializer, then deserialize DocRaptor’s response back into typed objects or raw content. HeaderSelector centralizes content-negotiation logic, and ApiException wraps non-2xx responses with the response body attached, so callers can inspect API-side validation errors directly. This is a thin transport-and-serialization layer with no business logic beyond mapping the DocRaptor OpenAPI contract onto PHP classes.

Tech Stack The library targets PHP 7.4/8.x, depends on guzzlehttp/guzzle (^7.3) for HTTP transport and guzzlehttp/psr7 for PSR-7 message objects, and uses ext-curl, ext-json, and ext-mbstring as required PHP extensions. Dev dependencies are phpunit/phpunit for testing and friendsofphp/php-cs-fixer for style enforcement, declared under PSR-4 autoloading (DocRaptor\ mapped to lib/).

Code Quality All client and model code under lib/ is machine-generated by openapi-generator from docraptor.yaml and explicitly marked “Do not edit the class manually,” so hand-authored logic is limited to the script/ regeneration tooling and the runnable examples under examples/ and test/. The test/ directory contains scenario scripts (sync, async, hosted, XLSX, Prince options) that exercise the API against a live DocRaptor endpoint rather than a PHPUnit unit-test suite with mocked HTTP, and CI is configured via a legacy .travis.yml rather than GitHub Actions. Error handling is explicit throughout, with Guzzle connect/request exceptions caught and re-thrown as typed ApiExceptions carrying the response body.

API Design The public surface mirrors DocRaptor’s REST API closely: construct a Doc (or AsyncDoc) model, set the fields you need via fluent setters, and pass it to DocApi::createDoc(). Method and property names track the API reference one-to-one, which keeps the client predictable for anyone reading DocRaptor’s docs alongside the code, though it also means the generated style favors completeness over PHP-idiomatic ergonomics (e.g. verbose setter chains rather than constructor options or builders).