Download the PHP package johind/collate without Composer

Collate — PDF manipulation for Laravel

Collate is a Laravel package that provides a fluent API for manipulating PDFs.

Powered by qpdf, it supports common operations including merging, splitting, extracting pages, watermarking, encryption, editing metadata, and web optimisation.

Requirements

• PHP 8.4+
• Laravel 11, 12, or 13
• qpdf v11.7.1 or higher installed on your system

Installation

Install the package via Composer:

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

You may also publish the config file manually:

Configuration

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

Quick Examples

Capabilities

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

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

Choosing a Disk

Switch disks on the fly using fromDisk():

Save to Disk

Download

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

Stream Inline

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

Raw Content

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

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:

Page Operations

Merging PDFs

Combine multiple files into a single document:

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

Adding Pages

Append entire files or specific pages to an existing document:

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

Removing Pages

Remove specific pages from a document:

Extracting Pages

Keep only the pages you need using onlyPages():

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

Anywhere a page range string is accepted (onlyPages(), addPages(), removePages(), rotate()), you can use qpdf range syntax:

Splitting a PDF

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

[!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:

Rotating Pages

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

Overlays & Underlays

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

Encryption & Decryption

Encrypt a document with a password:

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

The following permissions can be passed to restrict():

Decrypt a password-protected document:

Re-encrypt with a new password in one step:

Metadata & Inspection

Reading Metadata

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

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

Writing Metadata

Set metadata on the output document:

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

Remove all metadata from the output document:

[!WARNING] withoutMetadata() and withMetadata() are mutually exclusive. Calling both on the same instance will throw a BadMethodCallException.

Inspecting a PDF

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

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:

Optimization

Flattening

Flatten form fields and annotations into the page content:

Linearization

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

File Size Optimization

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

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

Advanced

Conditional Operations

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

Extending with Macros

Register macros on PendingCollate to add chainable operations:

Register macros on Collate to add new entry points:

Debugging the qpdf Command

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

[!WARNING] The output may contain sensitive data such as file paths and passwords.

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.

Changelog

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

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.

Security

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

License

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