Dynamic PDF plugin

October HTML to PDF converter using dompdf library.

Plugin uses dompdf wrapper for Laravel barryvdh/laravel-dompdf.

Features

• Handles most CSS 2.1 and a few CSS3 properties, including @import, @media & @page rules
• Supports most presentational HTML 4.0 attributes
• Supports external stylesheets, either local or through http/ftp (via fopen-wrappers)
• Supports complex tables, including row & column spans, separate & collapsed border models, individual cell styling
• Image support (gif, png (8, 24 and 32 bit with alpha channel), bmp & jpeg)
• No dependencies on external PDF libraries, thanks to the R&OS PDF class
• Inline PHP support
• Basic SVG support

Installation

There are couple ways to install this plugin.

1. Use October Marketplace and Add to project button.
2. Use October backend area Settings > System > Updates & Plugins > Install Plugins and type Renatio.DynamicPDF.
3. Use php artisan plugin:install Renatio.DynamicPDF command.
4. Use composer require renatio/dynamicpdf-plugin in project root. When you use this option you must run php artisan october:up after installation.

Fourth option should be used only for advanced users.

Using

Plugin will register menu item called PDF, which allow you to manage PDF layouts and templates.

Layouts define the PDF scaffold, that is everything that repeats on a PDF, such as a header and footer. Each layout has unique code, optional background image, HTML content and CSS content. Not all CSS properties are supported, so check CSSCompatibility.

Templates define the actual PDF content parsed from HTML. The code specified in the template is a unique identifier and cannot be changed once created.

You can use Twig in layouts and templates.

Plugin supports using CMS partials and filters inside template and layout markup.

Configuration

The defaults configuration settings are set in config/dompdf.php. Copy this file to your own config directory to modify the values. You can publish the config using this command:

php artisan vendor:publish --provider="Barryvdh\DomPDF\ServiceProvider"

You can still alter the dompdf options in your code before generating the PDF using this command:

PDF::loadTemplate('renatio::invoice')
    ->setOptions(['dpi' => 150, 'defaultFont' => 'sans-serif'])
    ->stream();

Available options and their defaults:

• rootDir: "{app_directory}/vendor/dompdf/dompdf"
• tempDir: "/tmp" (available in config/dompdf.php)
• fontDir: "{app_directory}/storage/fonts/" (available in config/dompdf.php)
• fontCache: "{app_directory}/storage/fonts/" (available in config/dompdf.php)
• chroot: "{app_directory}" (available in config/dompdf.php)
• logOutputFile: "/tmp/log.htm"
• defaultMediaType: "screen" (available in config/dompdf.php)
• defaultPaperSize: "a4" (available in config/dompdf.php)
• defaultFont: "serif" (available in config/dompdf.php)
• dpi: 96 (available in config/dompdf.php)
• fontHeightRatio: 1.1 (available in config/dompdf.php)
• isPhpEnabled: false (available in config/dompdf.php)
• isRemoteEnabled: true (available in config/dompdf.php)
• isJavascriptEnabled: true (available in config/dompdf.php)
• isHtml5ParserEnabled: false (available in config/dompdf.php)
• isFontSubsettingEnabled: false (available in config/dompdf.php)
• debugPng: false
• debugKeepTemp: false
• debugCss: false
• debugLayout: false
• debugLayoutLines: true
• debugLayoutBlocks: true
• debugLayoutInline: true
• debugLayoutPaddingBox: true
• pdfBackend: "CPDF" (available in config/dompdf.php)
• pdflibLicense: ""
• adminUsername: "user"
• adminPassword: "password"

Methods

| Method | Description | |---|---| | loadTemplate($code, array $data = [], $encoding = null) | Load backend template | | loadLayout($code, array $data = [], $encoding = null) | Load backend layout | | loadHTML($string, $encoding = null) | Load HTML string | | loadFile($file) | Load HTML string from a file | | parseTemplate(Template $template, array $data = []) | Parse backend template using Twig | | parseLayout(Layout $layout, array $mergeData = []) | Parse backend layout using Twig | | getDomPDF() | Get the DomPDF instance | | setPaper($paper, $orientation = 'portrait') | Set the paper size and orientation (default A4/portrait) | | setWarnings($warnings) | Show or hide warnings | | output() | Output the PDF as a string | | save($filename) | Save the PDF to a file | | download($filename = 'document.pdf') | Make the PDF downloadable by the user | | stream($filename = 'document.pdf') | Return a response with the PDF to show in the browser |

All methods are available through Facade class Renatio\DynamicPDF\Classes\PDF.

Tip: Background image

To display background image added in layout use following code:

<body style="background: url({{ background_img }}) top left no-repeat;">

Background image should be 96 DPI size (793 x 1121 px).

Tip: UTF-8 support

In your layout, set the UTF-8 meta tag in head section:

<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

Tip: Page breaks

You can use the CSS page-break-before/page-break-after properties to create a new page.

<style>
.page-break {
    page-break-after: always;
}
</style>
<h1>Page 1</h1>
<div class="page-break"></div>
<h1>Page 2</h1>

Tip: Open_basedir restriction error

On some hosting providers there were reports about open_basedir restriction problems with log file. You can change default log file destination like so:

return PDF::loadTemplate('renatio::invoice')
    ->setOptions(['logOutputFile' => storage_path('temp/log.htm')])
    ->stream();

Tip: Embed image inside PDF template

You can use absolute path for image eg. http://app.dev/path_to_your_image.

For this to work you must set isRemoteEnabled option.

return PDF::loadTemplate('renatio::invoice', ['file' => $file])
    ->setOptions(['isRemoteEnabled' => true])
    ->stream();

I assume that $file is instance of October\Rain\Database\Attach\File.

Then in the template you can use following example code:

{{ file.getPath }}

{{ file.getLocalPath }}

{{ file.getThumb(200, 200, {'crop' => true}) }}

For retrieving stylesheets or images via http following PHP setting must be enabled allow_url_fopen.

When allow_url_fopen is disabled on server try to use relative path. You can use October getLocalPath function on the file object to retrieve it.

Tip: Download PDF via Ajax response

OctoberCMS ajax framework cannot handle this type of response.

Recommended approach is to save PDF file locally and return redirect to PDF file.

Examples

After installation there will an example PDF invoice document, which will show, how you can structure HTML and CSS.

Render PDF in browser

use Renatio\DynamicPDF\Classes\PDF; // import facade

...

public function pdf()
{
    $templateCode = 'renatio::invoice'; // unique code of the template
    $data = ['name' => 'John Doe']; // optional data used in template

    return PDF::loadTemplate($templateCode, $data)->stream('download.pdf');
}

Where $templateCode is an unique code specified when creating the template, $data is optional array of twig fields which will be replaced in template.

In HTML template you can use {{ name }} to output John Doe.

Download PDF

use Renatio\DynamicPDF\Classes\PDF;

...

public function pdf()
{
    return PDF::loadTemplate('renatio::invoice')->download('download.pdf');
}

Fluent interface

You can chain the methods:

return PDF::loadTemplate('renatio::invoice')
    ->save('/path-to/my_stored_file.pdf')
    ->stream();

Change orientation and paper size

return PDF::loadTemplate('renatio::invoice')
    ->setPaper('a4', 'landscape')
    ->stream();

Available paper sizes.

PDF on CMS page

To display PDF on CMS page you can use PHP section of the page like so:

use Renatio\DynamicPDF\Classes\PDF;

function onStart()
{
    return PDF::loadTemplate('renatio::invoice')->stream();
}

Support

Please use GitHub Issues Page to report any issues with plugin.

Reviews should not be used for getting support or reporting bugs, if you need support please use the Plugin support link.

Like this plugin?

If you like this plugin, give this plugin a Like or Make donation with PayPal.