Download the PHP package bogdankharchenko/laravel-pdfmill without Composer

Laravel client for pdfmill

Merge, fill, stamp, split and read PDFs from Laravel, using your own deployment of pdfmill on Cloudflare Workers.

Every endpoint, operation, option and reply is generated from the API's OpenAPI spec as typed laravel-data classes. Your IDE and PHPStan know every field, and the docblocks repeat the API's own documentation.

Install

Add your deployment's address and API key to .env:

PDFMILL_TIMEOUT (seconds, default 120) and PDFMILL_CONNECT_TIMEOUT (default 10) are optional. To change the config file itself: php artisan vendor:publish --tag=pdfmill-config.

Use

Call the PdfMill facade, or inject BogdanKharchenko\PdfMill\Client.

Build a PDF step by step

create(), edit() and merge() return a PendingPdf. Each operation is a method on it, and nothing is sent until you end the chain:

Before that, ->filename('Contract 42.pdf') names the file, ->linkTtl(86400) sets how long store()'s link works, and ->withoutObjectStreams() writes a file that old tools can read.

Show a filled form in the browser

A FileResponse from ->file() can also be saved to a disk: ->file()->save('w9/ada.pdf', 's3').

Upload straight to S3

->file()->save() brings the whole PDF into your app's memory first. With ->put(), the Worker uploads it to your bucket itself. Spread in a presigned upload URL:

put() takes a URL and the headers it was signed with, as temporaryUploadUrl() returns them. It needs pdfmill 0.4 or later. An older deployment would keep the PDF in R2 instead, so put() throws an UnexpectedValueException rather than report an upload that didn't happen.

Merge uploads with a stored PDF

Add steps only sometimes

Read a PDF

Sources

Wherever the API takes a file, pass a string (an R2 key, or an http(s) URL) or a source object:

PdfSource adds password and preserveXFA, MergeSource adds pages, size and margin, and FontSource adds postscriptName. Requests that carry files go out as multipart; a source object used twice in one request is uploaded once.

Operations

Each operation is a PendingPdf method named after its op, run in the order you call them:

• Pages: addPage, removePages, selectPages, duplicatePage, rotatePages, resizePages, cropPages, setPageBoxes, scalePages, translateContent, insertPdf
• Drawing: drawText, drawImage, drawRectangle, drawEllipse, drawLine, drawSvgPath, drawSvg, drawPdfPage, watermark, pageNumbers
• Forms: fillForm, flattenForm, addFormField, setFieldProperties, removeFormFields, setFieldScript
• Scripts: addJavaScript, setXFAJavaScript, deleteXFA
• Document: setLayerVisibility, setViewerPreferences, setMetadata, attachFile, detachFile, convertToPDFA, embedFacturX, encrypt

Arguments you leave out are not sent, so the API's defaults apply. An explicit null is sent as null. Choices are enums in BogdanKharchenko\PdfMill\Enums, e.g. BuiltInFont::HelveticaBold or PaperSize::Letter. The API's README describes each operation in full.

Each operation is also a class in BogdanKharchenko\PdfMill\Operations, with the same arguments. Build a list of them elsewhere and add it with ->apply(...$operations).

Results

PDFs stored under the default outputs/ keys are deleted after 7 days if you set up the API's recommended R2 rule.

Errors

Every API error throws a subclass of BogdanKharchenko\PdfMill\Exceptions\ApiException. Each has the HTTP $status, the API's reply in $error, and a message that names the failing input, e.g. operations[2] (removePages): Page 9 is out of range.

Testing your app

PdfMill::fake() stands in for the API. Nothing is sent, every endpoint replies as the API would, and you assert on what your code asked for. It needs no PDFMILL_URL or key, and fakes a Client injected into your code too.

Only the network is replaced: your options are encoded and your files read just as in production.

By default every PDF is one blank A4 page. store() saves it under your key, or outputs/<uuid>.pdf. file(), download() and routes return a real PDF, and info(), text(), extract() and split() describe that page. To know keys and link expiry times in advance, use Str::freezeUuids() and $this->freezeTime().

put() gets that page's size and page count, but nothing is uploaded. If your code reads the file back, write it from a closure reply:

Set a reply

Give an endpoint its reply by name:

Assert

A failed assertion lists what was sent. PdfMill::sent('edit') returns the requests, to inspect yourself.

Each SentRequest has:

• endpoint
• data: the options sent, decoded from JSON
• files: the uploads
• operations()
• hasOperation()

hasOperation() finds an operation by name, hasOperation('watermark', ['text' => 'DRAFT']), or by an object built the way your code builds it, hasOperation(new Watermark(text: 'DRAFT')). It matches when the operation has at least the fields you give. Uploaded files match by filename and contents.

Without PdfMill::fake(), requests go through Laravel's HTTP client, so Http::fake() works too.

Working on this package

Everything in generated/ is produced from openapi.json, a copy of the API's spec, so don't edit it by hand. To update to a new API version:

composer test runs the tests, which use replies captured from the real API (tests/fixtures) and fail if generated/ is out of date. composer analyse runs PHPStan. To also run against a deployment:

License

MIT