Download the PHP package statikbe/laravel-puppeteer-pdf-converter without Composer

Laravel Puppeteer PDF Converter

This is a convenience wrapper for a service that converts an HTML page to PDF. The service uses Puppeteer.js and is developed in-house at Statik. The code for the service is not yet open-sourced, but can be shared upon request.

Installation

You can install the package via composer:

You can publish the config file with:

This is the contents of the published config file:

Configuration

Required: You need to set the url to the API in the .env with key PDF_CONVERSION_API.

Optional: The other configuration is optional. You can set default Puppeteer configuration, such as paper margins, scaling and paper width and height. The paper width and height defaults to A4. More information on possible Puppeteer configuration is available in the Puppeteer docs.

You can also manually set the PDF configuration when you create the PDF, see below. However, it is important to note that the default configuration set in the config file, is always taken as the basis and is overridden by the manual options in code. If a value is set to null in the config file or manual options, the option will not be send to the service (i.e. the option is disabled).

Usage

The library allows to convert an HTML page to a PDF for a route name (use convertRoute()) or for a URL (use convertUrl()).

If you want to override the PDF options that are set in the configuration file, you can create a PdfOptions object.

The following exceptions can occur:

• TimeoutException: Since the PDF conversion service runs on AWS Lambda, it can take timeout due to cold-start issues. If 20 seconds pass, this exception will be thrown. You can use this exception to implement a retry mechanism.
• UnsuccessfulHttpResponseException: When the given URL returns an HTTP status that is not successful (within the range of 200), this exception is thrown to avoid that error pages are rendered in the PDF.
• ConversionException: If an internal error occurs on the service or in the Puppeteer library, this exception is returned.
• PdfApiException: This exception is the super class of all above exceptions, and can thus be used to catch all of the above exceptions in one catch clause (as shown in the example).
• InvalidMarginUnitException: This exception is thrown if the unit of the margins is something else than px or cm.

Temporary URLs

The library can generate temporary signed URLs. This is handy if you need to generate PDFs from routes that require authorisation. The PDF service cannot login to your application. But by using temporarily signed URLs, we can validate that the application has generated the URL and no one has tempered with it.

You need to check in the controller of the HTML page whether the signature of the URL is valid. See section Local development for an example.

Local development

The PDF conversion service runs in the cloud. For local development, you can run it locally or use a tunneling service to expose your local web server. Examples of such tunneling software is Ngrok or Expose. Or if you use Valet, there is a sharing command

If you use Ngrok, you can start the service (replace APP_URL with the value of the APP_URL key in your .env file):

You can then configure the tunneled URL in the .env file with key NGROK_APP_URL. You can also set URLs of Valet or Expose in this variable. For example:

In case you use temporary signed URLs, there is a convenience function to check if a local tunnel is configured (i.e. whether the NGROK_APP_URL is set and the environment is set to local).

This can be used to bypass the valid signature check in your controller. Because the NGROK_APP_URL will be replaced in the generated URL, the signature will not be valid, hence we need to bypass the $request->hasValidSignature() check.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

You can use the Github issue tracker and pull requests are welcome!

Credits

• sten
• All Contributors

License

The MIT License (MIT). Please see License File for more information.