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.
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:
curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget libappindicator3-1 libatk-bridge2.0-0 libgbm1
sudo npm install --global --unsafe-perm puppeteer
sudo chmod -R o+rx /root/.cache/puppeteer/chrome
composer require eckinox/pdf-bundle
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.
# config/services.yaml
parameters:
router.request_context.host: 'myapp.com'
router.request_context.scheme: 'https'
router.request_context.base_url: '/'
Here's a basic example to get you started.
For more complete examples and information, check out the documentation below.
<?php
namespace App\Controller;
use Eckinox\PdfBundle\Pdf\PdfGeneratorInterface;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
class ReportController extends AbstractController
{
/**
* @Route("/my-report", name="my_report")
*/
public function overview(PdfGeneratorInterface $pdfGenerator): Response
{
$pdf = $pdfGenerator->renderPdf("your_template.html.twig", [
"key" => "value",
"foo" => "bar",
]);
return $pdf->output();
}
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.
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:
<?php
namespace App\Controller;
use Eckinox\PdfBundle\Pdf\FormatFactory;
use Eckinox\PdfBundle\Pdf\PdfGeneratorInterface;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
class ReportController extends AbstractController
{
/**
* @Route("/my-report", name="my_report")
*/
public function overview(PdfGeneratorInterface $pdfGenerator): Response
{
$pdf = $pdfGenerator->renderPdf("your_template.html.twig", [], FormatFactory::a4());
return $pdf->output();
}
Each format factory method accepts a boolean parameter $landscape
that allows you to determine the
desired orientation. This parameter defaults to Portrait mode (false
).
Here is the list of built-in formats:
Format | Size | Factory method |
---|---|---|
Letter | 8.5in x 11in | FormatFactory::letter(bool $landscape = false) |
Legal | 8.5in x 14in | FormatFactory::legal(bool $landscape = false) |
Tabloid | 11in x 17in | FormatFactory::tabloid(bool $landscape = false) |
Ledger | 17in x 11in | FormatFactory::ledger(bool $landscape = false) |
A0 | 33.1in x 8in | FormatFactory::a0(bool $landscape = false) |
A1 | 23.4in x 1in | FormatFactory::a1(bool $landscape = false) |
A2 | 16.54in x 4in | FormatFactory::a2(bool $landscape = false) |
A3 | 11.7in x 54in | FormatFactory::a3(bool $landscape = false) |
A4 | 8.27in x 7in | FormatFactory::a4(bool $landscape = false) |
A5 | 5.83in x 27in | FormatFactory::a5(bool $landscape = false) |
A6 | 4.13in x 83in | FormatFactory::a6(bool $landscape = false) |
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
.
$format = new Format("4.25in", "5.5in");
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.
The PdfInterface
instance returned by the PDF generator has three methods you can use:
PdfInterface::output(string $filename)
: returns aResponse
that outputs the PDF in the browser.PdfInterface::download(string $filename)
: returns aResponse
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.
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:
<svg width="800" height="1200" xmlns="http:https://www.w3.org/2000/svg">
<image href="your-image" width="800" height="1200" />
</svg>
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.
This bundle is licensed under the MIT license.