包简介

Convert HTML content into optimized images for a range of e-paper devices.

README 文档

README

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

browsershot_cham2v3cji4nbZ5JXN6_processed

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:

composer require bnussbau/epaper-pipeline-php

Usage

With Model Configuration

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

use Bnussbau\EpaperPipeline\Model;
use Bnussbau\EpaperPipeline\EpaperPipeline;
use Bnussbau\EpaperPipeline\Stages\ImageStage;
use Bnussbau\EpaperPipeline\Stages\BrowserStage;

$html = file_get_contents('./tests/assets/framework2_og.html');

$image = new EpaperPipeline()
    ->model(Model::OG)
    ->pipe(new BrowserStage()
        ->html($html))
    ->pipe(new ImageStage())
    ->process();

echo "Generated image: $image";

Generates PNG 800x480 8-bit Grayscale Gray 4c

Image Processing Only

use Bnussbau\EpaperPipeline\Stages\ImageStage;
use Bnussbau\EpaperPipeline\Model;

$imageStage = new ImageStage();
$imageStage->configureFromModel(Model::OG_BMP);

$result = $imageStage('./tests/assets/browsershot_og_1bit.png');
echo "Processed image: $result";

Generates BMP3 800x480 1-bit sRGB 2c

Manual Configuration

use Bnussbau\EpaperPipeline\Model;
use Bnussbau\EpaperPipeline\EpaperPipeline;
use Bnussbau\EpaperPipeline\Stages\ImageStage;
use Bnussbau\EpaperPipeline\Stages\BrowserStage;

$html = file_get_contents('./tests/assets/framework2_og.html');

$image = new EpaperPipeline()
    ->pipe(new BrowserStage()
        ->html($html))
    ->pipe(new ImageStage()
        ->format('png')
        ->width(800)
        ->height(600)
        ->rotation(90)
        ->colors(256)
        ->bitDepth(8))
    ->process();

echo "Generated image: $image";

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:

use Bnussbau\EpaperPipeline\Stages\BrowserStage;

$image = (new \Bnussbau\EpaperPipeline\EpaperPipeline())
    ->pipe((new BrowserStage())
        ->timezone('America/New_York')
        ->html('<html><body><script>document.write(new Date().toString())</script></body></html>'))
    ->pipe(new \Bnussbau\EpaperPipeline\Stages\ImageStage())
    ->process();

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.

use Bnussbau\EpaperPipeline\Model;
use Bnussbau\EpaperPipeline\EpaperPipeline;
use Bnussbau\EpaperPipeline\Stages\BrowserStage;
use Bnussbau\EpaperPipeline\Stages\ImageStage;
use Wnx\SidecarBrowsershot\BrowsershotLambda;

$html = file_get_contents('./tests/assets/framework2_og.html');

// Create your custom Browsershot instance (e.g., BrowsershotLambda)
$browsershotLambda = new BrowsershotLambda();

$image = new EpaperPipeline()
    ->model(Model::OG)
    ->pipe(new BrowserStage($browsershotLambda)
        ->html($html))
    ->pipe(new ImageStage())
    ->process();

echo "Generated image: $image";

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:

use Bnussbau\EpaperPipeline\Model;
use Bnussbau\EpaperPipeline\EpaperPipeline;
use Bnussbau\EpaperPipeline\Stages\BrowserStage;
use Bnussbau\EpaperPipeline\Stages\ImageStage;

// Enable fake mode for testing
EpaperPipeline::fake();

$html = '<html><body>Test Content</body></html>';

$result = (new EpaperPipeline())
    ->model(Model::OG)
    ->pipe(new BrowserStage()->html($html))
    ->pipe(new ImageStage())
    ->process();

echo "Mock image generated: $result";

// Disable fake mode when done
EpaperPipeline::restore();

API Reference

Pipeline

The main pipeline class that orchestrates the processing stages.

$pipeline = new Pipeline();
$pipeline->model(Model::OG_PNG); // Set model for automatic configuration
$pipeline->pipe(new BrowserStage()); // Add browser stage
$pipeline->pipe(new ImageStage()); // Add image stage
$result = $pipeline->process($payload); // Process payload

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.

$browserStage = new BrowserStage();
$browserStage
    ->html('<html><body>Content</body></html>')
    ->width(800)
    ->height(480)
    ->useDefaultDimensions() // force 800x480 e.g. in combination with Model to upscale image
    ->setBrowsershotOption('addStyleTag', json_encode(['content' => 'body{ color: red; }']));

$result = $browserStage(null);

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

$image = (new EpaperPipeline())
    ->model(Model::OG)
    ->pipe((new BrowserStage())->url('https://example.com'))
    ->pipe((new ImageStage())->dither())
    ->process();

ImageStage

Processes images for e-paper display compatibility.

$imageStage = new ImageStage();
$imageStage
    ->format('png')
    ->width(800)
    ->height(480)
    ->offsetX(0)
    ->offsetY(0)
    ->rotation(0)
    ->colors(2)
    ->bitDepth(1)
    ->outputPath('/path/to/output.png');

$result = $imageStage('/path/to/input.png');

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.

use Bnussbau\EpaperPipeline\Stages\ImageStage;

(new ImageStage())
    ->dither()
    ->colors(2)
    ->bitDepth(1);

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

use Bnussbau\EpaperPipeline\Model;
use Bnussbau\EpaperPipeline\EpaperPipeline;
use Bnussbau\EpaperPipeline\Stages\BrowserStage;
use Bnussbau\EpaperPipeline\Stages\ImageStage;

$html = file_get_contents('./tests/assets/color_6a_test.html');

// Inky Impression 13.3 model has color-6a palette (6 colors: red, green, blue, yellow, black, white)
$image = new EpaperPipeline()
    ->model(Model::INKY_IMPRESSION_13_3)
    ->pipe(new BrowserStage()
        ->html($html))
    ->pipe(new ImageStage())
    ->process();

echo "Generated color image: $image";

Example 2: Defining Color Palette as Array

use Bnussbau\EpaperPipeline\Stages\ImageStage;

// Define custom color palette (6 colors)
$colorPalette = [
    '#FF0000', // Red
    '#00FF00', // Green
    '#0000FF', // Blue
    '#FFFF00', // Yellow
    '#000000', // Black
    '#FFFFFF', // White
];

$imageStage = new ImageStage();
$imageStage
    ->format('png')
    ->colormap($colorPalette)
    ->dither(true); // Dithering works with color palettes (optional; only use for images)

$result = $imageStage('/path/to/input.png');
echo "Processed color image: $result";

Model

Access device model configurations.

$model = Model::OG_PNG;
$data = $model->getData();

echo $model->getLabel(); // "TRMNL OG (1-bit)"
echo $model->getWidth(); // 800
echo $model->getHeight(); // 480
echo $model->getColors(); // 2
echo $model->getBitDepth(); // 1

Development

Running Tests

composer test
composer test-coverage

Code Quality

composer format
composer analyse
composer rector

License

MIT License. See LICENSE file for details.

Contributing

Create an issue to discuss your idea
Fork the repository
Create a feature branch
Make your changes
Add tests to maintain coverage
Run the test suite
Submit a pull request

bnussbau/trmnl-pipeline-php 适用场景与选型建议

bnussbau/trmnl-pipeline-php 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 2.48k 次下载、GitHub Stars 达 0，最近一次更新时间为 2025 年 09 月 17 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「bnussbau」「epaper」「epaper-pipeline-php」「e-paper」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 bnussbau/trmnl-pipeline-php 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 bnussbau/trmnl-pipeline-php 我们能提供哪些服务？

定制开发 / 二次开发

基于 bnussbau/trmnl-pipeline-php 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 bnussbau/trmnl-pipeline-php 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

bnussbau/epaper-pipeline-php 0