knplabs/knp-snappy-bundle

Easily create PDF and images in Symfony by converting Twig/HTML templates.

v1.10.2 2024-06-10 12:38 UTC

Requires

• php: >=8.1
• knplabs/knp-snappy: ^1.4.3
• symfony/framework-bundle: ^5.1|^6.0|^7.0

Requires (Dev)

• phpunit/phpunit: ^8.5
• symfony/yaml: ^5.1|^6.0|^7.0

MIT

• KnpLabs Team
• Symfony Community

• knp
• knplabs
• bundle
• snappy
• pdf

README

Snappy is a PHP wrapper for the wkhtmltopdf conversion utility. It allows you to generate either pdf or image files from your html documents, using the webkit engine.

The KnpSnappyBundle provides a simple integration for your Symfony project.

Limitations

If you use JavaScript to render your pages, you may encounter some issues because of wkhtmltopdf not being fully compatible with ES6 apis. The only way to solve this issue is to provide polyfills that fix the gaps between modern ES6 apis and the wkhtmltopdf rendering engine.

Installation

With composer, require:

composer require knplabs/knp-snappy-bundle

If you are not using Flex, enable it in your kernel :

// config/bundles.php
<?php

return [
    //...
    Knp\Bundle\SnappyBundle\KnpSnappyBundle::class => ['all' => true],
    //...
];

Configuration

If you need to change the binaries, change the instance options or even disable one or both services, you can do it through the configuration.

# config/packages/knp_snappy.yaml
knp_snappy:
    pdf:
        enabled:    true
        binary:     /usr/local/bin/wkhtmltopdf #"\"C:\\Program Files\\wkhtmltopdf\\bin\\wkhtmltopdf.exe\"" for Windows users
        options:    []
    image:
        enabled:    true
        binary:     /usr/local/bin/wkhtmltoimage #"\"C:\\Program Files\\wkhtmltopdf\\bin\\wkhtmltoimage.exe\"" for Windows users
        options:    []

If you want to change temporary folder which is sys_get_temp_dir() by default, you can use

# config/packages/knp_snappy.yaml
knp_snappy:
    temporary_folder: "%kernel.cache_dir%/snappy"

You can also configure the timeout used by the generators with process_timeout:

# config/packages/knp_snappy.yaml
knp_snappy:
    process_timeout: 20 # In seconds

Usage

The bundle registers two services:

• the knp_snappy.image service allows you to generate images;
• the knp_snappy.pdf service allows you to generate pdf files.

Generate an image from a URL

// @var Knp\Snappy\Image
$knpSnappyImage->generate('http://www.google.fr', '/path/to/the/image.jpg');

Generate a pdf document from a URL

// @var Knp\Snappy\Pdf
$knpSnappyPdf->generate('http://www.google.fr', '/path/to/the/file.pdf');

Generate a pdf document from multiple URLs

// @var Knp\Snappy\Pdf
$knpSnappyPdf->generate(array('http://www.google.fr', 'http://www.knplabs.com', 'http://www.google.com'), '/path/to/the/file.pdf');

Generate a pdf document from a twig view

// @var Knp\Snappy\Pdf
$knpSnappyPdf->generateFromHtml(
    $this->renderView(
        'MyBundle:Foo:bar.html.twig',
        array(
            'some'  => $vars
        )
    ),
    '/path/to/the/file.pdf'
);

Render an image as response from a controller

use Knp\Bundle\SnappyBundle\Snappy\Response\JpegResponse;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class SomeController extends AbstractController
{
    public function imageAction(Knp\Snappy\Image $knpSnappyImage)
    {
        $html = $this->renderView('MyBundle:Foo:bar.html.twig', array(
            'some'  => $vars
        ));

        return new JpegResponse(
            $knpSnappyImage->getOutputFromHtml($html),
            'image.jpg'
        );
    }
}

Render a pdf document as response from a controller

use Knp\Bundle\SnappyBundle\Snappy\Response\PdfResponse;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class SomeController extends AbstractController
{
    public function pdfAction(Knp\Snappy\Pdf $knpSnappyPdf)
    {
        $html = $this->renderView('MyBundle:Foo:bar.html.twig', array(
            'some'  => $vars
        ));

        return new PdfResponse(
            $knpSnappyPdf->getOutputFromHtml($html),
            'file.pdf'
        );
    }
}

Render a pdf document with a relative url inside like css files

use Knp\Bundle\SnappyBundle\Snappy\Response\PdfResponse;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class SomeController extends AbstractController
{
    public function pdfAction(Knp\Snappy\Pdf $knpSnappyPdf)
    {
        $pageUrl = $this->generateUrl('homepage', array(), true); // use absolute path!

        return new PdfResponse(
            $knpSnappyPdf->getOutput($pageUrl),
            'file.pdf'
        );
    }
}

Maintainers

KNPLabs is looking for maintainers (see why).

If you are interested, feel free to open a PR to ask to be added as a maintainer.

We’ll be glad to hear from you :)

Credits

SnappyBundle and Snappy are based on the awesome wkhtmltopdf. SnappyBundle has been developed by KnpLabs.