1# ESC/POS Print Driver for PHP 2[](https://travis-ci.org/mike42/escpos-php) [](https://packagist.org/packages/mike42/escpos-php) 3[](https://packagist.org/packages/mike42/escpos-php) 4[](https://packagist.org/packages/mike42/escpos-php) 5[](https://coveralls.io/github/mike42/escpos-php?branch=development) 6 7This 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. 8 9The library was developed to add drop-in support for receipt printing to any PHP app, including web-based point-of-sale (POS) applications. 10 11## Compatibility 12 13### Interfaces and operating systems 14This driver is known to work with the following OS/interface combinations: 15 16<table> 17<tr> 18<th> </th> 19<th>Linux</th> 20<th>Mac</th> 21<th>Windows</th> 22</tr> 23<tr> 24<th>Ethernet</th> 25<td><a href="https://github.com/mike42/escpos-php/tree/master/example/interface/ethernet.php">Yes</a></td> 26<td><a href="https://github.com/mike42/escpos-php/tree/master/example/interface/ethernet.php">Yes</a></td> 27<td><a href="https://github.com/mike42/escpos-php/tree/master/example/interface/ethernet.php">Yes</a></td> 28</tr> 29<tr> 30<th>USB</th> 31<td><a href="https://github.com/mike42/escpos-php/tree/master/example/interface/linux-usb.php">Yes</a></td> 32<td>Not tested</td> 33<td><a href="https://github.com/mike42/escpos-php/tree/master/example/interface/windows-usb.php">Yes</a></td> 34</tr> 35<tr> 36<th>USB-serial</th> 37<td>Yes</td> 38<td>Yes</td> 39<td>Yes</td> 40</tr> 41<tr> 42<th>Serial</th> 43<td>Yes</td> 44<td>Yes</td> 45<td>Yes</td> 46</tr> 47<tr> 48<th>Parallel</th> 49<td><a href="https://github.com/mike42/escpos-php/tree/master/example/interface/windows-lpt.php">Yes</a></td> 50<td>Not tested</td> 51<td>Yes</td> 52</tr> 53<tr> 54<th>SMB shared</th> 55<td><a href="https://github.com/mike42/escpos-php/tree/master/example/interface/smb.php">Yes</a></td> 56<td>No</td> 57<td><a href="https://github.com/mike42/escpos-php/tree/master/example/interface/smb.php">Yes</a></td> 58</tr> 59<tr> 60<th>CUPS hosted</th> 61<td><a href="https://github.com/mike42/escpos-php/tree/master/example/interface/cups.php">Yes</a></td> 62<td><a href="https://github.com/mike42/escpos-php/tree/master/example/interface/cups.php">Yes</a></td> 63<td>No</td> 64</tr> 65</table> 66 67### Printers 68Many thermal receipt printers support ESC/POS to some degree. This driver has been known to work with: 69 70- 3nStar RPT-008 71- Approx APPPOS80AM 72- AURES ODP-333 73- AURES ODP-500 74- Bematech-4200-TH 75- Bematech LR2000E 76- Birch PRP-085III 77- Bixolon SRP-350III 78- Bixolon SRP-350Plus 79- Black Copper BC-85AC 80- CHD TH-305N 81- Citizen CBM1000-II 82- Citizen CT-S310II 83- Dapper-Geyi Q583P 84- Daruma DR800 85- DR-MP200 (manufacturer unknown) 86- EPOS TEP 220M 87- Elgin i9 88- Epson EU-T332C 89- Epson FX-890 (requires `feedForm()` to release paper). 90- Epson TM-T20 91- Epson TM-T20II 92- Epson TM-T70 93- Epson TM-T70II 94- Epson TM-T81 95- Epson TM-T82II 96- Epson TM-T88II 97- Epson TM-T88III 98- Epson TM-T88IV 99- Epson TM-T88V 100- Epson TM-U220 101- Epson TM-U295 (requires `release()` to release slip). 102- Epson TM-U590 and TM-U590P 103- Equal (EQ-IT-001) POS-58 104- Everycom EC-58 105- Excelvan HOP-E200 106- Excelvan HOP-E58 107- Excelvan HOP-E801 108- Gainscha GP-2120TF 109- Gainscha GP-5890x (Also marketed as EC Line 5890x) 110- Gainscha GP-U80300I (Also marketed as gprinter GP-U80300I) 111- gprinter GP-U80160I 112- HOIN HOP-H58 113- Ithaca iTherm 28 114- Hasar HTP 250 115- Metapace T-1 116- Metapace T-25 117- Nexa PX700 118- Nyear NP100 119- OKI RT322 120- OKI 80 Plus III 121- Orient BTP-R580 122- P-822D 123- P85A-401 (make unknown) 124- Partner Tech RP320 125- POSLIGNE ODP200H-III-G 126- QPOS Q58M 127- Rongta RP326US 128- Rongta RP58-U 129- Rongta RP80USE 130- SAM4S GIANT-100DB 131- Senor TP-100 132- Sewoo SLK-TS400 133- SEYPOS PRP-96 134- SEYPOS PRP-300 (Also marketed as TYSSO PRP-300) 135- SNBC BTP-R880NPIII 136- Solux SX-TP-88300 137- Sicar POS-80 138- Silicon SP-201 / RP80USE 139- SPRT SP-POS88V 140- Star BSC10 141- Star TSP100 ECO 142- Star TSP100III FuturePRNT 143- Star TSP-650 144- Star TUP-592 145- TVS RP45 Shoppe 146- Venus V248T 147- Xeumior SM-8330 148- Xprinter F-900 149- Xprinter XP-365B 150- Xprinter XP-58 Series 151- Xprinter XP-80C 152- Xprinter XP-90 153- XPrinter XP-Q20011 154- Xprinter XP-Q800 155- Zjiang NT-58H 156- Zjiang ZJ-5870 157- Zjiang ZJ-5890 (Also sold as POS-5890 by many vendors; ZJ-5890K, ZJ-5890T also work). 158- Zjiang ZJ-8220 (Also marketed as Excelvan ZJ-8220) 159- Zjiang ZJ-8250 160 161If 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. 162 163## Basic usage 164 165### Include the library 166 167#### Composer 168If you are using composer, then add `mike42/escpos-php` as a dependency: 169 170```bash 171composer require mike42/escpos-php 172``` 173 174In this case, you would include composer's auto-loader at the top of your source files: 175 176```php 177<?php 178require __DIR__ . '/vendor/autoload.php'; 179``` 180 181#### Manually 182If you don't have composer available, then simply download the code and include `autoload.php`: 183 184```bash 185git clone https://github.com/mike42/escpos-php vendor/mike42/escpos-php 186``` 187 188```php 189<?php 190require __DIR__ . '/vendor/mike42/escpos-php/autoload.php'; 191``` 192 193#### Requirements 194 195To maintain compatibility with as many systems as possible, this driver has few 196hard dependencies: 197 198- PHP 5.4 or above. 199- `mbstring` extension, since the driver accepts UTF-8 encoding. 200 201It is also suggested that you install either `imagick` or `gd`, so that you can 202print images. 203 204A number of optional packages can be added to enable more specific features. These 205are described in the "suggest" section of [composer.json](https://github.com/mike42/escpos-php/tree/master/composer.json). 206 207### The 'Hello World' receipt 208 209To 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. 210 211```php 212<?php 213/* Call this file 'hello-world.php' */ 214require __DIR__ . '/vendor/autoload.php'; 215use Mike42\Escpos\PrintConnectors\FilePrintConnector; 216use Mike42\Escpos\Printer; 217$connector = new FilePrintConnector("php://stdout"); 218$printer = new Printer($connector); 219$printer -> text("Hello World!\n"); 220$printer -> cut(); 221$printer -> close(); 222``` 223 224Some examples are below for common interfaces. 225 226Communicate with a printer with an Ethernet interface using `netcat`: 227 228```bash 229php hello-world.php | nc 10.x.x.x. 9100 230``` 231 232A USB local printer connected with `usblp` on Linux has a device file (Includes USB-parallel interfaces): 233 234```bash 235php hello-world.php > /dev/usb/lp0 236``` 237 238A computer installed into the local `cups` server is accessed through `lp` or `lpr`: 239 240```bash 241php hello-world.php > foo.txt 242lpr -o raw -H localhost -P printer foo.txt 243``` 244 245A local or networked printer on a Windows computer is mapped in to a file, and generally requires you to share the printer first: 246 247``` 248php hello-world.php > foo.txt 249net use LPT1 \\server\printer 250copy foo.txt LPT1 251del foo.txt 252``` 253 254If you have troubles at this point, then you should consult your OS and printer system documentation to try to find a working print command. 255 256### Using a PrintConnector 257 258To 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. 259 260For example, a `NetworkPrintConnector` accepts an IP address and port: 261 262```php 263use Mike42\Escpos\PrintConnectors\NetworkPrintConnector; 264use Mike42\Escpos\Printer; 265$connector = new NetworkPrintConnector("10.x.x.x", 9100); 266$printer = new Printer($connector); 267try { 268 // ... Print stuff 269} finally { 270 $printer -> close(); 271} 272``` 273 274While a serial printer might use: 275```php 276use Mike42\Escpos\PrintConnectors\FilePrintConnector; 277use Mike42\Escpos\Printer; 278$connector = new FilePrintConnector("/dev/ttyS0"); 279$printer = new Printer($connector); 280``` 281 282For 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 bug. 283 284### Using a CapabilityProfile 285 286Support 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. 287 288When 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). 289 290```php 291use Mike42\Escpos\PrintConnectors\WindowsPrintConnector; 292use Mike42\Escpos\CapabilityProfile; 293$profile = CapabilityProfile::load("simple"); 294$connector = new WindowsPrintConnector("smb://computer/printer"); 295$printer = new Printer($connector, $profile); 296``` 297 298As another example, Star-branded printers use different commands: 299 300```php 301use Mike42\Escpos\PrintConnectors\WindowsPrintConnector; 302use Mike42\Escpos\CapabilityProfile; 303$profile = CapabilityProfile::load("SP2000") 304$connector = new WindowsPrintConnector("smb://computer/printer"); 305$printer = new Printer($connector, $profile); 306``` 307 308For 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. 309 310### Tips & examples 311On Linux, your printer device file will be somewhere like `/dev/lp0` (parallel), `/dev/usb/lp1` (USB), `/dev/ttyUSB0` (USB-Serial), `/dev/ttyS0` (serial). 312 313On 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. 314 315A 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. 316 317Other examples are located in the [example/](https://github.com/mike42/escpos-php/blob/master/example/) directory. 318 319## Available methods 320 321### __construct(PrintConnector $connector, CapabilityProfile $profile) 322Construct new print object. 323 324Parameters: 325- `PrintConnector $connector`: The PrintConnector to send data to. 326- `CapabilityProfile $profile` Supported features of this printer. If not set, the "default" CapabilityProfile will be used, which is suitable for Epson printers. 327 328See [example/interface/](https://github.com/mike42/escpos-php/tree/master/example/interface/) for ways to open connections for different platforms and interfaces. 329 330### barcode($content, $type) 331Print a barcode. 332 333Parameters: 334 335- `string $content`: The information to encode. 336- `int $type`: The barcode standard to output. If not specified, `Printer::BARCODE_CODE39` will be used. 337 338Currently supported barcode standards are (depending on your printer): 339 340- `BARCODE_UPCA` 341- `BARCODE_UPCE` 342- `BARCODE_JAN13` 343- `BARCODE_JAN8` 344- `BARCODE_CODE39` 345- `BARCODE_ITF` 346- `BARCODE_CODABAR` 347 348Note that some barcode standards can only encode numbers, so attempting to print non-numeric codes with them may result in strange behaviour. 349 350### bitImage(EscposImage $image, $size) 351See [graphics()](#graphicsescposimage-image-size) below. 352 353### cut($mode, $lines) 354Cut the paper. 355 356Parameters: 357 358- `int $mode`: Cut mode, either `Printer::CUT_FULL` or `Printer::CUT_PARTIAL`. If not specified, `Printer::CUT_FULL` will be used. 359- `int $lines`: Number of lines to feed before cutting. If not specified, 3 will be used. 360 361### feed($lines) 362Print and feed line / Print and feed n lines. 363 364Parameters: 365 366- `int $lines`: Number of lines to feed 367 368### feedForm() 369Some 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. 370 371### feedReverse($lines) 372Print and reverse feed n lines. 373 374Parameters: 375 376- `int $lines`: number of lines to feed. If not specified, 1 line will be fed. 377 378### graphics(EscposImage $image, $size) 379Print an image to the printer. 380 381Parameters: 382 383- `EscposImage $img`: The image to print. 384- `int $size`: Output size modifier for the image. 385 386Size modifiers are: 387 388- `IMG_DEFAULT` (leave image at original size) 389- `IMG_DOUBLE_WIDTH` 390- `IMG_DOUBLE_HEIGHT` 391 392A minimal example: 393 394```php 395<?php 396$img = EscposImage::load("logo.png"); 397$printer -> graphics($img); 398``` 399 400See the [example/](https://github.com/mike42/escpos-php/blob/master/example/) folder for detailed examples. 401 402The function [bitImage()](#bitimageescposimage-image-size) takes the same parameters, and can be used if your printer doesn't support the newer graphics commands. As an additional fallback, the `bitImageColumnFormat()` function is also provided. 403 404### initialize() 405Initialize printer. This resets formatting back to the defaults. 406 407### pdf417Code($content, $width, $heightMultiplier, $dataColumnCount, $ec, $options) 408Print a two-dimensional data code using the PDF417 standard. 409 410Parameters: 411 412- `string $content`: Text or numbers to store in the code 413- `number $width`: Width of a module (pixel) in the printed code. Default is 3 dots. 414- `number $heightMultiplier`: Multiplier for height of a module. Default is 3 times the width. 415- `number $dataColumnCount`: Number of data columns to use. 0 (default) is to auto-calculate. Smaller numbers will result in a narrower code, making larger pixel sizes possible. Larger numbers require smaller pixel sizes. 416- `real $ec`: Error correction ratio, from 0.01 to 4.00. Default is 0.10 (10%). 417- `number $options`: Standard code `Printer::PDF417_STANDARD` with start/end bars, or truncated code `Printer::PDF417_TRUNCATED` with start bars only. 418 419### pulse($pin, $on_ms, $off_ms) 420Generate a pulse, for opening a cash drawer if one is connected. The default settings (0, 120, 240) should open an Epson drawer. 421 422Parameters: 423 424- `int $pin`: 0 or 1, for pin 2 or pin 5 kick-out connector respectively. 425- `int $on_ms`: pulse ON time, in milliseconds. 426- `int $off_ms`: pulse OFF time, in milliseconds. 427 428### qrCode($content, $ec, $size, $model) 429Print the given data as a QR code on the printer. 430 431- `string $content`: The content of the code. Numeric data will be more efficiently compacted. 432- `int $ec` Error-correction level to use. One of `Printer::QR_ECLEVEL_L` (default), `Printer::QR_ECLEVEL_M`, `Printer::QR_ECLEVEL_Q` or `Printer::QR_ECLEVEL_H`. Higher error correction results in a less compact code. 433- `int $size`: Pixel size to use. Must be 1-16 (default 3) 434- `int $model`: QR code model to use. Must be one of `Printer::QR_MODEL_1`, `Printer::QR_MODEL_2` (default) or `Printer::QR_MICRO` (not supported by all printers). 435 436### selectPrintMode($mode) 437Select print mode(s). 438 439Parameters: 440 441- `int $mode`: The mode to use. Default is `Printer::MODE_FONT_A`, with no special formatting. This has a similar effect to running `initialize()`. 442 443Several MODE_* constants can be OR'd together passed to this function's `$mode` argument. The valid modes are: 444 445- `MODE_FONT_A` 446- `MODE_FONT_B` 447- `MODE_EMPHASIZED` 448- `MODE_DOUBLE_HEIGHT` 449- `MODE_DOUBLE_WIDTH` 450- `MODE_UNDERLINE` 451 452### setBarcodeHeight($height) 453Set barcode height. 454 455Parameters: 456 457- `int $height`: Height in dots. If not specified, 8 will be used. 458 459### setBarcodeWidth($width) 460Set barcode bar width. 461 462Parameters: 463 464- `int $width`: Bar width in dots. If not specified, 3 will be used. Values above 6 appear to have no effect. 465 466### setColor($color) 467Select print color - on printers that support multiple colors. 468 469Parameters: 470 471- `int $color`: Color to use. Must be either `Printer::COLOR_1` (default), or `Printer::COLOR_2` 472 473### setDoubleStrike($on) 474Turn double-strike mode on/off. 475 476Parameters: 477 478- `boolean $on`: true for double strike, false for no double strike. 479 480### setEmphasis($on) 481Turn emphasized mode on/off. 482 483Parameters: 484 485- `boolean $on`: true for emphasis, false for no emphasis. 486 487### setFont($font) 488Select font. Most printers have two fonts (Fonts A and B), and some have a third (Font C). 489 490Parameters: 491 492- `int $font`: The font to use. Must be either `Printer::FONT_A`, `Printer::FONT_B`, or `Printer::FONT_C`. 493 494### setJustification($justification) 495Select justification. 496 497Parameters: 498 499- `int $justification`: One of `Printer::JUSTIFY_LEFT`, `Printer::JUSTIFY_CENTER`, or `Printer::JUSTIFY_RIGHT`. 500 501### setLineSpacing($height) 502 503Set the height of the line. 504 505Some printers will allow you to overlap lines with a smaller line feed. 506 507Parameters: 508 509- `int $height`: The height of each line, in dots. If not set, the printer will reset to its default line spacing. 510 511### setPrintLeftMargin($margin) 512 513Set print area left margin. Reset to default with `Printer::initialize()`. 514 515Parameters: 516 517- `int $margin`: The left margin to set on to the print area, in dots. 518 519### setPrintWidth($width) 520 521Set print area width. This can be used to add a right margin to the print area. Reset to default with `Printer::initialize()`. 522 523Parameters: 524 525- `int $width`: The width of the page print area, in dots. 526 527### setReverseColors($on) 528Set black/white reverse mode on or off. In this mode, text is printed white on a black background. 529 530Parameters: 531 532- `boolean $on`: True to enable, false to disable. 533 534### setTextSize($widthMultiplier, $heightMultiplier) 535Set the size of text, as a multiple of the normal size. 536 537Parameters: 538 539- `int $widthMultiplier`: Multiple of the regular height to use (range 1 - 8). 540- `int $heightMultiplier`: Multiple of the regular height to use (range 1 - 8). 541 542### setUnderline($underline) 543Set underline for printed text. 544 545Parameters: 546 547- `int $underline`: Either `true`/`false`, or one of `Printer::UNDERLINE_NONE`, `Printer::UNDERLINE_SINGLE` or `Printer::UNDERLINE_DOUBLE`. Defaults to `Printer::UNDERLINE_SINGLE`. 548 549### text($str) 550Add text to the buffer. Text should either be followed by a line-break, or `feed()` should be called after this. 551 552Parameters: 553 554- `string $str`: The string to print. 555 556# Further notes 557Posts I've written up for people who are learning how to use receipt printers: 558 559* [What is ESC/POS, and how do I use it?](https://mike42.me/blog/what-is-escpos-and-how-do-i-use-it), which documents the output of `example/demo.php`. 560* [Setting up an Epson receipt printer](https://mike42.me/blog/2014-20-26-setting-up-an-epson-receipt-printer) 561* [Getting a USB receipt printer working on Linux](https://mike42.me/blog/2015-03-getting-a-usb-receipt-printer-working-on-linux) 562 563# Development 564 565This code is MIT licensed, and you are encouraged to contribute any modifications back to the project. 566 567For development, it's suggested that you load `imagick`, `gd` and `Xdebug` PHP exensions, and install `composer`. 568 569The tests are executed on [Travis CI](https://travis-ci.org/mike42/escpos-php) over PHP 5.4, 5.5, 5.6, 7.0, 7.1 and 7.2, plus the latest LTS version of HHVM, 3.21. Older versions of PHP are not supported in current releases. 570 571Fetch a copy of this code and load dependencies with composer: 572 573 git clone https://github.com/mike42/escpos-php 574 cd escpos-php/ 575 composer install 576 577Execute unit tests via `phpunit`: 578 579 php vendor/bin/phpunit --coverage-text 580 581This project uses the PSR-2 standard, which can be checked via [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer): 582 583 php vendor/bin/phpcs --standard=psr2 src/ -n 584 585The developer docs are build with [doxygen](https://github.com/doxygen/doxygen). Re-build them to check for documentation warnings: 586 587 make -C doc clean && make -C doc 588 589Pull requests and bug reports welcome. 590
){kind=link}
){kind=link}
