{"id":13684462,"url":"https://github.com/FriendsOfCake/CakePdf","last_synced_at":"2025-04-30T21:30:28.626Z","repository":{"id":46752694,"uuid":"4264971","full_name":"FriendsOfCake/CakePdf","owner":"FriendsOfCake","description":"CakePHP plugin for creating and/or rendering PDFs, supporting several popular PDF engines.","archived":false,"fork":false,"pushed_at":"2025-01-30T04:09:45.000Z","size":24587,"stargazers_count":375,"open_issues_count":6,"forks_count":183,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-04-12T20:43:21.829Z","etag":null,"topics":["cakephp","cakephp-plugin","pdf","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FriendsOfCake.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-05-08T20:09:05.000Z","updated_at":"2025-02-25T22:39:56.000Z","dependencies_parsed_at":"2025-02-07T19:00:26.733Z","dependency_job_id":null,"html_url":"https://github.com/FriendsOfCake/CakePdf","commit_stats":{"total_commits":352,"total_committers":49,"mean_commits":7.183673469387755,"dds":0.71875,"last_synced_commit":"d96f0a16e0f070071de1278857f00c02aae00973"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FriendsOfCake%2FCakePdf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FriendsOfCake%2FCakePdf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FriendsOfCake%2FCakePdf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FriendsOfCake%2FCakePdf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FriendsOfCake","download_url":"https://codeload.github.com/FriendsOfCake/CakePdf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251785318,"owners_count":21643453,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cakephp","cakephp-plugin","pdf","php"],"created_at":"2024-08-02T14:00:33.847Z","updated_at":"2025-04-30T21:30:28.613Z","avatar_url":"https://github.com/FriendsOfCake.png","language":"PHP","readme":"# CakePdf plugin\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/FriendsOfCake/CakePdf/ci.yml?branch=master\u0026style=flat-square)](https://github.com/FriendsOfCake/CakePdf/actions?query=workflow%3ACI+branch%3Amaster)\n[![Total Downloads](https://img.shields.io/packagist/dt/friendsofcake/CakePdf.svg?style=flat-square)](https://packagist.org/packages/friendsofcake/CakePdf)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://packagist.org/packages/friendsofcake/CakePdf)\n\nPlugin containing CakePdf lib which will use a PDF engine to convert HTML to PDF.\n\nEngines included in the plugin:\n* DomPdf (^3.0)\n* Mpdf (^8.0.4)\n* Tcpdf (^6.3)\n* WkHtmlToPdf **RECOMMENDED ENGINE**\n\nCommunity maintained engines:\n* [PDFreactor](https://github.com/jmischer/cake-pdfreactor)\n\n\n## Requirements\n\n* One of the following render engines: DomPdf, Mpdf, Tcpdf or wkhtmltopdf\n* pdftk (optional) See: http://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/\n\n\n## Installation\n\nUsing [Composer](http://getcomposer.org):\n\n```\ncomposer require friendsofcake/cakepdf\n```\n\nCakePdf does not include any of the supported PDF engines, you need to install\nthe ones you intend to use yourself.\n\nPackages for the recommend `wkhtmltopdf` engine can be downloaded from https://wkhtmltopdf.org/downloads.html.\nDomPdf, Mpdf and Tcpdf can be installed via composer using one of the following commands:\n\n```\ncomposer require dompdf/dompdf\ncomposer require tecnickcom/tcpdf\ncomposer require mpdf/mpdf\n```\n\n## Setup\n\nLoading the plugin using CakePHP's console:\n\n```\n./bin/cake plugin load CakePdf\n```\n\nIf you plan to use [the PDF view functionality](#1-render-as-pdf-including-forced-download-in-the-browser-with-pdfview)\nthat automatically renders and returns the PDF for sending it to the browser,\nyou should also register the `pdf` extension in your `config/routes.php` file:\n\n```php\n$routes-\u003escope('/', function (\\Cake\\Routing\\RouteBuilder $routes) {\n    $routes-\u003esetExtensions(['pdf']);\n    // ...\n});\n```\n\nFurther setup information can be found in the usage section.\n\n## Configuration\n\nUse `Configure::write('CakePdf', $config);` or in controller use view builder to\nset view option named `pdfConfig` (only when used with PdfView). You need to\ndefine at least `$config['engine']`. When using CakePdf directly you can also\npass the config array to constructor. The value for engine should have the\n`Plugin.ClassName` format without the Engine suffix.\n\nConfiguration options:\n* engine: Engine to be used (required), or an array of engine config options\n  * className: Engine class to use\n  * binary: Binary file to use (Only for wkhtmltopdf)\n  * cwd: current working directory (Only for wkhtmltopdf)\n  * options: Engine specific options. Currently used for following engine:\n    * `WkHtmlToPdfEngine`: The options are passed as CLI arguments\n    * `TexToPdfEngine`: The options are passed as CLI arguments\n    * `DomPdfEngine`: The options are passed to constructor of `Dompdf` class\n    * `MpdfEngine`: The options are passed to constructor of `Mpdf` class\n* crypto: Crypto engine to be used, or an array of crypto config options\n  * className: Crypto class to use\n  * binary: Binary file to use\n* pageSize: Change the default size, defaults to A4\n* orientation: Change the default orientation, defaults to portrait\n* margin: Array or margins with the keys: bottom, left, right, top and their values\n* title: Title of the document\n* delay: A delay in milliseconds to wait before rendering the pdf\n* windowStatus: The required window status before rendering the pdf\n* encoding: Change the encoding, defaults to UTF-8\n* download: Set to true to force a download, only when using PdfView\n* filename: Filename for the document when using forced download\n\nExample:\n```php\nConfigure::write('CakePdf', [\n    'engine' =\u003e 'CakePdf.WkHtmlToPdf',\n    'margin' =\u003e [\n        'bottom' =\u003e 15,\n        'left' =\u003e 50,\n        'right' =\u003e 30,\n        'top' =\u003e 45,\n    ],\n    'orientation' =\u003e 'landscape',\n    'download' =\u003e true,\n]);\n```\n\n```php\nuse CakePdf\\View\\PdfView;\n\nclass InvoicesController extends AppController\n{\n    public function initialize(): void\n    {\n        parent::initialize();\n\n        // https://book.cakephp.org/5/en/controllers.html#content-type-negotiation\n        $this-\u003eaddViewClasses([PdfView::class]);\n    }\n\n    // In your Invoices controller you could set additional configs,\n    // or override the global ones:\n    public function view($id = null)\n    {\n        $invoice = $this-\u003eInvoice-\u003eget($id);\n        $this-\u003eviewBuilder()-\u003esetOption(\n            'pdfConfig',\n            [\n                'orientation' =\u003e 'portrait',\n                'filename' =\u003e 'Invoice_' . $id,\n            ]\n        );\n        $this-\u003eset('invoice', $invoice);\n    }\n}\n```\n\nThe `engine` and `crypto` config options can also be arrays with configuration\noptions for the relevant class. For example:\n\n```php\nConfigure::write('CakePdf', [\n    'engine' =\u003e [\n        'className' =\u003e 'CakePdf.WkHtmlToPdf',\n        // Options usable depend on the engine used.\n        'options' =\u003e [\n            'print-media-type' =\u003e false,\n            'outline' =\u003e true,\n            'dpi' =\u003e 96,\n            'cover' =\u003e [\n                'url' =\u003e 'cover.html',\n                'enable-smart-shrinking' =\u003e true,\n            ],\n            'toc' =\u003e true,\n        ],\n\n        /**\n         * For Mac OS X / Linux by default the `wkhtmltopdf` binary should\n         * be available through environment path or you can specify location as:\n         */\n        // 'binary' =\u003e '/usr/local/bin/wkhtmltopdf',\n\n        /**\n         * On Windows the engine uses the path shown below as default.\n         * You NEED to use the path like old fashioned MS-DOS Paths,\n         * otherwise you will get error like:\n         * \"WKHTMLTOPDF didn't return any data\"\n         */\n        // 'binary' =\u003e 'C:\\\\Progra~1\\\\wkhtmltopdf\\\\bin\\\\wkhtmltopdf.exe',\n    ],\n]);\n```\n\n## Usage\n\nYou can use CakePdf in two ways, read carefully which one you actually need.\nMany people mix both ways and don't get the expected results.\n\n\n### 1: Render as PDF (including forced download) in the browser with PdfView\n\nYou can create PDF template and layout files for your controller actions and have\nthem automatically rendered. Place the templates in a `pdf` subdir, for\ninstance `templates/Invoices/pdf/view.php`, layouts will be in\n`templates/layout/pdf/default.php`.\n\nThen for e.g. accessing the URL `http://localhost/invoices/view/1.pdf` would\ngive you the generated PDF.\n\nAdditionally you can map resources by adding `Router::mapResources(['Invoices']);`\nto your routes file and you can access the same document at\n`http://localhost/invoices/1.pdf`.\n\nIn case you don't want to use the `pdf` extension in your URLs, you can omit\nregistering it in your routes configuration. You can then set the `Accept`\nrequest header to `application/pdf` to make CakePHP automatically switch to `PdfView`\n(required the `viewClasses()` method to be set as shown above), or explicity switch\nthe view class in your controller action:\n\n```php\n$this-\u003eviewBuilder()-\u003esetClassName('CakePdf.Pdf');\n```\n\nInstead of having the pdf rendered in the browser itself, you can force it to be\ndownloaded by using `download` option. Additionally you can specify custom filename\nusing `filename` options.\n\n```php\n$this-\u003eviewBuilder()-\u003esetOption(\n    'pdfConfig',\n    [\n        'download' =\u003e true, // This can be omitted if \"filename\" is specified.\n        'filename' =\u003e 'Invoice_' . $id, // This can be omitted if you want a file name based on URL.\n    ]\n);\n```\n\n### 2: Create PDF for email attachment, file storage etc.\n\nYou can use CakePdf to create raw PDF data with a view template.\nThe view file path would look like `templates/pdf/newsletter.php`.\nLayout file path would be like `templates/layout/pdf/default.php`\nNote that layouts for both usage types are within same directory, but the view\ntemplates use different file paths Optionally you can also write the raw data to\nfile.\n\nExample:\n```php\n$CakePdf = new \\CakePdf\\Pdf\\CakePdf();\n$CakePdf-\u003etemplate('newsletter', 'default');\n$CakePdf-\u003eviewVars(['key' =\u003e 'value']);\n// Get the PDF string returned\n$pdf = $CakePdf-\u003eoutput();\n// Or write it to file directly\n$pdf = $CakePdf-\u003ewrite(APP . 'files' . DS . 'newsletter.pdf');\n```\n\n\n## Encryption\n\nYou can optionally encrypt the PDF with permissions\n\nTo use encryption you first need to select a crypto engine. Currently we support\nthe following crypto engines:\n* Pdftk\n\n\n### Usage\n\nAdd the following in your bootstrap.\n\n```php\nConfigure::write('CakePdf.crypto', 'CakePdf.Pdftk');\n```\n\nOptions in pdfConfig:\n* protect: Set to true to enable encryption\n* userPassword (optional): Set a password to open the PDF file\n* ownerPassword (optional): Set the password to unlock the locked permissions\n* one of the above must be present, either userPassword or ownerPassword\n* permissions (optional): Define the permissions\n\nPermissions:\n\nBy default, we deny all permissions.\n\nTo allow all permissions:\n\nSet 'permission' to true\n\nTo allow specific permissions:\n\nSet 'permissions' to an array with a combination of the following available permissions:\n* print\n* degraded_print\n* modify,\n* assembly,\n* copy_contents,\n* screen_readers,\n* annotate,\n* fill_in\n\n## How to\n\n## Ensure css, images etc. are loaded in PDF\n\nUse absolute URLs for static assets in your view templates for PDFs.\nIf you use `HtmlHelper::image()`, or `HtmlHelper::css()`\nmake sure you have set `fullBase` option to `true`.\n\nFor example\n```php\necho $this-\u003eHtml-\u003eimage('logo.png', ['fullBase' =\u003e true]);\necho $this-\u003eHtml-\u003ecss('bootstrap.css', ['fullBase' =\u003e true]);\n```\n\nIf you are enable to get URLs for assets working properly, you can\ntry using file system paths instead for the assets.\n\n```\n\u003cimg src=\"\u003c?= WWW_ROOT ?\u003eimg/logo.png\" /\u003e\n```\n\n**Note:** Since v0.12.16 wkhtmltopdf requires the option `enable-local-file-access`\nto be able to use local filesytem paths for assets. You can enable it by setting\n`'enable-local-file-access' =\u003e true` in the engine config array.\n\n## Get header and footer on all pages\n\nHere are a couple of CSS based solutions you can refer to for easily\ngetting header footer on all PDF pages.\n\n* https://ourcodeworld.com/articles/read/687/how-to-configure-a-header-and-footer-in-dompdf\n* https://jessicaschillinger.com/print-repeating-header-browser/\n","funding_links":[],"categories":["PDF"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFriendsOfCake%2FCakePdf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFriendsOfCake%2FCakePdf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFriendsOfCake%2FCakePdf/lists"}