escpos-php

The library uses different connectors to transport data to your printer. Choose the one that matches your operating system and printer interface:

• FilePrintConnector: Directly uses files (useful for writing to device files like /dev/usb/lp0).
• NetworkPrintConnector: Directly uses network sockets (e.g., for Ethernet printers on port 9100).
• WindowsPrintConnector: Connects to Windows shared printers from Windows or Linux (Linux users require Samba).
• CupsPrintConnector: Connects to CUPS-shared printers from Linux or Mac.
• MemoryPrintConnector: Does not connect to a real printer; use this to capture ESC/POS receipts for testing or auditing.

If you need to test a specific connection method, use the examples located in the example/interface/ subfolder. These include examples for:

• Parallel
• Serial
• USB
• Network
• File-based

To print to an Ethernet printer, use the NetworkPrintConnector. It communicates directly with the printer over the network, typically on port 9100. Ensure the printer is reachable from your PHP server's network.

For USB or Serial printers that you want to print to over a network, you must first install and share the printer on a computer, then use WindowsPrintConnector or CupsPrintConnector to access it.

Since ESC/POS "page mode" (which allows native complex layout rendering) is not supported, the recommended approach for complex layouts is to render the entire layout as an image and print that image.

For example, you can use wkhtmltoimage to convert HTML to an image, or use Imagick to print a PDF.

To develop with this library, it is recommended to load the imagick, gd, and Xdebug PHP extensions. The project requires PHP 8.2 or higher.

Install dependencies:

git clone https://github.com/mike42/escpos-php
cd escpos-php/
composer install

Run unit tests:

php vendor/bin/phpunit --coverage-text

Run tests with coverage (requires Xdebug):

XDEBUG_MODE=coverage php vendor/bin/phpunit --coverage-text

This library is designed for use with the Composer PHP dependency manager. Add the mike42/escpos-php package to your project to get started.

composer require mike42/escpos-php

If image printing is slow, consider these three optimizations:

1. Install Imagick: Ensure the Imagick PHP extension is loaded. The driver uses it to avoid a slower internal image processing implementation.
2. Use Faster Interfaces: Avoid Serial connections if possible; use USB or Ethernet to reduce data transfer time.
3. Reduce Image Density: Images are sent uncompressed. You can speed up transfers by scaling down images. The driver provides an option to print at half density, which reduces the pixel count significantly while maintaining the same printed size.

Ensure your environment meets the following requirements:

• PHP: 8.2 or newer.
• Extensions (Required):
  • json: Used to load bundled printer definitions.
  • intl: Used for character encoding.
  • zlib: Used for de-compressing bundled resources.
• Extensions (Recommended):
  • imagick or gd: Used to speed up image processing. If neither is present, the library falls back to gfx-php.

The example/ directory contains a collection of feature demonstrations. For a quick overview of what your printer supports, run demo.php.

Note: Most examples print to standard output (STDOUT). To see them work on a physical printer, you must either edit the PrintConnector within the example file or redirect the script's output to your printer device.

EscposPrintBuffer is a standard implementation of the PrintBuffer interface. It manages character encoding, newlines, and code page switching for ESC/POS printers. It automatically handles UTF-8 normalization and attempts to map Unicode code points to the printer's supported code pages.

If you encounter issues with character rendering on your specific hardware, you can interchange this for an ImagePrintBuffer (which uses image-based rendering instead).