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.
A "hello world" receipt can be generated easily (Call this hello-world.php
):
<?php
require_once(dirname(__FILE__) . "/Escpos.php");
$printer = new Escpos();
$printer -> text("Hello World!\n");
$printer -> cut();
$printer -> close();
This would be printed as:
# Networked printer
php hello-world.php | nc 10.x.x.x. 9100
# Local printer
php hello-world.php > /dev/...
# Windows local printer
php hello-world.php > foo.txt
net use LPT1 \\server\printer
copy foo.txt LPT1
del foo.txt
From your web app, you could pass the output directly to a socket if your printer is networked:
<?php
require_once(dirname(__FILE__) . "/Escpos.php");
$connector = new NetworkPrintConnector("10.x.x.x", 9100);
$printer = new Escpos($connector);
$printer -> text("Hello World!\n");
$printer -> cut();
$printer -> close();
Or to a local printer:
<?php
require_once(dirname(__FILE__) . "/Escpos.php");
$connector = new FilePrintConnector("/dev/ttyS0");
$printer = new Escpos($connector);
$printer -> text("Hello World!\n");
$printer -> cut();
$printer -> close();
The library should be initialised with a PrintConnector, which will pass on the data to your printer. Use the table under "Compatibility", or the examples below to choose the appropriate connector for your platform & interface. If no connector is specified, then standard output is used.
When you have finished using the print object, call close()
to finalize any data transfers.
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, SMB or Windows LPT) - 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 in ReceiptPrinter.php. It includes justification, boldness, and a barcode.
Other examples are located in the example/ directory.
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 |
Many thermal receipt printers support ESC/POS to some degree. This driver has been known to work with:
- EPOS TEP 220M
- Epson TM-T88III
- Epson TM-T88IV
- Epson TM-T70
- Epson TM-T82II
- Epson TM-T20
- Epson TM-T70II
- Epson TM-U220
- Epson FX-890 (requires
feedForm()
to release paper). - Okipos 80 Plus III
- P-822D
- SEYPOS PRP-300 (Also marketed as TYSSO PRP-300)
- Star TSP-650
- Star TUP-592
- Xprinter XP-Q800
- Zijang NT-58H
- Zijang ZJ-5870
- Zijang ZJ-5890T (Marketed as POS 5890T)
If you use any other printer with this code, please let me know so I can add it to the list.
Construct new print object.
Parameters:
PrintConnector $connector
: The PrintConnector to send data to. If not set, output is sent to standard output.AbstractCapabilityProfile $profile
Supported features of this printer. If not set, the DefaultCapabilityProfile will be used, which is suitable for Epson printers.
See example/interface/ for ways to open connections for different platforms and interfaces.
Print a barcode.
Parameters:
string $content
: The information to encode.int $type
: The barcode standard to output. If not specified,Escpos::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.
See graphics() below.
Cut the paper.
Parameters:
int $mode
: Cut mode, eitherEscpos::CUT_FULL
orEscpos::CUT_PARTIAL
. If not specified,Escpos::CUT_FULL
will be used.int $lines
: Number of lines to feed before cutting. If not specified, 3 will be used.
Print and feed line / Print and feed n lines.
Parameters:
int $lines
: Number of lines to feed
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.
Print and reverse feed n lines.
Parameters:
int $lines
: number of lines to feed. If not specified, 1 line will be fed.
Print an image to the printer.
Parameters:
EscposImage $img
: The image to print.int $size
: Output size modifier for the image.
Size modifiers are:
IMG_DEFAULT
(leave image at original size)IMG_DOUBLE_WIDTH
IMG_DOUBLE_HEIGHT
A minimal example:
<?php
$img = new EscposImage("logo.png");
$printer -> graphics($img);
See the example/ folder for detailed examples.
The function bitImage() takes the same parameters, and can be used if your printer doesn't support the newer graphics commands.
Initialize printer. This resets formatting back to the defaults.
Generate a pulse, for opening a cash drawer if one is connected. The default settings (0, 120, 240) should open an Epson drawer.
Parameters:
int $pin
: 0 or 1, for pin 2 or pin 5 kick-out connector respectively.int $on_ms
: pulse ON time, in milliseconds.int $off_ms
: pulse OFF time, in milliseconds.
Print the given data as a QR code on the printer.
string $content
: The content of the code. Numeric data will be more efficiently compacted.int $ec
Error-correction level to use. One ofEscpos::QR_ECLEVEL_L
(default),Escpos::QR_ECLEVEL_M
,Escpos::QR_ECLEVEL_Q
orEscpos::QR_ECLEVEL_H
. Higher error correction results in a less compact code.int $size
: Pixel size to use. Must be 1-16 (default 3)int $model
: QR code model to use. Must be one ofEscpos::QR_MODEL_1
,Escpos::QR_MODEL_2
(default) orEscpos::QR_MICRO
(not supported by all printers).
Select print mode(s).
Parameters:
int $mode
: The mode to use. Default isEscpos::MODE_FONT_A
, with no special formatting. This has a similar effect to runninginitialize()
.
Several MODE_* constants can be OR'd together passed to this function's $mode
argument. The valid modes are:
MODE_FONT_A
MODE_FONT_B
MODE_EMPHASIZED
MODE_DOUBLE_HEIGHT
MODE_DOUBLE_WIDTH
MODE_UNDERLINE
Set barcode height.
Parameters:
int $height
: Height in dots. If not specified, 8 will be used.
Turn double-strike mode on/off.
Parameters:
boolean $on
: true for double strike, false for no double strike.
Turn emphasized mode on/off.
Parameters:
boolean $on
: true for emphasis, false for no emphasis.
Select font. Most printers have two fonts (Fonts A and B), and some have a third (Font C).
Parameters:
int $font
: The font to use. Must be eitherEscpos::FONT_A
,Escpos::FONT_B
, orEscpos::FONT_C
.
Select justification.
Parameters:
int $justification
: One ofEscpos::JUSTIFY_LEFT
,Escpos::JUSTIFY_CENTER
, orEscpos::JUSTIFY_RIGHT
.
Set black/white reverse mode on or off. In this mode, text is printed white on a black background.
Parameters:
boolean $on
: True to enable, false to disable.
Set the size of text, as a multiple of the normal size.
Parameters:
int $widthMultiplier
: Multiple of the regular height to use (range 1 - 8).int $heightMultiplier
: Multiple of the regular height to use (range 1 - 8).
Set underline for printed text.
Parameters:
int $underline
: Eithertrue
/false
, or one ofEscpos::UNDERLINE_NONE
,Escpos::UNDERLINE_SINGLE
orEscpos::UNDERLINE_DOUBLE
. Defaults toEscpos::UNDERLINE_SINGLE
.
Add text to the buffer. Text should either be followed by a line-break, or feed()
should be called after this.
Parameters:
string $str
: The string to print.
Posts I've written up for people who are learning how to use receipt printers:
- What is ESC/POS, and how do I use it?, which documents the output of test.php.
- Setting up an Epson receipt printer
- Getting a USB receipt printer working on Linux
Some forks of this project have been developed by others for specific use cases. Improvements from the following projects have been incorporated into escpos-php:
Epson notes that not all of its printers support all ESC/POS features, and includes a table in their documentation:
Note that many printers produced by other vendors use the same standard, and are compatible by varying degrees.