README

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

Command line wrapper for this package: trmnl-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 >=12 different e-ink device models.

Requirements

PHP 8.2 or higher
Imagick extension
Spatie Browsershot (requires Node.js and Puppeteer -> see Browsershot Requirements)

Installation

You can install the package via composer:

composer require bnussbau/trmnl-pipeline-php

Usage

With Model Configuration

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

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

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

$image = new TrmnlPipeline()
    ->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\TrmnlPipeline\Stages\ImageStage;
use Bnussbau\TrmnlPipeline\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\TrmnlPipeline\Model;
use Bnussbau\TrmnlPipeline\TrmnlPipeline;
use Bnussbau\TrmnlPipeline\Stages\ImageStage;
use Bnussbau\TrmnlPipeline\Stages\BrowserStage;

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

$image = new TrmnlPipeline()
    ->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";

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\TrmnlPipeline\Model;
use Bnussbau\TrmnlPipeline\TrmnlPipeline;
use Bnussbau\TrmnlPipeline\Stages\BrowserStage;
use Bnussbau\TrmnlPipeline\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 TrmnlPipeline()
    ->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\TrmnlPipeline\Model;
use Bnussbau\TrmnlPipeline\TrmnlPipeline;
use Bnussbau\TrmnlPipeline\Stages\BrowserStage;
use Bnussbau\TrmnlPipeline\Stages\ImageStage;

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

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

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

echo "Mock image generated: $result";

// Disable fake mode when done
TrmnlPipeline::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 to PNG images using Spatie Browsershot.

$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);

ImageStage

Processes images for e-ink 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');

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

Maintainers

Details