PHPackages                             johind/collate - 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 & Document Generation](/categories/documents)
4. /
5. johind/collate

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

johind/collate
==============

Laravel PDF package to merge, split, extract pages, watermark, encrypt, and optimize PDFs using qpdf.

v1.5.3(1mo ago)9444MITPHPPHP ^8.4 || ^8.5CI passing

Since Mar 11Pushed 3w ago2 watchersCompare

[ Source](https://github.com/johind/laravel-collate)[ Packagist](https://packagist.org/packages/johind/collate)[ Docs](https://github.com/johind/collate)[ GitHub Sponsors](https://github.com/johind)[ RSS](/packages/johind-collate/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (10)Dependencies (27)Versions (14)Used By (0)

Build Better PDF Workflows in Laravel
=====================================

[](#build-better-pdf-workflows-in-laravel)

[![Tests](https://github.com/johind/laravel-collate/actions/workflows/run-tests.yml/badge.svg)](https://github.com/johind/laravel-collate/actions/workflows/run-tests.yml)[![Packagist License](https://camo.githubusercontent.com/e60623f508586f049d48cfb8396ee411b0c9bc3be174381a1893c37462a3c1e5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e63652d4d49542d626c7565)](http://choosealicense.com/licenses/mit/)[![Latest Stable Version](https://camo.githubusercontent.com/aed3b58552070d19839316351c8b6b3cca91d8779a610f44de92076b17892e82/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a6f68696e642f636f6c6c6174653f6c6162656c3d537461626c65)](https://packagist.org/packages/johind/collate)[![Total Downloads](https://camo.githubusercontent.com/70dd3a3d150ad1ce24dca4eff519b61f9c02f2b1f7cc9d20927e177d95b1e53f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a6f68696e642f636f6c6c6174652e7376673f6c6162656c3d446f776e6c6f616473)](https://packagist.org/packages/johind/collate)

Collate brings fluent PDF workflows to Laravel, giving your app expressive, chainable tools to compose, transform, secure, and deliver PDFs.

Powered by [qpdf](https://qpdf.readthedocs.io/), it supports common operations including merging, splitting, extracting pages, watermarking, encryption, editing metadata, and web optimisation.

Requirements
------------

[](#requirements)

- PHP 8.4+
- Laravel 11, 12, or 13
- [qpdf](https://qpdf.readthedocs.io/) v11.7.1 or higher installed on your system

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

[](#installation)

Install the package via Composer:

```
composer require johind/collate
```

Then run the install command to publish the configuration and verify that `qpdf` is available:

```
php artisan collate:install
```

You may also publish the config file manually:

```
php artisan vendor:publish --tag="collate-config"
```

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

[](#configuration)

The published config file (`config/collate.php`) contains three options:

```
return [
    // Path to the qpdf binary (default: 'qpdf')
    'binary_path' => env('COLLATE_BINARY_PATH', 'qpdf'),

    // Default filesystem disk for reading/writing PDFs (default: null, uses your app's default disk)
    'default_disk' => env('COLLATE_DISK'),

    // Directory for temporary files during processing (automatically cleaned up)
    'temp_directory' => env('COLLATE_TEMP_DIR', storage_path('app/collate')),
];
```

Quick Examples
--------------

[](#quick-examples)

```
use Johind\Collate\Facades\Collate;

// Prepare an uploaded document for archival
Collate::open($request->file('document'))
    ->addPages('legal/standard-terms.pdf')
    ->withMetadata(title: 'Client Report 2025')
    ->encrypt('client-password')
    ->toDisk('s3')
    ->save('reports/final.pdf');

// Merge and optimize multiple files for web viewing
Collate::merge('cover.pdf', 'chapter-1.pdf', 'chapter-2.pdf')
    ->overlay('branding/watermark.pdf')
    ->linearize()
    ->save('book.pdf');
```

Capabilities
------------

[](#capabilities)

CategoryFeatures**Getting started**[open](#opening-a-pdf) · [choose a disk](#choosing-a-disk) · [save](#save-to-disk) · [download](#download) · [stream](#stream-inline) · [raw content](#raw-content)**Page operations**[merge](#merging-pdfs) · [split](#splitting-a-pdf) · [add](#adding-pages) · [remove](#removing-pages) · [extract](#extracting-pages) · [rotate](#rotating-pages)**Overlays & watermarks**[overlay & underlay](#overlays--underlays)**Security**[encrypt / decrypt](#encryption--decryption) · [restrict permissions](#encryption--decryption)**Metadata & inspection**[read metadata](#reading-metadata) · [write metadata](#writing-metadata) · [strip metadata](#stripping-metadata) · [inspect](#inspecting-a-pdf) · [page count](#reading-metadata)**Optimization**[flatten](#flattening) · [linearize](#linearization) · [optimize](#optimization)**Advanced**[conditional operations](#conditional-operations) · [macros](#extending-with-macros) · [debugging](#debugging-the-qpdf-command) · [error handling](#error-handling)Getting Started
---------------

[](#getting-started)

Use `open()` to manipulate an existing PDF, or `merge()` to combine multiple files. Both return a fluent builder you can chain before saving or returning a response.

### Opening a PDF

[](#opening-a-pdf)

```
use Johind\Collate\Facades\Collate;

$pending = Collate::open('invoices/2024-001.pdf');
```

Files are resolved from your configured filesystem disk. You can also pass `UploadedFile` instances:

```
Collate::open($request->file('document'));
```

### Choosing a Disk

[](#choosing-a-disk)

Switch disks on the fly using `fromDisk()`:

```
Collate::fromDisk('s3')->open('reports/quarterly.pdf')->toDisk('local')->save('quarterly.pdf');
```

### Save to Disk

[](#save-to-disk)

```
Collate::open('input.pdf')->save('output.pdf');
```

### Download

[](#download)

Return a download response from a controller. The filename defaults to `document.pdf` when omitted:

```
return Collate::open('invoice.pdf')
    ->encrypt('client-password')
    ->download('invoice-2024-001.pdf');
```

### Stream Inline

[](#stream-inline)

Display the PDF inline in the browser. The filename defaults to `document.pdf` when omitted:

```
return Collate::merge('cover.pdf', 'report.pdf')
    ->linearize()
    ->stream('quarterly-report.pdf');
```

### Raw Content

[](#raw-content)

Get the raw PDF binary contents as a string. Useful for APIs, email attachments, or custom storage:

```
$content = Collate::open('document.pdf')->content();
```

### Returning from Controllers

[](#returning-from-controllers)

`PendingCollate` implements Laravel's `Responsable` interface, so you can return it directly from a controller. By default, the PDF is displayed in the browser:

```
public function show()
{
    return Collate::open('invoice.pdf');
}
```

Page Operations
---------------

[](#page-operations)

### Merging PDFs

[](#merging-pdfs)

Combine multiple files into a single document:

```
Collate::merge(
    'documents/cover.pdf',
    'documents/chapter-1.pdf',
    'documents/chapter-2.pdf',
)->save('documents/book.pdf');

// Also accepts a single array of files
Collate::merge(['doc1.pdf', 'doc2.pdf'])->save('merged.pdf');
```

For more control, pass a closure to select specific pages:

```
use Johind\Collate\PendingCollate;

Collate::merge(function (PendingCollate $pdf) {
    $pdf->addPage('documents/cover.pdf', 1);
    $pdf->addPages('documents/appendix.pdf', range: '1-3');
})->save('documents/book.pdf');
```

### Adding Pages

[](#adding-pages)

Append entire files or specific pages to an existing document:

```
Collate::open('report.pdf')
    ->addPage('appendix.pdf', pageNumber: 3)       // single page from another file
    ->addPages('terms.pdf', range: '1-5')          // page range
    ->addPages(['exhibit-a.pdf', 'exhibit-b.pdf']) // multiple complete files
    ->save('final-report.pdf');
```

Important

The `range` parameter cannot be used when passing an array of files. Chain multiple `addPages()` calls instead.

### Removing Pages

[](#removing-pages)

Remove specific pages from a document:

```
Collate::open('document.pdf')
    ->removePage(3)
    ->save('without-page-3.pdf');

Collate::open('document.pdf')
    ->removePages([1, 3, 5])
    ->save('trimmed.pdf');

// Remove a range of pages
Collate::open('document.pdf')
    ->removePages('5-10')
    ->save('trimmed.pdf');
```

### Extracting Pages

[](#extracting-pages)

Keep only the pages you need using `onlyPages()`:

```
Collate::open('document.pdf')
    ->onlyPages([1, 2, 3])
    ->save('first-three-pages.pdf');

// Also accepts qpdf range expressions
Collate::open('document.pdf')
    ->onlyPages('1-5,8,11-z')
    ->save('selected-pages.pdf');
```

Warning

`onlyPages()` and `removePages()` are mutually exclusive and neither can be called more than once — calling both, or calling either twice, on the same instance will throw a `BadMethodCallException`.

### Page Range Syntax

[](#page-range-syntax)

Anywhere a page range string is accepted (`onlyPages()`, `addPages()`, `removePages()`, `rotate()`), you can use [qpdf range syntax](https://qpdf.readthedocs.io/en/stable/cli.html#page-ranges):

ExpressionMeaning`1-5`Pages 1 through 5`1,3,5`Pages 1, 3, and 5`1-3,7-9`Pages 1–3 and 7–9`z`Last page`1-z`All pages`1-z:odd`Odd pages only`1-z:even`Even pages only### Splitting a PDF

[](#splitting-a-pdf)

Split every page into its own file. The path supports a `{page}` placeholder for the page number:

```
$paths = Collate::open('multi-page.pdf')
    ->split('pages/page-{page}.pdf');

// $paths → Collection ['pages/page-1.pdf', 'pages/page-2.pdf', ...]
```

Important

Always include `{page}` in your path. Without it, every page will be written to the same destination, with each one overwriting the last.

All operations (page selection, rotation, overlays, etc.) are applied before splitting, so you can chain them freely:

```
Collate::open('scanned.pdf')
    ->rotate(90)
    ->onlyPages('1-5')
    ->split('pages/page-{page}.pdf');
```

### Rotating Pages

[](#rotating-pages)

Rotate pages by 0, 90, 180, or 270 degrees:

```
Collate::open('scanned.pdf')
    ->rotate(90)
    ->save('rotated.pdf');

// Rotate specific pages only
Collate::open('scanned.pdf')
    ->rotate(90, range: '1-3')
    ->rotate(180, range: '5')
    ->save('fixed.pdf');
```

Overlays & Underlays
------------------------

[](#overlays--underlays)

Add watermarks, letterheads, or backgrounds. Both methods accept a disk path or an `UploadedFile` instance:

```
// Overlay (on top — watermarks, stamps)
Collate::open('document.pdf')
    ->overlay('watermark.pdf')
    ->save('watermarked.pdf');

// Underlay (behind — backgrounds, letterheads)
Collate::open('content.pdf')
    ->underlay('letterhead.pdf')
    ->save('branded.pdf');
```

Encryption & Decryption
---------------------------

[](#encryption--decryption)

Encrypt a document with a password:

```
Collate::open('confidential.pdf')
    ->encrypt('secret')
    ->save('protected.pdf');
```

For more control, use separate user and owner passwords and restrict specific permissions. Note that `restrict()` must be called after `encrypt()`:

```
Collate::open('confidential.pdf')
    ->encrypt(
        userPassword: 'secret',
        ownerPassword: 'more-secret',
        bitLength: 256,
    )
    ->restrict('print', 'extract')
    ->save('locked.pdf');
```

The following permissions can be passed to `restrict()`:

PermissionEffect`print`Disallow printing`modify`Disallow modifications`extract`Disallow text and image extraction`annotate`Disallow adding annotations`assemble`Disallow page assembly (inserting, rotating, etc.)`print-highres`Disallow high-resolution printing`form`Disallow filling in form fields`modify-other`Disallow all other modificationsDecrypt a password-protected document:

```
Collate::open('locked.pdf')
    ->decrypt('secret')
    ->save('unlocked.pdf');
```

Re-encrypt with a new password in one step:

```
Collate::open('locked.pdf')
    ->decrypt('old-password')
    ->encrypt('new-password')
    ->save('re-encrypted.pdf');
```

Metadata & Inspection
-------------------------

[](#metadata--inspection)

### Reading Metadata

[](#reading-metadata)

Use `inspect()` (a semantic alias for `open()`) for read-only operations like reading metadata or counting pages:

```
$meta = Collate::inspect('document.pdf')->metadata();

$meta->title;        // 'Quarterly Report'
$meta->author;       // 'Taylor Otwell'
$meta->subject;
$meta->keywords;
$meta->creator;
$meta->producer;
$meta->creationDate;
$meta->modDate;

$count = Collate::inspect('document.pdf')->pageCount();
```

`pageCount()` and `metadata()` are also available on the builder if you need them mid-chain, even after a `merge()`:

```
Collate::merge('doc1.pdf', 'doc2.pdf')
    ->when(fn ($pdf) => $pdf->pageCount() > 10, fn ($pdf) => $pdf->rotate(90))
    ->save('merged.pdf');
```

### Writing Metadata

[](#writing-metadata)

Set metadata on the output document:

```
Collate::open('document.pdf')
    ->withMetadata(
        title: 'Annual Report 2024',
        author: 'Taylor Otwell',
    )
    ->save('branded-report.pdf');

// Also accepts a PdfMetadata instance (named parameters override its values)
$meta = Collate::inspect('source.pdf')->metadata();
Collate::open('target.pdf')
    ->withMetadata($meta, author: 'New Author')
    ->withMetadata(title: 'Updated Title')
    ->save('output.pdf');
```

Note

When you pass a `PdfMetadata` instance, you can override any named fields in the same call except `title`. To change the title, call `withMetadata()` again with `title:` as shown above.

### Stripping Metadata

[](#stripping-metadata)

Remove all metadata from the output document:

```
Collate::open('document.pdf')
    ->withoutMetadata()
    ->save('clean.pdf');
```

Warning

`withoutMetadata()` and `withMetadata()` are mutually exclusive. Calling both on the same instance will throw a `BadMethodCallException`.

### Inspecting a PDF

[](#inspecting-a-pdf)

Use `inspect()` to query properties of an existing document without modifying it:

```
$pdf = Collate::inspect('document.pdf');

$pdf->isEncrypted();  // true if the document is encrypted
$pdf->hasPassword();  // true if a password is required to open the document
$pdf->isLinearized(); // true if the document is linearized for fast web viewing
$pdf->pdfVersion();   // e.g. '1.7', '2.0'
$pdf->pageSize();     // PageSize { width: 612.0, height: 792.0 }
$pdf->pageSize(3);    // dimensions of a specific page
```

`inspect()` is a semantic alias for `open()`. You can also call these methods mid-chain on any builder.

`pageSize()` returns the underlying page box dimensions in PDF points, not a rotation-adjusted display size. The returned `PageSize` object includes conversion helpers:

```
$size = Collate::inspect('document.pdf')->pageSize();

$size->widthInInches();
$size->heightInInches();
$size->widthInMillimeters();
$size->heightInMillimeters();
```

Optimization
------------

[](#optimization)

### Flattening

[](#flattening)

Flatten form fields and annotations into the page content:

```
Collate::open('form-filled.pdf')->flatten()->save('flattened.pdf');
```

### Linearization

[](#linearization)

Optimize a PDF for fast web viewing (progressive loading):

```
Collate::open('large-report.pdf')->linearize()->save('web-optimized.pdf');
```

### File Size Optimization

[](#file-size-optimization)

Reduce file size by removing redundant data and optimizing internal structures:

```
Collate::open('bloated.pdf')->optimize()->save('smaller.pdf');
```

When `optimize()` is combined with `linearize()`, qpdf's linearization requirements take precedence over object stream generation. Other optimization steps still apply.

```
Collate::open('form-filled.pdf')
    ->flatten()
    ->optimize()
    ->linearize()
    ->save('optimized.pdf');
```

Advanced
--------

[](#advanced)

### Conditional Operations

[](#conditional-operations)

`PendingCollate` uses the `Conditionable` trait, so you can conditionally apply operations:

```
Collate::open('document.pdf')
    ->when($request->boolean('watermark'), fn ($pdf) => $pdf->overlay('watermark.pdf'))
    ->when($request->boolean('flatten'), fn ($pdf) => $pdf->flatten())
    ->save('output.pdf');
```

### Extending with Macros

[](#extending-with-macros)

Register macros on `PendingCollate` to add chainable operations:

```
use Johind\Collate\PendingCollate;

PendingCollate::macro('stamp', function () {
    return $this->overlay('assets/stamp.pdf');
});

Collate::open('contract.pdf')->stamp()->save('stamped.pdf');
```

Register macros on `Collate` to add new entry points:

```
use Johind\Collate\Collate;

Collate::macro('openInvoice', function (int $invoiceId) {
    return $this->open("invoices/{$invoiceId}.pdf");
});

Collate::openInvoice(2024001)->download();
```

### Debugging the qpdf Command

[](#debugging-the-qpdf-command)

Use `dump()` and `dd()` to inspect the underlying qpdf command that Collate builds, without executing it:

```
Collate::open('document.pdf')
    ->rotate(90)
    ->encrypt('secret')
    ->dump();  // dumps the command and continues the chain

Collate::open('document.pdf')
    ->overlay('watermark.pdf')
    ->dd();    // dumps the command and stops execution
```

Warning

The output may contain sensitive data such as file paths and passwords.

### Error Handling

[](#error-handling)

All exceptions thrown by Collate extend `Johind\Collate\Exceptions\CollateException`, which itself extends PHP's `RuntimeException`.

When a `qpdf` command fails, a `Johind\Collate\Exceptions\ProcessFailedException` is thrown, exposing the `exitCode`and `errorOutput` from the underlying process. Invalid arguments (bad page ranges, unsupported rotation degrees, etc.) throw standard `InvalidArgumentException` or `BadMethodCallException` instances.

```
use Johind\Collate\Exceptions\ProcessFailedException;

try {
    Collate::open('corrupted.pdf')->save('output.pdf');
} catch (ProcessFailedException $e) {
    $e->exitCode;    // qpdf exit code
    $e->errorOutput; // stderr from qpdf
}
```

Changelog
---------

[](#changelog)

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

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

[](#contributing)

Thank you for your help in keeping Collate stable! I am primarily looking for contributions that focus on fixing bugs, improving error handling or enhancing performance. If you have an idea for a new feature, please open an issue to discuss it with me first, since I want to ensure that the scope of the package remains focused. Please note that I do not provide monetary compensation for contributions.

Before submitting a code change, run `composer check`. Collate uses Pest for all tests; please do not add PHPUnit test classes or run the suite through `vendor/bin/phpunit`.

Security
--------

[](#security)

If you discover a security vulnerability, please send an email rather than opening a GitHub issue.

License
-------

[](#license)

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

###  Health Score

49

—

FairBetter than 94% of packages

Maintenance94

Actively maintained with recent releases

Popularity23

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~6 days

Recently: every ~16 days

Total

13

Last Release

31d ago

PHP version history (2 changes)v1.0.0PHP ^8.4

v1.4.3PHP ^8.4 || ^8.5

### Community

Maintainers

![](https://www.gravatar.com/avatar/f5f531f5b08f2538e350a08ec17aa3d22e75e4142fa5237b6b4819c5988d9dce?d=identicon)[johind](/maintainers/johind)

---

Top Contributors

[![johind](https://avatars.githubusercontent.com/u/10245695?v=4)](https://github.com/johind "johind (128 commits)")

---

Tags

encryptionextractlaravelmergepackagepdfphpqpdfsplitwatermarklaravelpdfqpdfpdf-manipulationmerge-pdfsplit-pdfai-preparation

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/johind-collate/health.svg)

```
[![Health](https://phpackages.com/badges/johind-collate/health.svg)](https://phpackages.com/packages/johind-collate)
```

###  Alternatives

[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.3M42](/packages/spatie-laravel-pdf)[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.1k9.9M89](/packages/dedoc-scramble)[spatie/laravel-health

Monitor the health of a Laravel application

87411.3M152](/packages/spatie-laravel-health)[spatie/laravel-passkeys

Use passkeys in your Laravel app

470755.5k32](/packages/spatie-laravel-passkeys)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3913.7k](/packages/rawilk-profile-filament-plugin)[elegantly/laravel-invoices

Store invoices safely in your Laravel application

23441.5k1](/packages/elegantly-laravel-invoices)

PHPackages © 2026

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