PHPackages                             statikbe/laravel-puppeteer-pdf-converter - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF &amp; Document Generation](/categories/documents)
4. /
5. statikbe/laravel-puppeteer-pdf-converter

ActiveLibrary[PDF &amp; Document Generation](/categories/documents)

statikbe/laravel-puppeteer-pdf-converter
========================================

This is a convenience wrapper for the Statik Puppeteer PDF conversion API on AWS Lambda.

v1.3.1(8mo ago)72.8kMITPHPPHP ^8.1|^8.2|^8.3CI passing

Since Apr 27Pushed 3d ago2 watchersCompare

[ Source](https://github.com/statikbe/laravel-puppeteer-pdf-converter)[ Packagist](https://packagist.org/packages/statikbe/laravel-puppeteer-pdf-converter)[ Docs](https://github.com/statikbe/laravel-puppeteer-pdf-converter)[ RSS](/packages/statikbe-laravel-puppeteer-pdf-converter/feed)WikiDiscussions main Synced today

READMEChangelog (9)Dependencies (13)Versions (14)Used By (0)

[![Laravel Puppeteer PDF Converter](documentation/img/banner-laravel-puppeteer-pdf-converter.png)](documentation/img/banner-laravel-puppeteer-pdf-converter.png)

Laravel Puppeteer PDF Converter &amp; Merger
============================================

[](#laravel-puppeteer-pdf-converter--merger)

[![Latest Version on Packagist](https://camo.githubusercontent.com/815bda2c87e3d85a19220759b9b42e4542c6c959cd2576ff292169eb5f737c48/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73746174696b62652f6c61726176656c2d7075707065746565722d7064662d636f6e7665727465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/statikbe/laravel-puppeteer-pdf-converter)[![Total Downloads](https://camo.githubusercontent.com/d68773dece0a835d8c68841c07c247205bfe03426633e6a9171fc421aaf1bacb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f73746174696b62652f6c61726176656c2d7075707065746565722d7064662d636f6e7665727465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/statikbe/laravel-puppeteer-pdf-converter)

This is a convenience wrapper for a service that converts an HTML page to PDF. The service uses [Puppeteer.js](https://pptr.dev/)and is developed in-house at [Statik](https://www.statik.be). The code for the service is not yet open-sourced, but can be shared upon request.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require statikbe/laravel-puppeteer-pdf-converter
```

You can publish the config file with:

```
php artisan vendor:publish --tag="puppeteer-pdf-converter-config"
```

This is the contents of the published config file: [puppeteer-pdf-converter.php](config%2Fpuppeteer-pdf-converter.php)

Configuration
-------------

[](#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](https://pptr.dev/#?product=Puppeteer&version=v10.4.0&show=api-pagepdfoptions).

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).

### Merge API

[](#merge-api)

**Required:** You need to set the url to the API in the `.env` with key `PDF_MERGER_API` and an API key in `PDF_MERGER_API_KEY`.

Usage
-----

[](#usage)

### Conversion API:

[](#conversion-api)

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.

```
//set options and get pdf from conversion API
try {
    $pdfOptions = new PdfOptions();
    $pdfOptions->setScale(0.6)
        ->setPageMargins(new PdfPageMargin(40, PdfPageMargin::MARGIN_IN_PIXELS));
    $pdfUrl = PuppeteerPdfConverter::convertRoute('report_index', ['organisation' => $organisation], 'report.pdf', $pdfOptions);
    return redirect($pdfUrl);
}
catch(PdfApiException $exception){
    Log::error(sprintf('PDF report could not be created: %s (for organisation: %s)', $exception->getMessage(), $organisation));
    return view('pdf_error', ['error' => $exception->getMessage()]);
}
```

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

[](#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.

### Merger API

[](#merger-api)

With the `PdfMerger` class you can merge multiple PDFs into one while maintaining the PDF layers (including links and annotations). This class provides two public functions to merge either URLs pointing to PDFs, or binary base64 strings representing PDFs, into one single PDF. The `mergePdfUrls` method requires an array of links to existing PDFs that you would like to merge, and optionally the output format of the final document along with its filename. You can output a url to the PDF file, stored in an S3 bucket, or receive the binary stream of the file.

Here is a simple example of how to use mergePdfUrls method:

```
$merger = new \Statikbe\PuppeteerPdfConverter\PdfMerger();
$urls = ['http://example.com/first.pdf', 'http://example.com/second.pdf'];
$mergedPdfUrl = $merger->mergePdfUrls($urls,
    \Statikbe\PuppeteerPdfConverter\Enum\MergerOutput::URL,
    'merged_file.pdf');
```

In this case, `$mergedPdfUrl` will hold the URL to the resulting PDF called 'merged\_file.pdf'.

`mergePdfFiles` method works similarly, but it takes an array of local file paths to the PDF documents you want to merge:

```
$merger = new \Statikbe\PuppeteerPdfConverter\PdfMerger();
$files = ['/path/to/first.pdf', '/path/to/second.pdf'];
$response = $merger->mergePdfFiles($files, \Statikbe\PuppeteerPdfConverter\Enum\MergerOutput::BASE64);
```

In this case, `$response` will contain a binary stream of the merged PDFs ready to be saved or sent over the network.

This functionality can be used with an optional `MergerOutput` parameter to determine the format of the result. By default, this parameter is set to output a URL. Alternatively, you can set `MergerOutput::BASE64` to retrieve the merged result as a Base64-encoded string.

Remember to always include appropriate exception handling when using these methods as they may throw a `PdfApiException` if the AWS Lambda function encounters an error.

Local development
-----------------

[](#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](https://ngrok.com/) or [Expose](https://expose.dev/). Or if you use [Valet](https://laravel.com/docs/9.x/valet), there is a [sharing command](https://laravel.com/docs/9.x/valet#sharing-sites)

```
valet share
```

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

```
ngrok http -host-header=APP_URL 80
```

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:

```
NGROK_APP_URL=http://dba0-94-224-113-240.ngrok.io

```

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`).

```
PuppeteerPdfConverter::isLocalTunnelConfigured();
```

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
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

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

Credits
-------

[](#credits)

- [sten](https://github.com/sten)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

51

—

FairBetter than 96% of packages

Maintenance82

Actively maintained with recent releases

Popularity25

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 67% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~145 days

Recently: every ~204 days

Total

9

Last Release

265d ago

PHP version history (4 changes)1.0.0PHP ^7.4|^8.0|^8.1

v1.2.0PHP ^7.4|^8.0|^8.1|^8.2

v1.2.2PHP ^8.0|^8.1|^8.2|^8.3

v1.3.0PHP ^8.1|^8.2|^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/1250437446b84017407f7f1900194b1e1c93fcf34b332ba382fb77f69b251cb6?d=identicon)[statikbe](/maintainers/statikbe)

---

Top Contributors

[![sten](https://avatars.githubusercontent.com/u/180665?v=4)](https://github.com/sten "sten (63 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (19 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (11 commits)")[![kristofser](https://avatars.githubusercontent.com/u/5928907?v=4)](https://github.com/kristofser "kristofser (1 commits)")

---

Tags

laravelpdfpdf-converterpdf-generationpuppeteerpdfpuppeteerhtml2pdfhtml-to-pdfstatikbepdf-conversion

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/statikbe-laravel-puppeteer-pdf-converter/health.svg)

```
[![Health](https://phpackages.com/badges/statikbe-laravel-puppeteer-pdf-converter/health.svg)](https://phpackages.com/packages/statikbe-laravel-puppeteer-pdf-converter)
```

###  Alternatives

[spatie/browsershot

Convert a webpage to an image or pdf using headless Chrome

5.2k30.7M82](/packages/spatie-browsershot)[spipu/html2pdf

Html2Pdf is a HTML to PDF converter written in PHP - It uses TCPDF - OFFICIAL PACKAGE

1.8k10.4M39](/packages/spipu-html2pdf)[chrome-php/chrome

Instrument headless chrome/chromium instances from PHP

2.6k4.3M54](/packages/chrome-php-chrome)[gotenberg/gotenberg-php

A PHP client for interacting with Gotenberg, a developer-friendly API for converting numerous document formats into PDF files, and more!

3674.8M15](/packages/gotenberg-gotenberg-php)[spiritix/php-chrome-html2pdf

A PHP library for converting HTML to PDF using Google Chrome

153465.3k2](/packages/spiritix-php-chrome-html2pdf)[imal-h/pdf-box

The most advanced, driver-based PDF manipulation library for PHP v3.0. Supports Ghostscript, Chrome Headless (HTML to PDF), OpenSSL/FPDI (Signing), and PDFtk (Forms).

59400.0k](/packages/imal-h-pdf-box)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
