README

Export entries as PDF and compress, watermark or protect PDF assets without leaving the Statamic Control Panel, powered by the PDFGate PDF API.

Editors get four new actions in the places they already work, and templates get one tag:

Export as PDF in every collection. Pick an entry and download it as a PDF, or pick several and download a zip.
Compress PDF, Watermark PDF and Protect PDF in every asset container. Each one replaces the file in place or saves a new file next to it.
{{ pdfgate:download_url }} in Antlers gives visitors a "Download as PDF" link for the current page.

Rendering and processing happen on PDFGate's servers. Your site needs no headless browser, no Ghostscript and no PDF library, and it works on any host, including shared hosting and Statamic Cloud-style setups where you cannot install binaries.

Requirements

Statamic 5 or 6
PHP 8.2 or newer with ext-curl and ext-json
A PDFGate account and API key

Quick start

Install the addon:
```
composer require pdfgate/statamic
```
Create an API key in the PDFGate dashboard and add it to your site's .env:
```
PDFGATE_API_KEY=live_your_api_key
```
Keys that start with live_ call the production API, keys that start with test_ call the sandbox API. Sandbox requests are meant for testing and are not charged on a paid PDFGate plan.
Open a collection in the Control Panel, pick a published entry and choose Export as PDF from its action menu. The PDF downloads.
Open an asset container, pick a PDF and choose Compress PDF. Keep "Replace the original file" and run it. The file size drops in the listing.

That is the whole setup. The actions appear for users who can view entries and edit assets, and the sections below explain each one and the options you can change.

Export entries as PDF

Open a collection, pick an entry and choose Export as PDF from its action menu. The browser downloads {slug}.pdf. Select several entries in the listing to download entries.zip with one PDF per entry. The action is available in the list view and in the tree view of structured collections.

By default PDFGate loads the entry's public URL and renders it exactly as a visitor would see it, with your layout, stylesheets and fonts. The page must be reachable from the internet and the entry must be published. Drafts do not show the action in this mode. If the PDF comes back without styles, check that the stylesheet links use the same scheme as the page. A site served over https behind a proxy or load balancer needs Laravel's trusted proxies set, otherwise it writes http links that the renderer drops as mixed content.

For sites that are not public, such as a staging server or a site behind a login, or to export drafts, switch to HTML mode. Statamic renders the entry's template and sends the HTML to PDFGate instead. Stylesheets, fonts and images are still loaded from your APP_URL, so they need to be public for the PDF to look like the page.

PDFGATE_STATAMIC_SOURCE=html

Page size, orientation, margins and the other render options are set once in the config file, see below.

Download link in your templates

<a href="{{ pdfgate:download_url }}">Download as PDF</a>

The tag returns a signed link to the current entry's PDF. Pass entry="..." with an entry ID to link another entry. Only links created by the tag work, so nobody can turn your site into a PDF service for arbitrary pages, and requests are limited per IP address. The route can be turned off and the limit changed in the config file.

Compress, watermark and protect PDF assets

Open an asset container, pick a PDF and choose an action from its menu. All three work on a multi-selection too. Other file types do not show the actions.

Action	What it does	Options
Compress PDF	Reduces the file size of PDFs uploaded by editors, often by more than half.	None. Linearization for faster web viewing can be turned on in the config file.
Watermark PDF	Stamps a text on every page, for drafts, confidential documents or branding.	Text, font size, opacity, rotation and colour.
Protect PDF	Encrypts the file with AES-256 so it can only be opened with a password.	Password to open, an optional owner password, and switches to disable printing, copying and editing.

Each dialog ends with a Result choice:

Replace the original file writes the processed PDF over the asset. Its path, metadata and every field that references it stay the same.
Save as a new file next to the original creates {name}-compressed.pdf, {name}-watermarked.pdf or {name}-protected.pdf in the same folder and leaves the original untouched.

When a request fails, the message from PDFGate is shown in the Control Panel together with the file name, and the asset is left as it was.

Configuration

Publish the config file to change the defaults:

php artisan vendor:publish --tag=pdfgate-statamic-config

Key	Default	Description
`entries.source`	`url`	`url` renders the entry's public URL, `html` renders the template and sends the HTML.
`entries.options`	A4, print background	Render options applied to every export, for example `orientation`, `margin` or `pageSizeType`. See the HTML to PDF API reference.
`entries.download_route`	`true`	Registers the route used by the `{{ pdfgate:download_url }}` tag.
`entries.throttle`	`10`	Requests per minute per IP address allowed on the download route.
`assets.compress.linearize`	`false`	Optimise compressed PDFs for page-by-page web viewing.
`delete_remote_documents`	`true`	Delete the uploaded and generated documents from your PDFGate account once the file has been delivered to Statamic.

Need more?

PDFGate also fills PDF forms, adds form fields, flattens documents, extracts form data and sends documents out for e-signature. If you would like any of these inside Statamic, for example signing a contract generated from an entry, open an issue and tell us about your use case and we can build it.

License

MIT. See LICENSE.

pdfgate / statamic

Package info

Security

Statistics