Demo URL: https://october-demo.renatio.com/backend/backend/auth/signin
Login: dynamicpdf
Password: dynamicpdf
This plugin allows developers to create and edit PDF templates with a simple user interface.
HTML to PDF converter uses dompdf library.
Plugin uses dompdf wrapper for Laravel barryvdh/laravel-dompdf.
If you like this plugin, give this plugin a Like or Make donation with PayPal.
Please check my other plugins.
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.
Icon made by Darius Dan from www.flaticon.com.
There are couple ways to install this plugin.
- Use
php artisan plugin:install Renatio.DynamicPDFcommand. - Use
composer require renatio/dynamicpdf-pluginin project root. When you use this option you must runphp artisan october:migrateafter installation.
PDF can be created in October using either PDF views or PDF templates. A PDF view is supplied by plugin in the file system in the /views directory. Whereas a PDF template is managed using the back-end interface via Settings > PDF > PDF Templates. All PDFs templates support using Twig for markup.
PDF views must be registered in the Plugin registration file with the registerPDFTemplates and registerPDFLayouts
method. This will automatically generate a PDF template and layout and allows them to be customized using the back-end
interface.
PDF layouts views reside in the file system and the code used represents the path to the view file. For example PDF layout with the code author.plugin::pdf.layouts.default would use the content in following file:
plugins/ <=== Plugins directory
author/ <=== "author" segment
plugin/ <=== "plugin" segment
views/ <=== View directory
pdf/ <=== "pdf" segment
layouts/ <=== "layouts" segment
default.htm <=== "default" segment
The content inside a PDF view file can include up to 3 sections: configuration, CSS/LESS, and HTML markup.
Sections are separated with the == sequence. For example:
name = "Default PDF layout"
==
body {
font-size: 16px;
}
==
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Document</title>
<style type="text/css" media="screen">
{{ css|raw }}
</style>
</head>
<body>
{{ content_html|raw }}
</body>
</html>
Note: Basic Twig tags and expressions are supported in PDF views.
The CSS/LESS section is optional and a view can contain only the configuration and HTML markup sections.
name = "Default PDF layout"
==
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Document</title>
<style type="text/css" media="screen">
{{ css|raw }}
</style>
</head>
<body>
{{ content_html|raw }}
</body>
</html>
The configuration section sets the PDF view parameters. The following configuration parameters are supported:
| Parameter | Description |
|---|---|
| name | the layout name, required. |
PDF layouts reside in the database and can be created by selecting Settings > PDF > PDF Templates and clicking the * Layouts* tab. These behave just like CMS layouts, they contain the scaffold for the PDF. PDF views and templates support the use of PDF layouts. The code specified in the layout is a unique identifier and cannot be changed once created.
PDF templates reside in the file system and the code used represents the path to the view file. For example PDF template with the code author.plugin::pdf.invoice would use the content in following file:
plugins/ <=== Plugins directory
author/ <=== "author" segment
plugin/ <=== "plugin" segment
views/ <=== View directory
pdf/ <=== "pdf" segment
invoice.htm <=== "invoice" segment
The content inside a PDF view file can include up to 2 sections: configuration and HTML markup. Sections are
separated with the == sequence. For example:
title = "Invoice"
layout = "renatio.demo::pdf.layouts.default"
description = "Invoice template"
size = "a4"
orientation = "portrait"
==
<h1>Invoice</h1>
Note: Basic Twig tags and expressions are supported in PDF views.
The configuration section sets the PDF view parameters. The following configuration parameters are supported:
| Parameter | Description |
|---|---|
| title | the template title, required. |
| layout | the layout code, optional. |
| description | the template description, optional. |
| size | the template paper size, optional, default a4. |
| orientation | the template paper orientation, optional, default portrait. |
PDF templates reside in the database and can be created in the back-end area via Settings > PDF > PDF Templates. The code specified in the template is a unique identifier and cannot be changed once created.
Note: If the PDF template does not exist in the system, this code will attempt to find a PDF view with the same code.
PDF views can be registered as templates that are automatically generated in the back-end ready for customization. PDF
templates can be customized via the Settings > PDF Templates menu. The templates can be registered by adding
the registerPDFTemplates method of the Plugin registration class (Plugin.php).
public function registerPDFTemplates()
{
return [
'renatio.demo::pdf.invoice',
'renatio.demo::pdf.resume',
];
}
The method should return an array of pdf view names.
Like templates, PDF layouts can be registered by adding the registerPDFLayouts method of the Plugin registration
class (Plugin.php).
public function registerPDFLayouts()
{
return [
'renatio.demo::pdf.layouts.invoice',
'renatio.demo::pdf.layouts.resume',
];
}
The method should return an array of pdf view names.
PDF templates and layouts can be accessed in the back-end area via Settings > PDF > PDF 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/LESS content. Not all CSS properties are supported, so check CSSCompatibility.
Templates define the actual PDF content parsed from HTML.
The default 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 dynamic methods for all options like so:
PDF::loadTemplate('renatio::invoice')
->setDpi(300)
->setDefaultFont('sans-serif')
->stream();
or you can use setOption method before generating the pdf using this command:
PDF::loadTemplate('renatio::invoice')
->setOption(['dpi' => 300, '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"
See Dompdf\Options for a list of available options.
| 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.
To display background image added in layout use following code:
<body style="background: url({{ background_img }}) top left no-repeat;">
Background image should be at least 96 DPI size (793 x 1121 px).
If you want to use better quality image like 300 DPI (2480 x 3508 px) than you need to change template options like so:
return PDF::loadTemplate($model->code)
->setDpi(300)
->stream();
In your layout, set the UTF-8 meta tag in head section:
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
If you have problems with foreign characters than try to use DejaVu Sans font family.
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>
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')
->setLogOutputFile(storage_path('temp/log.htm'))
->stream();
You can use absolute path for image eg. https://app.dev/path_to_your_image.
For this to work you must set isRemoteEnabled option.
return PDF::loadTemplate('renatio::invoice', ['file' => $file])
->setIsRemoteEnabled(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.
OctoberCMS ajax framework cannot handle this type of response.
Recommended approach is to save PDF file locally and return redirect to PDF file.
Page numbers can be generated using PHP. Inline PHP is disabled by default, because it can be a security risk. You can
enable inline PHP using setIsPhpEnabled method.
return PDF::loadTemplate('renatio::invoice')
->setIsRemoteEnabled(true)
->setIsPhpEnabled(true)
->stream();
After that you must place following code before closing </body> tag of the layout file.
<script type="text/php">
if (isset($pdf)) {
$size = 9;
$color = [0,0,0];
$font = $fontMetrics->getFont('Open Sans');
$textHeight = $fontMetrics->getFontHeight($font, $size);
$width = $fontMetrics->getTextWidth('Page 1 of 2', $font, $size);
$foot = $pdf->open_object();
$w = $pdf->get_width();
$h = $pdf->get_height();
$y = $h - $textHeight - 13;
$pdf->close_object();
$pdf->add_object($foot, 'all');
$text = "Page {PAGE_NUM} of {PAGE_COUNT}";
// Center the text
$pdf->page_text($w / 2 - $width / 2, $y, $text, $font, $size, $color);
}
</script>
There is a console command that will enable demo templates and layouts.
php artisan dynamicpdf:demo
To disable demo run following command:
php artisan dynamicpdf:demo --disable
The first example shows invoice with custom font and image embed.
The second example shows usage of header & footer, page break, page numbers and full background image.
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.
use Renatio\DynamicPDF\Classes\PDF;
public function pdf()
{
return PDF::loadTemplate('renatio::invoice')->download('download.pdf');
}
You can chain the methods:
return PDF::loadTemplate('renatio::invoice')
->save('/path-to/my_stored_file.pdf')
->stream();
return PDF::loadTemplate('renatio::invoice')
->setPaper('a4', 'landscape')
->stream();
Available paper sizes.
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();
}
<html>
<head>
<style>
@page { margin: 100px 25px; }
header { position: fixed; top: -60px; left: 0px; right: 0px; background-color: lightblue; height: 50px; }
footer { position: fixed; bottom: -60px; left: 0px; right: 0px; background-color: lightblue; height: 50px; }
p { page-break-after: always; }
p:last-child { page-break-after: never; }
</style>
</head>
<body>
<header>header on each page</header>
<footer>footer on each page</footer>
<main>
<p>page1</p>
<p>page2</p>
</main>
</body>
</html>
Plugin provides "Open Sans" font, which can be imported in Layout CSS section.
@font-face {
font-family: 'Open Sans';
src: url({{ 'plugins/renatio/dynamicpdf/assets/fonts/OpenSans-Regular.ttf'|app }});
}
@font-face {
font-family: 'Open Sans';
font-weight: bold;
src: url({{ 'plugins/renatio/dynamicpdf/assets/fonts/OpenSans-Bold.ttf'|app }});
}
@font-face {
font-family: 'Open Sans';
font-style: italic;
src: url({{ 'plugins/renatio/dynamicpdf/assets/fonts/OpenSans-Italic.ttf'|app }});
}
@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: bold;
src: url({{ 'plugins/renatio/dynamicpdf/assets/fonts/OpenSans-BoldItalic.ttf'|app }});
}
body {
font-family: 'Open Sans', sans-serif;
font-size: 16px;
}