HTML PDF API Bundle

There are a lot of different solutions for converting HTML to PDF, as there are many usages for such a tool. Some of those tools are incomplete, or overly simplified; others are too expensive. Our friends over at Effectiva Studio have come up with what we have found to be a great way to convert HTML to PDF. They have an API which lets you define a lot of different options, personalization of your PDF, and other goodies - check out HTMLPDFAPI.

As we found that API very useful, we also figured we could make it easier to use it in Symfony projects. Therefore, the idea was born to wrap the API in a Symfony2 bundle. And the Netgen HtmlPdfApi Bundle was born.

Further down the road we decided it wouldn’t be fair to make this available just for the Symfony community, so we separated the HtmlPdfApi wrapper into a PHP library, and left the bundle just to worry about the configuration and making it simpler to use in Symfony projects. Now anyone is able to use our wrapper from any PHP framework!

HTMLPDFAPI options

HTMLPDFAPI offers a variety of options -  you can generate PDF from URL, generate PDF from HTML, manage assets on the server, find out how many credits you have left on your account, and much more.

Assets enable you to permanently upload your frequently used files like your logo, font or a high quality image. When generating PDF you can also send a header and/or footer template with some variables, such as {{ page }}, {{ pages }} and {{ title }}, or your asset <img src="{{assets_path}}/my_image.jpg" />.

There are really a lot of options (listed in documentation), and all of them are made available through our bundle.

HTMLPDFAPI Bundle

It is obvious you need some kind of an HTTP client to use the HTMLPDFAPI. We decided to give it a go with Guzzle. Our bundle comes with a predefined configuration for Guzzle, but, just in case you don’t like it, we also added a CURL client. Of course, you can feel free to add some other HTTP client implementation of your own, just be sure to configure the bundle properly. :)

In short, the bundle offers you the following functionalities:

• generate PDF from a web page URL
• generate PDF directly from an HTML string
• generate PDF from a file (for example, a zip file)
• manage assets
• control account credits

If you would like to try it out, simply follow the instructions on Github.

Using the bundle

If you have installed and properly configured the bundle, you can now start using it in your own project. The wrapper is defined as a service, so you need to get it from a service container:

$htmlPdfApi = $this->container->get('netgen_html_pdf_api'); 

Generating PDF

After getting the service from the service container, everything is as simple as it can be. You just set an array with parameters, and pass those parameters to the method of your choice.

Available methods are:

• generateFromURL
• generateFromHTML
• generateFromFile

Each of the methods expects a parameter array, with the same set of options available (listed on the HTMLPDFAPI documentation site).

For example, if you would like to generate a PDF from our homepage, with DPI of the generated document set at 150, and in the landscape orientation, you would do something like this:

$params = array(
    'url' => "https://www.netgen.io",
    'dpi' => 150,
    'orientation' => “landscape”
);

$pdfFile = $htmlPdfApi->generateFromURL($params);

It is the same if you choose to generate PDF from HTML or from file, the only thing that differs is the required parameter - if you are generating from URL, the ‘url’ field in the parameters array must be set; if you are generating from HTML, the ‘html’ parameter must be set; and of course, if generating from file, the ‘file’ parameter must be set. Only one parameter of the three can be set (setting the ‘html’ parameter on the generateFromURL method will produce an error). Other parameters are the same for all three functions.

Simple examples:

• generating from HTML string:

$params = array('html' => "<h1>HTML PDF API is cool!</h1>");
$pdfFile = $htmlPdfApi->generateFromHTML($params);

• generating from file:

$params = array('file' => "example.html");
$pdfFile = $htmlPdfApi->generateFromFile($params);

Managing assets

I already mentioned assets. They allow you to upload a file and use it as a local file on the server in your templates. There are several operations you can perform on assets: upload, download, delete, get asset id by name, and get list of uploaded assets.

Credits

When you sign up for HTMLPDFAPI service on their site, you get a certain number of credits available. Those credits are used every time you generate new file. The bundle offers you a possibility to find out how many credits you have left on your account.

Detailed instructions for using the bundle are available on Github.

Using the library without the bundle

Of course, you don’t have to use the bundle, you can only use our library. It is as simple as adding one line of code in your composer.json:

"require": {
    "netgen/htmlpdfapi": "0.1"
}, 

If you are using the library only, make sure you configure all the required parameters for the HTTP client (host, token), and pass on the client and the validator to the HtmlPdfApi object upon constructing.

So that’s it! We hope you will find our bundle and HTMLPDFAPI useful and that we made someone’s life at least a little bit easier with this product. :)

Feel free to share your feedback here or on Github!