Git Product home page Git Product logo

cakepdf's Introduction

CakePdf plugin

Build Status Total Downloads License

Plugin containing CakePdf lib which will use a PDF engine to convert HTML to PDF.

Current engines:

  • DomPdf
  • Mpdf
  • Tcpdf
  • WkHtmlToPdf RECOMMENDED ENGINE

Requirements

Installation

Using Composer:

composer require friendsofcake/cakepdf

CakePdf does not include any of the supported PDF engines, you need to install the ones you intend to use yourself. The recommend wkhtmltopdf engine can be downloaded from http://wkhtmltopdf.org/, by default CakePdf expects the wkhtmltopdf binary to be located in /usr/bin/wkhtmltopdf. If you are using wkhtmltopdf in Windows, remove any spaces in the path name. For example use C:/Progra~1/wkhtmltopdf/bin/wkhtmltopdf.exe

DomPdf, Mpdf and Tcpdf can be installed via composer using on of the following commands:

composer require dompdf/dompdf
composer require tecnickcom/tcpdf
composer require mpdf/mpdf

Setup

In config/bootstrap.php add:

Plugin::load('CakePdf', ['bootstrap' => true]);

or using CakePHP's console:

./bin/cake plugin load CakePdf -b

If you plan to use the PDF view functionality that automatically renders and returns the PDF for sending it to the browser, you should also register the pdf extension in your config/routes.php file, either globally before the routes that should be affected:

Router::extensions(['pdf']);

or for a specific route scope:

Router::scope('/', function (\Cake\Routing\RouteBuilder $routes) {
    $routes->addExtensions(['pdf']);
    // ...
});

Further setup information can be found in the usage section.

Configuration

Use Configure::write('CakePdf', $config); or set Controller property $pdfConfig (only when used with PdfView). You need to define at least $config['engine']. When using CakePdf directly you can also pass the config array to constructor. The value for engine should have the Plugin.ClassName format without the Engine suffix.

Configuration options:

  • engine: Engine to be used (required), or an array of engine config options
    • className: Engine class to use
    • binary: Binary file to use (Only for wkhtmltopdf)
    • cwd: current working directory (Only for wkhtmltopdf)
    • options: Engine specific options. Currently only for WkHtmlToPdf, where the options are passed as CLI arguments, and for DomPdf, where the options are passed to the DomPdf class constructor.
  • crypto: Crypto engine to be used, or an array of crypto config options
    • className: Crypto class to use
    • binary: Binary file to use
  • pageSize: Change the default size, defaults to A4
  • orientation: Change the default orientation, defaults to potrait
  • margin: Array or margins with the keys: bottom, left, right, top and their values
  • title: Title of the document
  • delay: A delay in milliseconds to wait before rendering the pdf
  • windowStatus: The required window status before rendering the pdf
  • encoding: Change the encoding, defaults to UTF-8
  • download: Set to true to force a download, only when using PdfView
  • filename: Filename for the document when using forced download

Example:

<?php
    Configure::write('CakePdf', [
        'engine' => 'CakePdf.WkHtmlToPdf',
        'margin' => [
            'bottom' => 15,
            'left' => 50,
            'right' => 30,
            'top' => 45
        ],
        'orientation' => 'landscape',
        'download' => true
    ]);
?>

<?php
    class InvoicesController extends AppController
    {
        // In your Invoices controller you could set additional configs,
        // or override the global ones:
        public function view($id = null)
        {
            $invoice = $this->Invoice->get($id);
            $this->viewBuilder()->options([
                'pdfConfig' => [
                    'orientation' => 'portrait',
                    'filename' => 'Invoice_' . $id
                ]
            ]);
            $this->set('invoice', $invoice);
        }
    }
?>

The engine and crypto config options can also be arrays with configuration options for the relevant class. For example:

    Configure::write('CakePdf', [
        'engine' => [
            'className' => 'CakePdf.WkHtmlToPdf',
            // Mac OS X / Linux is usually like:
            'binary' => '/usr/local/bin/wkhtmltopdf',
            // On Windows environmnent you NEED to use the path like
            // old fashioned MS-DOS Paths, otherwise you will keep getting:
            // WKHTMLTOPDF didn't return any data
            // 'binary' => 'C:\\Progra~1\\wkhtmltopdf\\bin\\wkhtmltopdf.exe',
            // 'cwd' => 'C:\\Progra~1\\wkhtmltopdf\\bin',
	        'options' => [
	            'print-media-type' => false,
	            'outline' => true,
	            'dpi' => 96
	        ],
        ],
    ]);

Usage

You can use CakePdf in two ways, read carefully which one you actually need. Many people mix both ways and don't get the expected results.

1: Render as PDF (including forced download) in the browser with PdfView

You can create PDF view and layout files for your controller actions and have them automatically rendered. Place the view templates in a 'pdf' subdir, for instance src/Template/Invoices/pdf/view.ctp, layouts will be in src/Template/Layout/pdf/default.ctp.

Make sure your InvoicesController class loads the RequestHandler component and browse to http://localhost/invoices/view/1.pdf

Additionally you can map resources by adding Router::mapResources(['Invoices']); to your routes file and you can access the same document at http://localhost/invoices/1.pdf.

In case you don't want to use the pdf extension in your URLs, you can omit registering it in your routes configuration. Then in your controller action call RequestHandler::render() to switch the view class and template paths.

$this->RequestHandler->renderAs($this, 'pdf', ['attachment' => 'filename.pdf']);

2: Create PDF for email attachment, file storage etc.

You can use CakePdf lib to create raw PDF data with a view template. The view file path would look like src/Template/Pdf/newsletter.ctp. Layout file path would be like src/Template/Layout/pdf/default.ctp Note that layouts for both usage types are within same directory, but the view templates use different file paths Optionally you can also write the raw data to file.

Example:

<?php
    $CakePdf = new \CakePdf\Pdf\CakePdf();
    $CakePdf->template('newsletter', 'default');
    $CakePdf->viewVars($this->viewVars);
    // Get the PDF string returned
    $pdf = $CakePdf->output();
    // Or write it to file directly
    $pdf = $CakePdf->write(APP . 'files' . DS . 'newsletter.pdf');

Encryption

You can optionally encrypt the PDF with permissions

To use encryption you first need to select a crypto engine. Currently we support the following crypto engines:

  • Pdftk

Usage

Add the following in your bootstrap.

Configure::write('CakePdf.crypto', 'CakePdf.Pdftk');

Options in pdfConfig:

  • protect: Set to true to enable encryption
  • userPassword (optional): Set a password to open the PDF file
  • ownerPassword (optional): Set the password to unlock the locked permissions
  • one of the above must be present, either userPassword or ownerPassword
  • permissions (optional): Define the permissions

Permissions:

By default, we deny all permissions.

To allow all permissions:

Set 'permission' to true

To allow specific permissions:

Set 'permissions' to an array with a combination of the following available permissions:

  • print
  • degraded_print
  • modify,
  • assembly,
  • copy_contents,
  • screen_readers,
  • annotate,
  • fill_in

Note about static assets

Use absolute URLs for static assets in your view templates for PDFs. If you use HtmlHelper::image(), HtmlHelper::script() or HtmlHelper::css() make sure you have $options['_full'] = true.

For example

echo $this->Html->script('jquery/jquery.js', ['fullBase' => true]);
echo $this->Html->css('bootstrap/bootstrap.css', ['fullBase' => true]);

Thanks

Many thanks to Kim Biesbjerg and Jelle Henkens for their contributions. Want your name here as well? Create a pull request for improvements/other PDF engines.

cakepdf's People

Contributors

admad avatar bar avatar birdy247 avatar bostjanpisler avatar carusogabriel avatar ceeram avatar chipco avatar dakota avatar darensipes avatar dereuromark avatar havokinspiration avatar iamthom avatar icaroscherma avatar josegonzalez avatar jszoja avatar lamasgergo avatar lorenzo avatar marlinc avatar p-try avatar rafaelios avatar ravage84 avatar renan avatar spriz avatar stmeyer avatar tenebrousedge avatar uzyn avatar vtek21 avatar waspinator avatar yomexzo avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.