KnpSnappyBundle

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

Then enable it in your kernel (optional if you are using the Flex recipe with Symfony >= 4) :

// 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.

# app/config/config.yml (or config/packages/knp_snappy.yaml if using Symfony4 and the Flex recipe)
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

# app/config/config.yml (or config/packages/knp_snappy.yaml if using Symfony4 and the Flex recipe)
knp_snappy:
    temporary_folder: "%kernel.cache_dir%/snappy"

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

# app/config/config.yml (or config/packages/knp_snappy.yaml if using Symfony4 and the Flex recipe)
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.

KnpLabs/KnpSnappyBundle

KnpLabs

Reviews

Repository Details