README

By endroid

Library for easy PDF generation built around wkhtmltopdf and Snappy. Click here for an example. Please note this example takes some time to load because it contains a lot of pages and no caching is applied.

Read the blog for more information on why I created this library and how to use it.

Easy data loading

When you generate a PDF you need to make sure you pass the right contents to the PDF object. This data can come from any source (a file, a URL, a controller) and some of these impose a performance hit so you often want to cache some of these contents instead of loading the data every time you generate the PDF.

The endroid/asset takes this burden away by allowing you to define your assets via a simple array of options. The asset factory and guesser make sure the right type of asset is created and even provide a so called cache asset that wraps any other asset.

$this->pdfBuilder
    ->setCover([
        'controller' => CoverController::class,
        'parameters' => ['title' => 'My PDF', 'date' => new DateTime()],
        'cache_key' => 'cover',
        'cache_expires_after' => 3600,
        'cache_clear' => true, // use to purge any previously cached data
    ])
;

For more information read the documentation.

Handling external resources

An HTML page can contain a number of external resources, each triggering a separate request. However during PDF generation this can lead to performance or even stability issues. Therefor we need the number of requests to be as low as possible.

The endroid/embed library helps you minimize the number of assets to load during PDF generation by allowing you to embed external resources via a Twig extension. You can use this extension to embed resources like fonts, stylesheets and scripts.

<link rel="stylesheet" href="{{ embed(asset('/styles.css')) }}">

<style>
@font-face {
    font-family: 'SCP';
    font-weight: normal;
    src: url('{{ embed('https://fontlibrary.org/scp.ttf') }}');
}
</style>

For more information you can read the documentation.

The PDF builder

When endroid/installer detects Symfony the builder is automatically wired and you can immediately start using it to build a PDF. This is an example of how you can use the builder.

$pdfBuilder
    ->setCover([
        'controller' => CoverController::class,
        'cache_key' => 'cover',
        'cache_expires_after' => 3600,
    ])
    ->setTableOfContents([
        'path' => '/var/www/html/table_of_contents.xml',
        'cache_key' => 'toc',
    ])
    ->setHeader([
        'template' => 'pdf/header.html.twig',
        'cache_key' => 'header',
    ])
    ->setFooter([
        'template' => 'pdf/footer.html.twig',
        'cache_key' => 'footer',
    ])
    ->setContent([
        'url' => 'http://endroid.nl/',
        'cache_key' => 'content',
    ])
    ->setOptions([
        'margin-top' => 16,
        'margin-bottom' => 16,
        'header-spacing' => 5,
        'footer-spacing' => 5,
    ])
;

$pdf = $pdfBuilder->getPdf();

// Create a response object
$response = InlinePdfResponse::createFromPdf($pdf);

// Or output directly
header('Content-type: application/pdf');
echo $pdf->generate();

Installation

Use Composer to install the library.

$ composer require endroid/pdf

Symfony

When you use Symfony, the installer makes sure that services are automatically wired. If the Snappy\Pdf service is not registered yet, make sure you create a service definition for it or install the knplabs/snappy-bundle along with the library.

$ composer require endroid/pdf knplabs/knp-snappy-bundle

Also, if any of the asset types is unsupported (for instance because you have no cache component or Twig available) or if you simply don't want some to be registered you can uncomment the adapter via the service configuration.

Bootstrapping the PDF builder

When no autowiring is available you need to instantiate and wire the necessary dependencies yourself. You can do so via a bootstrap file for instance.

$snappy = new Snappy(__DIR__.'/../vendor/h4cc/wkhtmltopdf-amd64/bin/wkhtmltopdf-amd64');

$assetFactory = new AssetFactory();
$assetFactory->add(new DataAssetFactoryAdapter());
$assetFactory->add(new ControllerAssetFactoryAdapter($kernel, $requestStack));
$assetFactory->add(new TemplateAssetFactoryAdapter($twig));
...

$pdfBuilder = new PdfBuilder(new Pdf($snappy), $assetFactory);

Versioning

Version numbers follow the MAJOR.MINOR.PATCH scheme. Backwards compatible changes will be kept to a minimum but be aware that these can occur. Lock your dependencies for production and test your code when upgrading.

License

This bundle is under the MIT license. For the full copyright and license information please view the LICENSE file that was distributed with this source code.

endroid / pdf

Maintainers

Details