by , 2 comments

Many web applications have a PDF export requirement: invoices, reports, brochures, or eBooks. Generating these PDFs, especially if they’re complex or large, can be really challenging. Fortunately, there’s DocRaptor, which provides an easy-to-use API for converting HTML web pages into PDFs. This is a walkthrough of how to setup and use DocRaptor’s PHP library:

Installation

DocRaptor can be installed via the Composer dependency manager or by downloading the files directly. To use Composer, simply run this on your command line:

composer require docraptor/docrapto

Alternatively, download and unzip the latest release into your project directory. Simply include autoload.php to get access to the DocRaptor library:

// docraptor.php require_once('/path/to/docraptor-php/autoload.php');

Add Your API Key

Unlimited watermarked test documents can made using the “ YOUR_API_KEY_HERE ” key. If you’re ready to make non-watermarked documents, you can get your own API key by creating an account.

$configuration = DocRaptor\Configuration::getDefaultConfiguration(); $configuration->setUsername("YOUR_API_KEY_HERE");

Add HTML

To make your PDF, simply set the document content to your HTML:

$docraptor = new DocRaptor\DocApi(); $doc = new DocRaptor\Doc(); $doc->setDocumentContent("<html><body>Your HTML goes here!</body></html>");

If you want to use an existing website page, just input the URL like this:

$docraptor = new DocRaptor\DocApi(); $doc = new DocRaptor\Doc(); $doc->setDocumentUrl("http://docraptor.com/samples/ebook.html");

Either way you decide to input the HTML, any external assets in your HTML (CSS, JS, images) are required to be accessible to the DocRaptor servers. They must also either have absolute URLs or you can include a baseurl in your document or use the baseurl API option.

Set API Options

Since DocRaptor makes PDFs and Excel files, we need to set the document type:

$doc->setDocumentType("pdf");

To create the free watermarked documents, we need to set test to true:

$doc->setTest(true);

JavaScript processing can be enabled with this command:

$doc->setJavascript(true);

See DocRaptor’s API documentation for the full list of API options. There’s a lot of them, but they aren’t necessary for most projects.

Generate the PDF

That’s all the setup that’s required. Creating the document is just one line of code, but we should wrap it error handling:

try { $create_response = $docraptor->createDoc($doc); } catch (DocRaptor\ApiException $error) { echo $error . "

"; echo $error->getMessage() . "

"; echo $error->getCode() . "

"; echo $error->getResponseBody() . "

"; }

Save the PDF

Once generated, the PDF can be saved to the server.

$file = fopen("/tmp/docraptor-php.pdf", "wb"); fwrite($file, $create_response); fclose($file);

Or Send it to the Browser

Or if we’re creating the PDF after a user action and we want them to immediately download it, we can send it to the browser without saving it on the server:

header('Content-Description: File Transfer'); header('Content-Type: application/pdf'); header('Content-Disposition: attachment; filename=example.pdf'); header('Content-Transfer-Encoding: binary'); header('Expires: 0'); header('Cache-Control: must-revalidate, post-check=0, pre-check=0'); header('Pragma: public'); header('Content-Length: ' . strlen($create_response)); ob_clean(); flush(); echo($create_response); exit;

Complete Example

Putting it all together, here’s the full code for making a PDF with DocRaptor. As you can see, it’s short and offloads all the CPU intensive work off our server and puts it onto DocRaptor. It also lets us rapidly make PDFs if multiple users request a PDF at once, which is hard to do if we try to use an open source library.

<?php // docraptor.php require_once('docraptor-php/autoload.php'); $configuration = DocRaptor\Configuration::getDefaultConfiguration(); $configuration->setUsername("YOUR_API_KEY_HERE"); $docraptor = new DocRaptor\DocApi(); $doc = new DocRaptor\Doc(); $doc->setDocumentContent("<html><body>Hello World</body></html>"); //$doc->setDocumentUrl("http://docraptor.com/examples/invoice.html"); $doc->setDocumentType("pdf"); // DocRaptor also makes Excel files $doc->setTest(true); //$doc->setJavascript(true); try { $create_response = $docraptor->createDoc($doc); $file = fopen("/tmp/docraptor-php.pdf", "wb"); fwrite($file, $create_response); fclose($file); //header('Content-Description: File Transfer'); //header('Content-Type: application/pdf'); //header('Content-Disposition: attachment; filename=example.pdf'); //header('Content-Transfer-Encoding: binary'); //header('Expires: 0'); //header('Cache-Control: must-revalidate, post-check=0, pre-check=0'); //header('Pragma: public'); //header('Content-Length: ' . strlen($create_response)); //ob_clean(); //flush(); //echo($create_response); //exit; } catch (DocRaptor\ApiException $error) { echo $error . "

"; echo $error->getMessage() . "

"; echo $error->getCode() . "

"; echo $error->getResponseBody() . "

"; }

Despite PDFs being one of the internet’s most common standards, it’s surprisingly difficult to dynamically create PDFs from a website. There’s three primary tools used to create PDFs:

PDF Generators allow you to create PDFs by adding text at pixel location 123×456 and an images at pixel location 456×123. While fast to generate and simple, the code to generate these PDFs is brittle and time consuming to write.

Browser-Based libraries use Webkit or Chromium to generate a PDF based on HTML. These are fast to setup, but provide limited PDF functionality and quality. Browsers are simply not optimized from PDF generation.

Commercial libraries built from the ground up to turn HTML into PDFs. These engines are designed specifically for PDF generation and provide a level of quality and control than the browser-based libraries cannot.

DocRaptor is based on one of the commercial tools, but they offer affordable pricing and an easy-to-use PHP library.