# ESC/POS Print Driver for PHP
This project implements a subset of Epson's ESC/POS protocol for thermal receipt printers. It allows you to generate and print receipts with basic formatting, cutting, and barcodes on a compatible printer.
The library was developed to add drop-in support for receipt printing to any PHP app, including web-based point-of-sale (POS) applications.
## Compatibility
### Interfaces and operating systems
This driver is known to work with the following OS/interface combinations:
| |
Linux |
Mac |
Windows |
| Ethernet |
Yes |
Yes |
Yes |
| USB |
Yes |
Not tested |
Yes |
| USB-serial |
Yes |
Yes |
Yes |
| Serial |
Yes |
Yes |
Yes |
| Parallel |
Yes |
Not tested |
Yes |
| SMB shared |
Yes |
No |
Yes |
| CUPS hosted |
Yes |
Yes |
No |
### Printers
Many thermal receipt printers support ESC/POS to some degree. This driver has been known to work with:
- 3nStar RPT-008
- Approx APPPOS80AM
- AURES ODP-333
- AURES ODP-500
- Bematech-4200-TH
- Bematech LR2000E
- Birch PRP-085III
- Bixolon SRP-350III
- Bixolon SRP-350Plus
- Black Copper BC-85AC
- CHD TH-305N
- Citizen CBM1000-II
- Citizen CT-S310II
- Dapper-Geyi Q583P
- Daruma DR800
- DR-MP200 (manufacturer unknown)
- EPOS TEP 220M
- Elgin i9
- Epson EU-T332C
- Epson FX-890 (requires `feedForm()` to release paper).
- Epson TM-T20
- Epson TM-T20II
- Epson TM-T70
- Epson TM-T70II
- Epson TM-T81
- Epson TM-T82II
- Epson TM-T88II
- Epson TM-T88III
- Epson TM-T88IV
- Epson TM-T88V
- Epson TM-U220
- Epson TM-U295 (requires `release()` to release slip).
- Epson TM-U590 and TM-U590P
- Equal (EQ-IT-001) POS-58
- Everycom EC-58
- Excelvan HOP-E200
- Excelvan HOP-E58
- Excelvan HOP-E801
- Gainscha GP-2120TF
- Gainscha GP-5890x (Also marketed as EC Line 5890x)
- Gainscha GP-U80300I (Also marketed as gprinter GP-U80300I)
- gprinter GP-U80160I
- HOIN HOP-H58
- Ithaca iTherm 28
- Hasar HTP 250
- Metapace T-1
- Metapace T-25
- Nexa PX700
- Nyear NP100
- OKI RT322
- OKI 80 Plus III
- Orient BTP-R580
- P-822D
- P85A-401 (make unknown)
- Partner Tech RP320
- POSLIGNE ODP200H-III-G
- QPOS Q58M
- Rongta RP326US
- Rongta RP58-U
- Rongta RP80USE
- SAM4S GIANT-100DB
- Senor TP-100
- Sewoo SLK-TS400
- SEYPOS PRP-96
- SEYPOS PRP-300 (Also marketed as TYSSO PRP-300)
- SNBC BTP-R880NPIII
- Solux SX-TP-88300
- Sicar POS-80
- Silicon SP-201 / RP80USE
- SPRT SP-POS88V
- Star BSC10
- Star TSP100 ECO
- Star TSP100III FuturePRNT
- Star TSP-650
- Star TUP-592
- TVS RP45 Shoppe
- Venus V248T
- Xeumior SM-8330
- Xprinter F-900
- Xprinter XP-365B
- Xprinter XP-58 Series
- Xprinter XP-80C
- Xprinter XP-90
- XPrinter XP-Q20011
- Xprinter XP-Q800
- Zjiang NT-58H
- Zjiang ZJ-5870
- Zjiang ZJ-5890 (Also sold as POS-5890 by many vendors; ZJ-5890K, ZJ-5890T also work).
- Zjiang ZJ-8220 (Also marketed as Excelvan ZJ-8220)
- Zjiang ZJ-8250
If you use any other printer with this code, please [let us know](https://github.com/mike42/escpos-php/issues/new) so that it can be added to the list.
## Basic usage
### Include the library
#### Composer
This library is designed for use with the `composer` PHP dependency manager. Simply add the `mike42/escpos-php` package to get started:
```bash
composer require mike42/escpos-php
```
If you haven't used `composer` before, you can read about it at [getcomposer.org](https://getcomposer.org/).
#### Requirements
This project has few hard dependencies:
- PHP 8.2 or newer.
- `json` extension, used to load bundled printer definitions (see [documentation](https://www.php.net/manual/en/book.json.php))
- `intl` extension, used for character encoding (see [documentation](https://www.php.net/manual/en/book.intl.php))
- `zlib` extension, used for de-compressing bundled resources (see [documentation](https://www.php.net/manual/en/book.zlib.php)).
It is also suggested that you install either `imagick` or `gd`, as these will be used to speed up image processing if present. The [gfx-php](https://github.com/mike42/gfx-php) library will otherwise be used as a fallback.
### The 'Hello World' receipt
To make use of this driver, your server (where PHP is installed) must be able to communicate with your printer. Start by generating a simple receipt and sending it to your printer using the command-line.
```php
text("Hello World!\n");
$printer -> cut();
$printer -> close();
```
Some examples are below for common interfaces.
Communicate with a printer with an Ethernet interface using `netcat`:
```bash
php hello-world.php | nc 10.x.x.x. 9100
```
A USB local printer connected with `usblp` on Linux has a device file (Includes USB-parallel interfaces):
```bash
php hello-world.php > /dev/usb/lp0
```
A computer installed into the local `cups` server is accessed through `lp` or `lpr`:
```bash
php hello-world.php > foo.txt
lpr -o raw -H localhost -P printer foo.txt
```
A local or networked printer on a Windows computer is mapped in to a file, and generally requires you to share the printer first:
```
php hello-world.php > foo.txt
net use LPT1 \\server\printer
copy foo.txt LPT1
del foo.txt
```
If you have troubles at this point, then you should consult your OS and printer system documentation to try to find a working print command.
### Using a PrintConnector
To print receipts from PHP, use the most applicable [PrintConnector](https://github.com/mike42/escpos-php/tree/master/src/Mike42/Escpos/PrintConnectors) for your setup. The connector simply provides the plumbing to get data to the printer.
For example, a `NetworkPrintConnector` accepts an IP address and port:
```php
use Mike42\Escpos\PrintConnectors\NetworkPrintConnector;
use Mike42\Escpos\Printer;
$connector = new NetworkPrintConnector("10.x.x.x", 9100);
$printer = new Printer($connector);
try {
// ... Print stuff
} finally {
$printer -> close();
}
```
While a serial printer might use:
```php
use Mike42\Escpos\PrintConnectors\FilePrintConnector;
use Mike42\Escpos\Printer;
$connector = new FilePrintConnector("/dev/ttyS0");
$printer = new Printer($connector);
```
For each OS/interface combination that's supported, there are examples in the compatibility section of how a `PrintConnector` would be constructed. If you can't get a `PrintConnector` to work, then be sure to include the working print command in your issue.
### Using a CapabilityProfile
Support for commands and code pages varies between printer vendors and models. By default, the driver will accept UTF-8, and output commands that are suitable for Epson TM-series printers.
When trying out a new brand of printer, it's a good idea to use the "simple" `CapabilityProfile`, which instructs the driver to avoid the use of advanced features (generally simpler image handling, ASCII-only text).
```php
use Mike42\Escpos\PrintConnectors\WindowsPrintConnector;
use Mike42\Escpos\CapabilityProfile;
$profile = CapabilityProfile::load("simple");
$connector = new WindowsPrintConnector("smb://computer/printer");
$printer = new Printer($connector, $profile);
```
As another example, Star-branded printers use different commands:
```php
use Mike42\Escpos\PrintConnectors\WindowsPrintConnector;
use Mike42\Escpos\CapabilityProfile;
$profile = CapabilityProfile::load("SP2000")
$connector = new WindowsPrintConnector("smb://computer/printer");
$printer = new Printer($connector, $profile);
```
For a list of available profiles, or to have support for your printer improved, please see the upstream [receipt-print-hq/escpos-printer-db](https://github.com/receipt-print-hq/escpos-printer-db) project.
### Tips & examples
On Linux, your printer device file will be somewhere like `/dev/lp0` (parallel), `/dev/usb/lp1` (USB), `/dev/ttyUSB0` (USB-Serial), `/dev/ttyS0` (serial).
On Windows, the device files will be along the lines of `LPT1` (parallel) or `COM1` (serial). Use the `WindowsPrintConnector` to tap into system printing on Windows (eg. [Windows USB](https://github.com/mike42/escpos-php/tree/master/example/interface/windows-usb.php), [SMB](https://github.com/mike42/escpos-php/tree/master/example/interface/smb.php) or [Windows LPT](https://github.com/mike42/escpos-php/tree/master/example/interface/windows-lpt.php)) - this submits print jobs via a queue rather than communicating directly with the printer.
A complete real-world receipt can be found in the code of [Auth](https://github.com/mike42/Auth) in [ReceiptPrinter.php](https://github.com/mike42/Auth/blob/master/lib/misc/ReceiptPrinter.php). It includes justification, boldness, and a barcode.
Other examples are located in the [example/](https://github.com/mike42/escpos-php/blob/master/example/) directory.
## Available methods
### __construct(PrintConnector $connector, CapabilityProfile $profile)
Construct new print object.
Parameters:
- `PrintConnector $connector`: The PrintConnector to send data to.
- `CapabilityProfile $profile` Supported features of this printer. If not set, the "default" CapabilityProfile will be used, which is suitable for Epson printers.
See [example/interface/](https://github.com/mike42/escpos-php/tree/master/example/interface/) for ways to open connections for different platforms and interfaces.
### barcode($content, $type)
Print a barcode.
Parameters:
- `string $content`: The information to encode.
- `int $type`: The barcode standard to output. If not specified, `Printer::BARCODE_CODE39` will be used.
Currently supported barcode standards are (depending on your printer):
- `BARCODE_UPCA`
- `BARCODE_UPCE`
- `BARCODE_JAN13`
- `BARCODE_JAN8`
- `BARCODE_CODE39`
- `BARCODE_ITF`
- `BARCODE_CODABAR`
Note that some barcode standards can only encode numbers, so attempting to print non-numeric codes with them may result in strange behaviour.
### bitImage(EscposImage $image, $size)
See [graphics()](#graphicsescposimage-image-size) below.
### cut($mode, $lines)
Cut the paper.
Parameters:
- `int $mode`: Cut mode, either `Printer::CUT_FULL` or `Printer::CUT_PARTIAL`. If not specified, `Printer::CUT_FULL` will be used.
- `int $lines`: Number of lines to feed before cutting. If not specified, 3 will be used.
### feed($lines)
Print and feed line / Print and feed n lines.
Parameters:
- `int $lines`: Number of lines to feed
### feedForm()
Some printers require a form feed to release the paper. On most printers, this command is only useful in page mode, which is not implemented in this driver.
### feedReverse($lines)
Print and reverse feed n lines.
Parameters:
- `int $lines`: number of lines to feed. If not specified, 1 line will be fed.
### graphics(