DEV Community: Denis Skripchenko

Migrating from mpdf: an MIT PDF toolkit with no GPL friction

Denis Skripchenko — Sat, 18 Jul 2026 08:57:39 +0000

Every PHP shop that ships proprietary software eventually hits the same
wall: the de-facto standard HTML→PDF library, mpdf, is GPL-2.0-only. That
means bundling it into an OEM product, an on-premise installer, or any
closed-source codebase requires either shipping your product under GPL or
negotiating a commercial license. I hit that wall often enough that I
built a replacement.

php-pdf (github.com/dskripchenko/php-pdf)
is a pure-PHP, MIT-licensed PDF toolkit: HTML/CSS input, fluent builders,
TTF embedding with subsetting, barcodes, charts, AcroForm, PKCS#7
signing, PDF/A and PDF/X — plus reading and merging existing PDFs.

"Sounds too good" — so prove it

A two-week-old library claiming production crypto and PDF/A conformance
deserves skepticism. That's why every push to main runs an independent
proof chain in CI:

PDF/A references (1a/1b/2b/2u/3b) validated with veraPDF — the industry-standard validator, not our own code;
PDF/X structure checked byte-level plus a Ghostscript render pass;
signatures verified by the OpenSSL CLI against the exact /ByteRange bytes — and a tampered byte must break verification;
renders diffed against golden images with poppler.

Reports are public artifacts on every run:
conformance page.

The migration is mechanical

For the typical mpdf call site, swap one import:

// before
$mpdf = new \Mpdf\Mpdf(['format' => 'A4', 'margin_left' => 15]);
$mpdf->WriteHTML($html);
$mpdf->Output('invoice.pdf', 'F');

// after
$mpdf = new \Dskripchenko\PhpPdf\Compat\Mpdf(['format' => 'A4', 'margin_left' => 15]);
$mpdf->WriteHTML($html);
$mpdf->Output('invoice.pdf', 'F');

The compat facade covers WriteHTML/AddPage/Output (all four
destinations), metadata setters and the common config keys — and it's
exercised by the test suite, so the examples in the
migration guide
are tested code, not aspiration. The guide also has the full native-API
mapping table and a find/replace cheat-sheet for Destination::*
constants.

What the facade deliberately does NOT do: mpdf-specific HTML extensions
(<pagebreak>, <barcode>), SetHeader shortcodes, font-config arrays.
Those map to the native API, which is better at all of them (real block
elements for headers/footers, a first-class Barcode element with 16
formats, engine-level font config).

And it's faster

Reproducible benchmark (isolated subprocesses, medians, pinned competitor
versions — composer bench from a clean clone re-runs everything):

Scenario	php-pdf	mpdf 8.3.1
HTML → PDF article (~5 pages)	12.0 ms	64.1 ms
100-page invoice	576 ms	2640 ms
Image grid (20 pages)	6.5 ms	36.1 ms

Full methodology and all four competitors:
BENCHMARKS.

Honest limitations

The HTML/CSS subset is narrower than mpdf's in places (@page rules map to a PageSetup object instead).
Nothing auto-embeds fonts: base-14 covers Latin; Cyrillic/Arabic/CJK need a TTF passed to the engine (it is subset automatically).
Public-key encryption (/PubSec) is intentionally unimplemented — we won't ship crypto we can't test against real fixtures.

Laravel users: there's a thin bridge —
dskripchenko/laravel-php-pdf
with a Pdf facade and a response()->pdf() macro.

If GPL friction has ever made you postpone a PDF feature, give it a try:
composer require dskripchenko/php-pdf. Issues and failing PDFs from
real-world producers are the most valuable thing you can send my way.

Generate, read, and merge PDFs in PHP — no GPL, no FPDI

Denis Skripchenko — Mon, 06 Jul 2026 11:14:39 +0000

Every PHP project eventually needs a PDF — an invoice, a ticket, a report, a
signed contract. And every time, you hit the same two walls:

Generating PDFs usually means mpdf, which is GPL-2.0. Fine for internal tools, a licensing headache the moment you ship it inside a commercial, OEM, or on-premise product.
Merging or importing existing PDFs (stamp a watermark, prepend a cover, overlay a letterhead) means FPDI — and FPDI's PDF-parsing add-on is proprietary.

dskripchenko/php-pdf is a
pure-PHP, MIT-licensed toolkit that does both — generate and read/merge —
with no native binaries and no add-ons. It runs anywhere your Laravel app runs
(only ext-mbstring, ext-dom, ext-zlib; ext-openssl for AES/signing).

composer require dskripchenko/php-pdf

Generating a PDF

Three entry points, from highest to lowest level. The quickest is HTML/CSS:

use Dskripchenko\PhpPdf\Document;

$pdf = Document::fromHtml(<<<HTML
<h1>Invoice #1042</h1>
<p>Customer: <strong>Acme Corp</strong></p>
<table>
  <thead><tr><th>Item</th><th>Price</th></tr></thead>
  <tbody>
    <tr><td>Consulting</td><td>$1,200.00</td></tr>
    <tr><td>Hosting</td><td>$99.00</td></tr>
  </tbody>
</table>
HTML)->toBytes();

There's also a fluent DocumentBuilder and a low-level page API, plus 16
barcode formats, 8 chart types, TTF embedding with kerning, AcroForm fields,
PKCS#7 signing, and PDF/A & PDF/X conformance. But generation isn't the news
here — reading and merging is.

New in 1.1: reading & merging

Merge and reorder pages

PdfMerger concatenates whole or selected pages from any mix of files and
in-memory bytes:

use Dskripchenko\PhpPdf\Pdf\Merge\{PdfMerger, PdfSource};

PdfMerger::create()
    ->append(PdfSource::fromFile('cover.pdf'))
    ->append(PdfSource::fromBytes($invoice))          // the bytes we just generated
    ->append(PdfSource::fromFile('terms.pdf'), pages: [1, 2])
    ->toFile('packet.pdf');

Page annotations and bookmarks are carried over by default, with internal links
and named destinations remapped to the new pages.

Stamp a watermark or letterhead

stamp() draws a source page over the output pages as a reusable Form XObject —
perfect for a "DRAFT" watermark or a corporate letterhead:

use Dskripchenko\PhpPdf\Pdf\Merge\{PdfMerger, PdfSource, Placement};

PdfMerger::create()
    ->append(PdfSource::fromFile('contract.pdf'))
    ->stamp(PdfSource::fromFile('draft-watermark.pdf'), placement: Placement::fit())
    ->toFile('contract-draft.pdf');

Placement gives you fit() (scale to page, centered), stretch(), or
at($x, $y, $scale) for pixel-precise positioning.

FPDI-style: drop an imported page into a generated document

Sometimes you want to combine an existing PDF with freshly generated
content — e.g. print "PAID" and a QR code onto a scanned letterhead. Import the
page as a Form XObject and draw over or under it with the normal API:

use Dskripchenko\PhpPdf\Pdf\Document;
use Dskripchenko\PhpPdf\Pdf\StandardFont;
use Dskripchenko\PhpPdf\Pdf\Merge\PageImporter;
use Dskripchenko\PhpPdf\Pdf\Reader\ReaderDocument;

$src = ReaderDocument::fromBytes(file_get_contents('letterhead.pdf'));
[$w, $h] = PageImporter::pageSize($src, 0);

$doc  = new Document();
$page = $doc->addPage(customDimensionsPt: [$w, $h]);

$form = PageImporter::intoDocument($doc, $src, 0);
$page->useFormXObject($form, 0, 0, $w, $h);                 // imported page as background
$page->showText('PAID', 400, 750, StandardFont::Helvetica, 28); // your content on top

$doc->toFile('paid.pdf');

Rotation and crop boxes are handled automatically; the imported page's fonts and
images are copied verbatim.

A Laravel example: batch invoices into one file

A common real-world job: generate a PDF per invoice, then merge the batch into a
single file for download or email. In a queued job:

use Illuminate\Contracts\Queue\ShouldQueue;
use Dskripchenko\PhpPdf\Document;
use Dskripchenko\PhpPdf\Pdf\Merge\{PdfMerger, PdfSource};

class BuildInvoiceBatch implements ShouldQueue
{
    /** @param \App\Models\Invoice[] $invoices */
    public function __construct(
        private array $invoices,
        private string $outputPath,
    ) {}

    public function handle(): void
    {
        $merger = PdfMerger::create();

        foreach ($this->invoices as $invoice) {
            $pdf = Document::fromHtml(view('pdf.invoice', ['invoice' => $invoice])->render())
                ->toBytes();

            $merger->append(PdfSource::fromBytes($pdf));
        }

        $merger->toFile($this->outputPath);
    }
}

One Blade view for the invoice, one PdfMerger for the batch — no shell-outs,
no wkhtmltopdf binary, no GPL.

Reading, too

Need to inspect an incoming PDF before merging? ReaderDocument parses it —
classic and stream cross-references, object streams, corrupt-xref recovery, and
decryption (RC4 / AES-128 / AES-256, user and owner password):

use Dskripchenko\PhpPdf\Pdf\Reader\ReaderDocument;

$doc = ReaderDocument::fromBytes(file_get_contents('protected.pdf'), password: 'secret');

echo $doc->pageCount();
foreach ($doc->pages() as $page) {
    printf("%.0f × %.0f pt\n", $page->width(), $page->height());
}

Encrypted input is decrypted transparently and re-emitted unencrypted in the
merged output.

What it handles (and doesn't, yet)

The reader is validated against a third-party corpus — LibreOffice, Google Docs,
Ghostscript, pdfTeX, ImageMagick, Qt/pdfkit, FPDF2, pypdf — with CI on PHP
8.2 / 8.3 / 8.4 and a PHPStan level-6 gate. v1 merging carries content, images,
fonts, annotations, and bookmarks; it does not yet carry AcroForm field
trees or structure tags. It's all documented in the
reading & merging guide.

Try it

GitHub: https://github.com/dskripchenko/php-pdf
Packagist: composer require dskripchenko/php-pdf
MIT-licensed, PHP 8.2+, pure PHP.

If your PHP app generates PDFs and you've been paying the mpdf/FPDI licensing tax
— or shelling out to a native binary — this might be worth a look. Feedback and
issues welcome.

Build a versioned Laravel API with auto-generated OpenAPI docs in 10 minutes

Denis Skripchenko — Thu, 11 Jun 2026 06:12:56 +0000

TL;DR — We'll install dskripchenko/laravel-api, write one controller, and end up with a versioned API (/api/v1/...) and interactive OpenAPI 3.0 docs at /api/doc — generated from the docblock you'd write anyway. Then we'll ship a v2 without copy-pasting a single controller.

The problem

Two things rot in every growing Laravel API:

Versioning. v1 ships, then v2 needs to change three endpoints but keep the other twenty. You either copy-paste a V2 folder (and now bugfixes live in two places) or bolt if ($version === 2) branches into your controllers.
Docs. The OpenAPI spec drifts from the code the moment you merge. Annotation libraries (#[OA\Get(...)], giant YAML files) ask you to describe your API twice — once in code, once in attributes.

This package's bet: your controller already describes itself. The method name, the request fields, the response shape — write them once, as a normal PHPDoc, and let the package derive routes and docs from it. Versioning becomes plain PHP inheritance.

Let's build it.

What we'll build

A tiny tasks API:

POST /api/v1/task/list — list tasks
POST /api/v1/task/create — create one
interactive docs at GET /api/doc (raw spec per version at /api/doc/{version})
then a v2 that adds an endpoint without touching v1

Total: ~4 small files.

Step 0 — Install

composer require dskripchenko/laravel-api

Publish the config (optional, but handy to see the knobs):

php artisan vendor:publish --tag=laravel-api-config

// config/laravel-api.php
return [
    'prefix'            => 'api',                            // → /api/...
    'uri_pattern'       => '{version}/{controller}/{action}',
    'available_methods' => ['get', 'post', 'put', 'patch', 'delete'],
    'openapi_path'      => 'public/openapi',
    'doc_middleware'    => [],                               // lock down /api/doc here
];

Step 1 — Write a controller

Nothing exotic — it extends the package's ApiController, which gives you response helpers (success(), error(), validationError(), created(), noContent(), notFound()). The docblock is the documentation:

<?php

namespace App\Api\V1\Controllers;

use Dskripchenko\LaravelApi\Controllers\ApiController;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class TaskController extends ApiController
{
    /**
     * List tasks
     * Returns the current user's tasks.
     *
     * @input integer ?$page Page number
     * @input string $status Filter by status [open,done]
     *
     * @output integer $id Task id
     * @output string $title Task title
     * @output string $status Current status
     *
     * @return JsonResponse
     */
    public function list(Request $request): JsonResponse
    {
        return $this->success([
            ['id' => 1, 'title' => 'Pack for Vietnam', 'status' => 'done'],
            ['id' => 2, 'title' => 'Write this article', 'status' => 'open'],
        ]);
    }

    /**
     * Create a task
     *
     * @input string $title Task title
     * @input string ?$status Initial status [open,done]
     *
     * @output integer $id New task id
     * @output string $title Task title
     *
     * @return JsonResponse
     */
    public function create(Request $request): JsonResponse
    {
        return $this->created([
            'id'    => 3,
            'title' => $request->input('title'),
        ]);
    }
}

A few docblock conventions worth knowing:

?$page → optional field.
string $status ... [open,done] → the bracketed list becomes an enum in the spec.
@input integer(int64) $id / @input string(email) $email → type with format.
@input file $avatar → file upload; @input @User $user → $ref to a component schema.

Every response is wrapped in a consistent envelope:

{ "success": true, "payload": { ... } }

Errors (thrown ApiException or $this->error()) come back as:

{ "success": false, "payload": { "errorKey": "string", "message": "string" } }

Step 2 — Wire up the version, the module, the provider

Three small classes. This is the whole routing layer — no routes/api.php entries.

<?php
// app/Api/V1/Api.php — defines what v1 exposes
namespace App\Api\V1;

use Dskripchenko\LaravelApi\Components\BaseApi;
use App\Api\V1\Controllers\TaskController;

class Api extends BaseApi
{
    public static function getMethods(): array
    {
        return [
            'controllers' => [
                'task' => [                          // → /api/v1/task/{action}
                    'controller' => TaskController::class,
                    'actions'    => ['list', 'create'],
                ],
            ],
        ];
    }
}

<?php
// app/Api/ApiModule.php — maps version strings to Api classes
namespace App\Api;

use Dskripchenko\LaravelApi\Components\BaseModule;

class ApiModule extends BaseModule
{
    public function getApiVersionList(): array
    {
        return [
            'v1' => \App\Api\V1\Api::class,
        ];
    }
}

<?php
// app/Providers/ApiServiceProvider.php — plugs the module in
namespace App\Providers;

use Dskripchenko\LaravelApi\Providers\ApiServiceProvider as BaseApiServiceProvider;
use App\Api\ApiModule;

class ApiServiceProvider extends BaseApiServiceProvider
{
    protected function getApiModule(): ApiModule
    {
        return new ApiModule();
    }
}

return [
    App\Providers\AppServiceProvider::class,
    App\Providers\ApiServiceProvider::class,   // 👈
];

That's it. The base provider registers the routes and the /api/doc endpoint for you on boot.

Step 3 — Call it

curl -X POST http://localhost:8000/api/v1/task/list

{
  "success": true,
  "payload": [
    { "id": 1, "title": "Pack for Vietnam", "status": "done" },
    { "id": 2, "title": "Write this article", "status": "open" }
  ]
}

Actions are POST by default. Want GET? Declare it per action:
'list' => ['action' => 'list', 'method' => ['get']].

Step 4 — The payoff: free OpenAPI docs

Open GET /api/doc in a browser. You don't get a raw JSON file — you get a ready-to-use interactive API reference (rendered with Scalar), with a version switcher across v1, v2, … already wired up. The package walked your controllers, read those docblocks, and produced a complete OpenAPI 3.0 document — parameters, enums, response schemas, the lot. These docs can't drift, because they are the code.

Need the raw spec for CI, a client generator, or your own Redoc/Stoplight setup? Each version is served as JSON at GET /api/doc/{version} (e.g. /api/doc/v1) — no storage:link, no build step.

Need TypeScript clients? There's a generator:

php artisan api:generate-types

…and an exporter for Postman / HTTP Client / Markdown / cURL:

php artisan api:export --format=postman

Step 5 — Versioning without copy-paste

Here's the part that usually hurts. v2 should add an archive endpoint — but leave v1 untouched. You extend the previous version, at both the controller and the Api level.

The v2 controller inherits every v1 action and adds the new one:

<?php
// app/Api/V2/Controllers/TaskController.php
namespace App\Api\V2\Controllers;

use App\Api\V1\Controllers\TaskController as V1TaskController;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class TaskController extends V1TaskController   // inherits list() and create()
{
    /**
     * Archive a task
     *
     * @input integer $id Task id
     *
     * @output boolean $archived Whether it was archived
     */
    public function archive(Request $request): JsonResponse
    {
        return $this->success(['archived' => true]);
    }
}

And the v2 Api inherits every v1 action, swapping in the new controller:

<?php
// app/Api/V2/Api.php
namespace App\Api\V2;

use App\Api\V1\Api as V1Api;
use App\Api\V2\Controllers\TaskController;

class Api extends V1Api          // inherits every v1 action…
{
    public static function getMethods(): array
    {
        return [
            'controllers' => [
                'task' => [
                    'controller' => TaskController::class,   // …override just this one
                    'actions'    => [
                        'list',
                        'create',
                        'archive',          // add a brand-new action
                        'legacyExport' => false,   // → false disables an action (e.g. one inherited from v1)
                    ],
                ],
            ],
        ];
    }
}

// app/Api/ApiModule.php
public function getApiVersionList(): array
{
    return [
        'v1' => \App\Api\V1\Api::class,
        'v2' => \App\Api\V2\Api::class,
    ];
}

Now /api/v2/task/... is live, v2's docs appear automatically, and v1 never changed. Bugfix in a shared action? Fix it once in the base class. Need a clean break? Override the controller. Need to kill an endpoint in the new version? Set the action key to false (as with 'legacyExport' => false above).

Middleware cascades the same way — global → controller → action, with exclude-middleware / exclude-all-middleware escape hatches at each level.

Why this approach

	Annotation libs (`#[OA\...]`)	This package
Describe API	in code and in attributes	once, in the PHPDoc
Versioning	manual folders / `if` branches	PHP inheritance
Docs drift	possible (separate source)	impossible (derived)
Routes	hand-written	derived from `getMethods()`

It won't replace a full framework for every team — if you love attribute-driven specs, you'll miss them here. But if you've ever grep'd a controller wondering whether the docs still match it, this removes the question entirely.

Try it

composer require dskripchenko/laravel-api

⭐ Repo & full docs: https://github.com/dskripchenko/laravel-api
📦 Packagist: https://packagist.org/packages/dskripchenko/laravel-api

I maintain it — issues, ideas, and "this broke on my setup" reports are all welcome. What would you want a versioning-first API package to do that yours doesn't?