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.

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.

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