PHPackages                             webcooking/zpl-to-image - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. webcooking/zpl-to-image

ActiveLibrary[Image & Media](/categories/media)

webcooking/zpl-to-image
=======================

A PHP library to convert ZPL content to SVG images or GDImage objects

1.0.3(6mo ago)11.2k↓18.8%LGPL-3.0-or-laterPHPPHP >=8.0

Since Oct 3Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/webcooking/zpl_to_image)[ Packagist](https://packagist.org/packages/webcooking/zpl-to-image)[ RSS](/packages/webcooking-zpl-to-image/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (1)Versions (5)Used By (0)

ZPL to Image Converter
======================

[](#zpl-to-image-converter)

A PHP library to convert ZPL (Zebra Programming Language) content into images. **Generates SVG output** with support for TrueType fonts and GDImage conversion.

Features
--------

[](#features)

This library provides **3 types of ZPL conversion**:

- **ZPL → SVG** (`ZplToSvg`) - Vector rendering with TrueType fonts
- **ZPL → Imagick** (`ZplToImagick`) - Rasterization via rsvg-convert or Imagick
- **ZPL → GDImage** (`ZplToGdImage`) - PNG/JPEG export

Requirements
------------

[](#requirements)

- PHP 8.0 or higher
- GD extension enabled
- **Imagick extension** (for SVG to GDImage conversion)
    - Install: `pecl install imagick`
    - Or: `apt-get install php-imagick` (Linux)
    - Or: `brew install imagemagick` + `pecl install imagick` (macOS)
- **rsvg-convert** (optional but **highly recommended** for reliable rasterization)
    - Install: `apt-get install librsvg2-bin` (Linux)
    - Or: `brew install librsvg` (macOS)
    - Automatically used when available, provides better SVG compatibility

Installation
------------

[](#installation)

Clone the repository and run Composer install:

```
git clone https://github.com/webcooking/zpl_to_image.git
cd zpl_to_image
composer install
```

Usage
-----

[](#usage)

### Method 1: Generate SVG (Recommended)

[](#method-1-generate-svg-recommended)

```
use Webcooking\ZplToImage\ZplToSvg;

$zplContent = file_get_contents('path/to/your/label.zpl');

// Default: Noto Sans font
$svgContent = ZplToSvg::convert($zplContent);

// Use IBM VGA font
$svgContent = ZplToSvg::convert($zplContent, 4.0, 6.0, 300, 'ibm-vga');

// Use your own custom font
$svgContent = ZplToSvg::convert($zplContent, 4.0, 6.0, 300, '/path/to/your/font.ttf');

// Save to file
file_put_contents('output.svg', $svgContent);

// View SVG in browser or convert to PNG with ImageMagick:
// convert -density 300 -background white output.svg output.png
```

### Available Fonts

[](#available-fonts)

**Built-in fonts:**

- `'noto'` - Noto Sans - **DEFAULT**
- `'ibm-vga'` - IBM VGA 8x16

**Custom fonts:**

- Provide a path to any `.ttf` file: `'/path/to/your/font.ttf'`

### Method 2: Convert to GDImage (Raster with Imagick)

[](#method-2-convert-to-gdimage-raster-with-imagick)

```
use Webcooking\ZplToImage\ZplToGdImage;

$zplContent = file_get_contents('path/to/your/label.zpl');

// Convert to GDImage with default font (Noto Sans)
$image = ZplToGdImage::convert($zplContent);
imagepng($image, 'output.png');
imagedestroy($image);

// With custom parameters and font
$image = ZplToGdImage::convert(
    $zplContent,
    4.0,           // width in inches
    6.0,           // height in inches
    300,           // DPI
    'ibm-vga'      // font: 'noto', 'ibm-vga', or '/path/to/font.ttf'
);
imagepng($image, 'output.png');
imagedestroy($image);
```

### Method 3: Direct File Export (PNG/JPEG)

[](#method-3-direct-file-export-pngjpeg)

```
use Webcooking\ZplToImage\ZplToGdImage;

$zplContent = file_get_contents('path/to/your/label.zpl');

// Save directly as PNG (best quality)
ZplToGdImage::toPng(
    $zplContent,
    'output.png',  // output path
    4.0,           // width in inches
    6.0,           // height in inches
    300,           // DPI
    'noto',        // font renderer
    9              // PNG compression (0-9, 9=max)
);

// Save directly as JPEG
ZplToGdImage::toJpeg(
    $zplContent,
    'output.jpg',  // output path
    4.0,           // width in inches
    6.0,           // height in inches
    300,           // DPI
    'noto',        // font renderer
    90             // JPEG quality (0-100)
);

// Just get SVG string (no rasterization)
$svg = ZplToGdImage::toSvg($zplContent, 4.0, 6.0, 300, 'noto');
file_put_contents('output.svg', $svg);
```

### Method 4: Get an Imagick object directly

[](#method-4-get-an-imagick-object-directly)

If you prefer to work with Imagick directly (for advanced processing, composites or filters), use `ZplToImagick` which returns an `Imagick` object.

```
use Webcooking\ZplToImage\ZplToImagick;

$imagick = ZplToImagick::convert($zplContent, 4.0, 6.0, 300, 'noto');
// Save as PNG/JPEG using Imagick methods
$imagick->writeImage('output_imagick.png');
$imagick->setImageFormat('jpeg');
$imagick->setImageCompressionQuality(90);
$imagick->writeImage('output_imagick.jpg');
$imagick->clear();
$imagick->destroy();
```

### Font Comparison

[](#font-comparison)

FontStyleFile Size**Noto Sans**Modern, clean~1.9 MB**IBM VGA**Retro, pixel style~35 KBTesting
-------

[](#testing)

Run the example test scripts:

```
# Test a specific ZPL file
php examples/test.php simple_label.zpl

# Test all examples
php examples/test_all.php

# Test with different fonts
php examples/test_all.php ibm-vga
```

See the `examples/` folder for more details.

**Creating your own tests**

1. Create a `.zpl` file in the `examples/` folder
2. Test it: `php examples/test.php your_file.zpl`

**Docker testing**

A Docker environment is provided for consistent testing with all dependencies:

```
# Build and run tests in Docker
./docker-build-and-run.sh

# Or manually:
docker build -t php-imagick-gd .
docker run --rm -v "$(pwd):/workspace" php-imagick-gd bash -c "cd /workspace && php examples/test_all.php"
```

The Docker environment includes `rsvg-convert` for reliable rasterization, solving potential blank image issues.

Supported ZPL Commands
----------------------

[](#supported-zpl-commands)

Currently supports:

- `^A0N`: Font settings (height, width)
- `^FO`: Field origin (position x,y)
- `^FN`: Field number (for data association)
- `^FD`: Field data (text content)
- `^FR`: Field reverse (white text on black)
- `^GB`: Graphic box (rectangles, lines, filled boxes)
- `^BCN`: Barcode Code 128

More commands can be added as needed.

Troubleshooting
---------------

[](#troubleshooting)

### Issue: Blank/White JPG Images

[](#issue-blankwhite-jpg-images)

**Problem:** Generated JPEG/PNG images appear completely white or blank, even though SVG output is correct.

**Cause:** Some Imagick installations don't properly handle SVG files with embedded fonts (data URLs in @font-face rules).

**Solution:** The library detects and uses `rsvg-convert` when available. All classes automatically use the best available renderer:

1. **Install rsvg-convert** (recommended):

    ```
    # Ubuntu/Debian
    sudo apt-get install librsvg2-bin

    # CentOS/RHEL
    sudo yum install librsvg2-tools

    # macOS
    brew install librsvg
    ```
2. **Docker setup** (if using containerization):

    ```
    RUN apt-get update && apt-get install -y librsvg2-bin librsvg2-dev
    ```
3. **Verify installation:**

    ```
    which rsvg-convert  # Should show path to binary
    rsvg-convert --version  # Should show version info
    ```

When `rsvg-convert` is available, the library automatically uses it for SVG rasterization, providing much better compatibility with embedded fonts and complex SVG elements. If `rsvg-convert` is not available, it falls back to direct Imagick conversion.

Resources
---------

[](#resources)

- [Zebra Programming Guide (PDF)](https://www.zebra.com/content/dam/zebra/manuals/printers/common/programming/zpl-zbi2-pm-en.pdf)

License
-------

[](#license)

**Project**: LGPL-3.0-or-later

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

**Fonts**:

- **Noto Sans**: SIL Open Font License 1.1 (see `fonts/Noto_Sans/OFL.txt`)
- **IBM VGA**: Creative Commons CC BY-SA 4.0 by VileR (int10h.org) (see `fonts/IBM_VGA/LICENSE`)

Support
-------

[](#support)

If you use this package in a commercial or paid project and find it helpful, I'd be grateful if you considered offering a small token of thanks :

No pressure — this is only if the library saved you time and you feel like supporting future work.

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance67

Regular maintenance activity

Popularity21

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~11 days

Total

4

Last Release

194d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4d2c20502c6ebef56950cd0f58b768c5797d9c901efb411c468a3e9a1782e9c0?d=identicon)[Nuranto](/maintainers/Nuranto)

---

Top Contributors

[![Nuranto](https://avatars.githubusercontent.com/u/1633463?v=4)](https://github.com/Nuranto "Nuranto (10 commits)")

### Embed Badge

![Health badge](/badges/webcooking-zpl-to-image/health.svg)

```
[![Health](https://phpackages.com/badges/webcooking-zpl-to-image/health.svg)](https://phpackages.com/packages/webcooking-zpl-to-image)
```

###  Alternatives

[milon/barcode

Barcode generator like Qr Code, PDF417, C39, C39+, C39E, C39E+, C93, S25, S25+, I25, I25+, C128, C128A, C128B, C128C, 2-Digits UPC-Based Extention, 5-Digits UPC-Based Extention, EAN 8, EAN 13, UPC-A, UPC-E, MSI (Variation of Plessey code)

1.5k13.3M39](/packages/milon-barcode)[bkwld/croppa

Image thumbnail creation through specially formatted URLs for Laravel

510496.0k23](/packages/bkwld-croppa)[goat1000/svggraph

Generates SVG graphs

132849.6k3](/packages/goat1000-svggraph)[cohensive/embed

Media Embed (for Laravel or as a standalone).

120370.4k](/packages/cohensive-embed)[netresearch/rte-ckeditor-image

Image support in CKEditor for the TYPO3 ecosystem - by Netresearch

63991.3k4](/packages/netresearch-rte-ckeditor-image)[humanmade/tachyon-plugin

Rewrites WordPress image URLs to use Tachyon

87338.5k2](/packages/humanmade-tachyon-plugin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)