Download the PHP package eckinox/pdf-bundle without Composer

Generate PDFs from Twig templates in Symfony

Generating PDFs in Symfony should be simple.
And now, it is!

With this bundle, you can just render your PDFs like you render your Twig templates.

Getting started

1. Install Puppeteer

Before you proceed, make sure you have node and npm installed.

To install Puppeteer and its dependencies, we recommend you take a look at Puppeteer's official installation guide as well as their official troubleshooting guide.

Here is a snippet for Ubuntu (tested on 20.04) that works well at the time of writing:

2. Install this package via Composer

3. Configure the request context globally

The bundle needs to know the URL of your app to do some nifty stuff under the hood.
You must therefore define the request context for your app in your parameters.

To learn more about these parameters, check out Symfony's console documentation.

4. Start generating PDFs!

Here's a basic example to get you started.
For more complete examples and information, check out the documentation below.

Formats

The PdfGeneratorInterface::renderPdf() accepts a third optional parameter named $format. This allows you to define the format and orientation that will be used to generate the PDF.

Using built-in formats

The easiest and most common way of specifying a format is to use the built-in FormatFactory, which can provide you with all of the most common formats.

Specifying a format using one of the built-in formats looks like the following:

Each format factory method accepts a boolean parameter $landscape that allows you to determine the desired orientation. This parameter defaults to Portrait mode (false).

List of built-in formats

Here is the list of built-in formats:

Specifying a custom format

If the built-in formats don't offer the size you're looking for, you can always create your own formats.

Simply create an instance of Format and specify your desired width and height. Optionnally, you may define orientation and margins as well.

The width and height arguments accept the following units: px, in, cm and mm.

Margins

Margins for the document should be handled directly in CSS within your document.

Although this library offers some margin support and provides this information to Puppeteer, Puppeteer does not actually use it in its current implementation.

You should therefore define margins with physical units (in, cm, or mm) on the @page or html element in CSS.

Outputting, downloading and storing PDFs

The PdfInterface instance returned by the PDF generator has three methods you can use:

• PdfInterface::output(string $filename) : returns a Response that outputs the PDF in the browser.
• PdfInterface::download(string $filename) : returns a Response that triggers a download of the PDF.
• PdfInterface::getContent() : returns the PDF's content as a string.
  • This is useful to store the PDF to the local filesystem or to external storage like Amazon S3 or DO Spaces.

Troubleshooting

Large filesize (or: my PDFs are way too big!!)

This bundle relies on Puppeteer, which relies on Chromium's PDF generation. And Chromium's PDF generation, depending on which version is used, can generate PDFs with a very large filesize when the PDF contains images or emojis.

An easy fix for this is to wrap your images in an SVG tag, like so:

When you do this, your image will be embedded into the PDF at its regular filesize instead of being re-rendered as a PDF. This should dramatically reduce the file size of your generated PDFs.

License

This bundle is licensed under the MIT license.