Download the PHP package bnussbau/trmnl-pipeline-php without Composer

ePaper Pipeline PHP

ePaper Pipeline PHP provides a streamlined API, based on the pipeline pattern, for converting HTML content (or images) into optimized images for e-Paper devices. The image processing pipeline includes features like scaling, rotation, grayscale conversion, color quantization, and format-specific optimizations. This package is used in usetrmnl/larapaper. Devices model presets are provided by the TRMNL Models API.

Command line wrapper for this package: epaper-pipeline-cmd

Features

• Browser Rendering: HTML to image conversion using Spatie Browsershot
• Image Processing: Advanced image manipulation using ImageMagick
• TRMNL Models API: Automatic support for >=18 different e-paper device models (TRMNL, Seeed Studio, Kobo, Kindle, Nook, …).

Requirements

• PHP 8.2 or higher (PHP 8.4 + 8.5 are tested in CI)
• Imagick extension
• Spatie Browsershot (requires Node.js and Puppeteer -> see Browsershot Requirements)

Installation

You can install the package via composer:

Usage

With Model Configuration

Render HTML and convert to image compatible with the TRMNL OG model.

Generates PNG 800x480 8-bit Grayscale Gray 4c

Image Processing Only

Generates BMP3 800x480 1-bit sRGB 2c

Manual Configuration

Setting the Browser Timezone (optional)

You can control the timezone used by the headless browser when rendering your HTML by calling timezone() on BrowserStage with any valid PHP timezone identifier (e.g., UTC, America/New_York, Europe/Berlin).

Notes:

• The timezone is only applied when you explicitly call timezone(). If you don’t explicitly set the timezone, the browser will use the system timezone.
• This can be helpful when your HTML or scripts render time/date-dependent content.

Example:

Browser Rendering on AWS Lambda

You can use different Browsershot implementations (like BrowsershotLambda) by passing an instance to the BrowserStage. See installation instructions and requirments for stefanzweifel/sidecar-browsershot.

This allows you to use BrowsershotLambda or any other Browsershot implementation that extends Spatie\Browsershot\Browsershot.

Testing with Fake Mode

You can use the fake() method to prevent actual Browsershot and Imagick operations:

API Reference

Pipeline

The main pipeline class that orchestrates the processing stages.

BrowserStage

Converts HTML or a URL to PNG images using Spatie Browsershot. You must provide content via either html() or url() (mutually exclusive).

• html(string $html) — Set HTML content to render (e.g. a template or string).
• url(string $url) — Set a URL to capture (e.g. https://example.com). Use this when you want to screenshot a live webpage instead of rendering HTML. If the page is not black-and-white or contains photos, combine with ->dither() on ImageStage so the image is converted cleanly to the model’s limited palette; otherwise gradients and images can look harsh or banded.

Screenshot from URL with dithering (recommended for full-color or image-heavy pages):

ImageStage

Processes images for e-paper display compatibility.

Dithering

Recommended for photos but not for images containing mostly text, where it can make edges and letters appear rough or unclear. Dithering converts a grayscale photo into only black and white pixels by using patterns or noise to simulate intermediate shades, creating the illusion of continuous tones through spatial averaging.

Color Support

The pipeline supports color images via palettes defined in palettes.json. Models can specify one or more palette IDs, and the first palette with a colors array will be automatically applied. Color palettes use RGB colorspace for quantization and support dithering.

Example 1: Using Model Preset with Color Palette

Example 2: Defining Color Palette as Array

Model

Access device model configurations.

Development

Running Tests

Code Quality

License

MIT License. See LICENSE file for details.

Contributing

1. Create an issue to discuss your idea
2. Fork the repository
3. Create a feature branch
4. Make your changes
5. Add tests to maintain coverage
6. Run the test suite
7. Submit a pull request