Developed with love by KnpLabs Hire us for your project!
984

KnpSnappyBundle

by KnpLabs

Easily create PDF and images in Symfony by converting html using webkit

KnpSnappyBundle

Build Status
Scrutinizer Code Quality
StyleCI
knpbundles.com

Snappy is a PHP (5.6+) 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.

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 Symfony4) :

// app/AppKernel.php
public function registerBundles()
{
    $bundles = array(
        //...
        new Knp\Bundle\SnappyBundle\KnpSnappyBundle(),
        //...

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

$container->get('knp_snappy.image')->generate('http://www.google.fr', '/path/to/the/image.jpg');

Generate a pdf document from a URL

$container->get('knp_snappy.pdf')->generate('http://www.google.fr', '/path/to/the/file.pdf');

Generate a pdf document from multiple URLs

$container->get('knp_snappy.pdf')->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

$this->get('knp_snappy.pdf')->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;

class SomeController
{
    public function imageAction()
    {
        $html = $this->renderView('MyBundle:Foo:bar.html.twig', array(
            'some'  => $vars
        ));

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

Render a pdf document as response from a controller

use Knp\Bundle\SnappyBundle\Snappy\Response\PdfResponse;

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

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

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

use Knp\Bundle\SnappyBundle\Snappy\Response\PdfResponse;

class SomeController extends Controller
{
    public function pdfAction()
    {
        $pageUrl = $this->generateUrl('homepage', array(), true); // use absolute path!

        return new PdfResponse(
            $this->get('knp_snappy.pdf')->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.

Copyright (c) 2010 Knp Labs

The MIT license

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
knp_snappy:
temporary_folder: ~

# Generator process timeout in seconds.
process_timeout: ~
pdf:
enabled: true
binary: wkhtmltopdf
options:

# Prototype
name: []
env: []
image:
enabled: true
binary: wkhtmltoimage
options:

# Prototype
name: []
env: []
  • Merge pull request #255 from KnpLabs/update-phpunit
    By web-flow, 1 year ago
  • updating to use phpunit-bridge and updating travis config
    By weaverryan, 1 year ago
  • Merge pull request #252 from zairigimad/symfony5
    By web-flow, 1 year ago
  • only support supported Symfony versions
    By web-flow, 1 year ago
  • tweaking now that 5.0 is compat
    By web-flow, 1 year ago
  • add symfony 5 compatibility
    By , 1 year ago
  • Merge pull request #248 from alexpozzi/doc/maintainers
    By web-flow, 1 year ago
  • Explicitly add maintainers in the README
    By alexpozzi, 1 year ago
  • Merge pull request #236 from Einenlum/update/doc
    By web-flow, 1 year ago
  • Update documentation for Sf4
    By Einenlum, 1 year ago
  • Merge pull request #231 from NiR-/update-changelog
    By web-flow, 2 years ago
  • Add a note about v1.6.0 in the changelog
    By akerouanton, 2 years ago
  • Add a note about v1.5.2 in the changelog
    By akerouanton, 2 years ago
  • Merge pull request #229 from antograssiot/patch-1
    By web-flow, 2 years ago
  • Avoid deprecation warning when using symfony/config > 4.2
    By antograssiot, 2 years ago
  • Merge pull request #230 from NiR-/drop-unsupported-php-versions
    By web-flow, 2 years ago
  • Explicitly configure Travis to use its VM-based builds
    By akerouanton, 2 years ago
  • Upgrade phpunit to v7.4
    By akerouanton, 2 years ago
  • Remove symfony/translation from dev dependencies
    By akerouanton, 2 years ago
  • Fix test suite
    By akerouanton, 2 years ago
  • Drop unsupported PHP versions
    By akerouanton, 2 years ago
  • Merge pull request #208 from Laurent3170/patch-3
    By web-flow, 2 years ago
  • Merge pull request #226 from garthlord/master
    By web-flow, 2 years ago
  • Corrected typo in README example "Render a pdf document with a relative url inside like css files"
    By Goran Čeko, 2 years ago
  • Update link for Composer
    By web-flow, 2 years ago
  • Merge pull request #191 from carusogabriel/phpunit
    By web-flow, 3 years ago
  • Merge pull request #185 from NiR-/fix-bc-break
    By web-flow, 3 years ago
  • Merge pull request #194 from webworksnbg/master
    By web-flow, 3 years ago
  • Deprecation on config example
    By web-flow, 3 years ago
  • Use PHPUnit\Framework\TestCase instead of PHPUnit_Framework_TestCase
    By carusogabriel, 3 years ago