PDF to ZPL

Convert a PDF into the ZPL format. Allowing for custom images, alphabets like Hebrew, Arabic and Cyrillic (without messing with fonts on the printer) and multipage shipping labels!

Gettings Started:

composer require faerber/pdf-to-zpl

<?php
use Faerber\PdfToZpl\PdfToZplConverter;

$converter = new PdfToZplConverter();

// Get an array of ZPL commands (1 per page)
$pages = $converter->convertFromFile("myFile.pdf");

foreach ($pages as $index => $page) {
    // Each page is a single ZPL statement
    assert(str_starts_with($page, "^XA^GFA,"));
}

Environment Setup:

Ensure you have Imagick and GD installed using:

sudo apt install php8.4-gd

sudo apt install php8.4-imagick

Then make sure to enable them in php.ini.

This library can work with only Imagick but GD is recommended as well because its a lot faster (see benchmarks for more details)! If you would like to only use Imagick use these settings:

<?php

use Faerber\PdfToZpl\PdfToZplConverter;
use Faerber\PdfToZpl\Settings\ConverterSettings;
use Faerber\PdfToZpl\Images\ImageProcessorOption;

$converter = new PdfToZplConverter(
    new ConverterSettings(
        imageProcessorOption: ImageProcessorOption::Imagick,
    )
);

Imagick Settings

You may need to enable PDF permission in your Imagick settings.

The easiest way to do this is by running the setup shell script: sudo ./scripts/configure-imagick.sh

If the script doesn't meet your needs you can perform the change manually. First edit your Imagick Policy file with: sudo nano "/etc/$(ls /etc/ | grep ImageMagick)/policy.xml"

Find this line and ensure the rights are set to read | write:

<policy domain="coder" rights="none" pattern="PDF" />

Change to:

<policy domain="coder" rights="read | write" pattern="PDF" />

I've only tested this library on Linux and Mac so if you get it working on windows feel free to open a PR!

Converting Images:

<?php
use Faerber\PdfToZpl\ImageToZplConverter;

$converter = new ImagetoZplConverter();

// Get an array of ZPL commands (1 per page)
[$zpl] = $converter->convertFromFile("myFile.png");
assert(str_starts_with($zpl, "^XA^GFA,"));

Unit Testing

Testing is done via PHP Unit. Run composer test.

If you make major changes you may need to regenerate the test data. For example modifying scaling code where the output is correct but the test data is outdated. Run composer generate-test-data and manually verify the images are rendered correctly.

Benchmarking

Benchmarking is done via phpbench. Run composer benchmark.

Formatting

Formatting is done via php-cs-fixer. Run composer format.

How does this work?

1. Loads the PDF and render each page as image
2. Scale the image to match the DPI and aspect ratio of the label
3. Convert each page into a grayscaled bitmap
4. Run line encode the bitmap and marshall it into a ZPL binary representation
5. Wrap the encoded data into a ZPL payload