README

本项目实现了 Epson ESC/POS 协议的热敏收款打印机子集。它允许您在兼容的打印机上生成并打印带有基本格式化、裁剪和条形码的收据。

该库是为了向任何 PHP 应用程序（包括基于 Web 的 POS 应用程序）添加对收据打印的即时支持而开发的。

兼容性

接口和操作系统

该驱动程序已知与以下操作系统/接口组合兼容

打印机

许多热敏收款打印机在一定程度上支持 ESC/POS。以下是一些已知与此驱动程序兼容的打印机

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（制造商未知）
EPOS TEP 220M
Elgin i9
Epson EU-T332C
Epson FX-890（需要 feedForm() 释放纸张）。
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（需要 release() 释放票据）。
Epson TM-U590 和 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（也作为 EC Line 5890x 销售）
Gainscha GP-U80300I（也作为 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（制造商未知）
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（也作为 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 系列
Xprinter XP-80C
Xprinter XP-90
XPrinter XP-Q20011
Xprinter XP-Q800
Zjiang NT-58H
Zjiang ZJ-5870
Zjiang ZJ-5890（许多供应商也作为 POS-5890 销售；ZJ-5890K，ZJ-5890T 也适用）。
Zjiang ZJ-8220（也作为 Excelvan ZJ-8220 销售）
Zjiang ZJ-8250

如果您使用任何其他带有此代码的打印机，请通过联系我们，以便将其添加到列表中。

基本用法

包含库

Composer

此库是为与PHP依赖关系管理器composer一起使用而设计的。只需添加mike42/escpos-php软件包即可开始使用

composer require mike42/escpos-php

如果您以前没有使用过composer，您可以在getcomposer.org上了解更多信息。

要求

该项目只有很少的硬依赖项

PHP 7.3或更高版本。
json扩展，用于加载捆绑的打印机定义（请参阅文档）
intl扩展，用于字符编码（请参阅文档）
zlib扩展，用于解压缩捆绑资源（请参阅文档）。

还建议您安装imagick或gd之一，因为这些可以用于加速图像处理。

可以通过添加一些可选扩展来启用更多特定功能。这些在composer.json的“建议”部分中描述。

“Hello World”收据

要使用此驱动程序，您的服务器（PHP安装的位置）必须能够与您的打印机通信。首先，生成一个简单的收据，并通过命令行将其发送到您的打印机。

<?php
/* Call this file 'hello-world.php' */
require __DIR__ . '/vendor/autoload.php';
use Mike42\Escpos\PrintConnectors\FilePrintConnector;
use Mike42\Escpos\Printer;
$connector = new FilePrintConnector("php://stdout");
$printer = new Printer($connector);
$printer -> text("Hello World!\n");
$printer -> cut();
$printer -> close();

以下是一些常见接口的示例。

使用netcat与具有以太网接口的打印机通信

php hello-world.php | nc 10.x.x.x. 9100

在Linux上通过usblp连接的USB本地打印机有一个设备文件（包括USB-并行接口）

php hello-world.php > /dev/usb/lp0

安装在本地cups服务器上的计算机通过lp或lpr访问

php hello-world.php > foo.txt
lpr -o raw -H localhost -P printer foo.txt

在Windows计算机上的本地或网络打印机被映射到一个文件，通常需要您首先共享打印机

php hello-world.php > foo.txt
net use LPT1 \\server\printer
copy foo.txt LPT1
del foo.txt

如果在这里遇到问题，则应查阅您的操作系统和打印机系统文档，以尝试找到可用的打印命令。

使用PrintConnector

要从PHP打印收据，请使用最适合您设置的PrintConnector。连接器只是提供将数据发送到打印机的管道。

例如，NetworkPrintConnector接受IP地址和端口号

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();
}

而串行打印机可能会使用

use Mike42\Escpos\PrintConnectors\FilePrintConnector;
use Mike42\Escpos\Printer;
$connector = new FilePrintConnector("/dev/ttyS0");
$printer = new Printer($connector);

对于每个支持的操作系统/接口组合，兼容性部分都有如何构建PrintConnector的示例。如果您无法使PrintConnector正常工作，请确保在问题中包含可用的打印命令。

使用CapabilityProfile

命令和代码页的支持因打印机厂商和型号而异。默认情况下，驱动程序将接受UTF-8，并输出适用于Epson TM系列打印机的命令。

当尝试使用新品牌的打印机时，使用“简单”的CapabilityProfile是一个好主意，这会指示驱动程序避免使用高级功能（通常为更简单的图像处理，仅ASCII文本）。

use Mike42\Escpos\PrintConnectors\WindowsPrintConnector;
use Mike42\Escpos\CapabilityProfile;
$profile = CapabilityProfile::load("simple");
$connector = new WindowsPrintConnector("smb://computer/printer");
$printer = new Printer($connector, $profile);

例如，Star品牌的打印机使用不同的命令

use Mike42\Escpos\PrintConnectors\WindowsPrintConnector;
use Mike42\Escpos\CapabilityProfile;
$profile = CapabilityProfile::load("SP2000")
$connector = new WindowsPrintConnector("smb://computer/printer");
$printer = new Printer($connector, $profile);

有关可用配置文件列表或要改进对您的打印机的支持，请参阅上游receipt-print-hq/escpos-printer-db项目。

技巧与示例

在Linux上，您的打印机设备文件将在类似/dev/lp0（并行）、/dev/usb/lp1（USB）、/dev/ttyUSB0（USB-串行）、/dev/ttyS0（串行）的位置。

在Windows系统中，设备文件将类似于LPT1（并行）或COM1（串行）。使用WindowsPrintConnector在Windows上访问系统打印（例如，Windows USB、SMB或Windows LPT）——这通过队列提交打印作业，而不是直接与打印机通信。

完整的实际收据可以在Auth的代码中找到，具体位置在ReceiptPrinter.php。它包括对齐、加粗和条形码。

其他示例位于example/目录中。

可用方法

__construct(PrintConnector $connector, CapabilityProfile $profile)

构建新的打印对象。

参数

PrintConnector $connector：发送数据到的打印连接器。
CapabilityProfile $profile：此打印机的支持功能。如果未设置，将使用“默认”功能配置文件，它适用于Epson打印机。

请参阅example/interface/，了解为不同平台和接口打开连接的方法。

barcode($content, $type)

打印条形码。

参数

string $content：要编码的信息。
int $type：输出的条形码标准。如果未指定，将使用Printer::BARCODE_CODE39。

目前支持以下条形码标准（取决于您的打印机）

BARCODE_UPCA
BARCODE_UPCE
BARCODE_JAN13
BARCODE_JAN8
BARCODE_CODE39
BARCODE_ITF
BARCODE_CODABAR

请注意，某些条形码标准只能编码数字，因此尝试使用它们打印非数字代码可能会导致奇怪的行为。

bitImage(EscposImage $image, $size)

请参阅下面的graphics()。

cut($mode, $lines)

切割纸张。

参数

int $mode：切割模式，可以是Printer::CUT_FULL或Printer::CUT_PARTIAL。如果未指定，将使用Printer::CUT_FULL。
int $lines：切割前馈纸的行数。如果未指定，将使用3行。

feed($lines)

打印并馈送一行/打印并馈送n行。

参数

int $lines：要馈送的行数

feedForm()

某些打印机需要表单馈送来释放纸张。在大多数打印机上，此命令仅在页面模式下有用，此驱动程序未实现。

feedReverse($lines)

打印并反向馈送n行。

参数

int $lines：要馈送的行数。如果未指定，则馈送1行。

graphics(EscposImage $image, $size)

将图像打印到打印机。

参数

EscposImage $img：要打印的图像。
int $size：图像输出大小修饰符。

大小修饰符是

IMG_DEFAULT（保持图像原始大小）
IMG_DOUBLE_WIDTH
IMG_DOUBLE_HEIGHT

一个最小示例

<?php
$img = EscposImage::load("logo.png");
$printer -> graphics($img);

请参阅example/文件夹中的详细示例。

函数bitImage()接受相同的参数，如果您的打印机不支持较新的图形命令，则可以使用它。作为额外的后备，还提供了bitImageColumnFormat()函数。

initialize()

初始化打印机。这会将格式重置为默认值。

pdf417Code($content, $width, $heightMultiplier, $dataColumnCount, $ec, $options)

使用PDF417标准打印二维数据代码。

参数

string $content: 要存储在代码中的文本或数字
number $width: 打印代码中模块的宽度（像素）。默认为3个点。
number $heightMultiplier: 模块高度的倍数。默认为宽度的3倍。
number $dataColumnCount: 要使用的数据列数。0（默认）表示自动计算。较小的数字会使代码变窄，从而可能实现更大的像素大小。较大的数字需要更小的像素大小。
real $ec: 错误纠正比率，范围从0.01到4.00。默认为0.10（10%）。
number $options: 标准代码 Printer::PDF417_STANDARD 带有起始/结束条，或截断代码 Printer::PDF417_TRUNCATED 仅带有起始条。

pulse($pin, $on_ms, $off_ms)

生成脉冲，用于打开连接的现金抽屉。默认设置（0, 120, 240）应打开Epson抽屉。

参数

int $pin: 0或1，分别对应于2号引脚或5号踢出连接器。
int $on_ms: 脉冲开启时间，以毫秒为单位。
int $off_ms: 脉冲关闭时间，以毫秒为单位。

qrCode($content, $ec, $size, $model)

在打印机上打印指定数据为QR码。

string $content: 代码的内容。数值数据将更有效地压缩。
int $ec 要使用的错误纠正级别。可以是 Printer::QR_ECLEVEL_L（默认）、Printer::QR_ECLEVEL_M、Printer::QR_ECLEVEL_Q 或 Printer::QR_ECLEVEL_H。较高的错误纠正会导致代码密度较低。
int $size: 要使用的像素大小。必须是1-16（默认3）。
int $model: 要使用的QR码模型。必须是 Printer::QR_MODEL_1、Printer::QR_MODEL_2（默认）或 Printer::QR_MICRO（并非所有打印机都支持）。

selectPrintMode($mode)

选择打印模式。

参数

int $mode: 要使用的模式。默认为 Printer::MODE_FONT_A，不带特殊格式。这类似于运行 initialize()。

可以将几个 MODE_* 常量进行按位或运算，并将结果传递给此函数的 $mode 参数。有效的模式包括

MODE_FONT_A
MODE_FONT_B
MODE_EMPHASIZED
MODE_DOUBLE_HEIGHT
MODE_DOUBLE_WIDTH
MODE_UNDERLINE

setBarcodeHeight($height)

设置条形码高度。

参数

int $height: 以点为单位的高度。如果未指定，则使用8。

setBarcodeWidth($width)

设置条形码条宽度。

参数

int $width: 以点为单位的条宽度。如果未指定，则使用3。值大于6似乎没有效果。

setColor($color)

选择打印颜色 - 在支持多色的打印机上。

参数

int $color: 要使用的颜色。必须是 Printer::COLOR_1（默认）或 Printer::COLOR_2

setDoubleStrike($on)

打开/关闭双击模式。

参数

boolean $on: true表示双击，false表示无双击。

setEmphasis($on)

打开/关闭强调模式。

参数

boolean $on: true表示强调，false表示无强调。

setFont($font)

选择字体。大多数打印机有两种字体（字体A和字体B），某些打印机有第三种（字体C）。

参数

int $font: 要使用的字体。必须是 Printer::FONT_A、Printer::FONT_B 或 Printer::FONT_C。

setJustification($justification)

选择对齐方式。

参数

int $justification: 可以是 Printer::JUSTIFY_LEFT、Printer::JUSTIFY_CENTER 或 Printer::JUSTIFY_RIGHT。

setLineSpacing($height)

设置行高。

某些打印机允许您通过较小的换行符重叠行。

参数

int $height: 每行的高度，以点为单位。如果未设置，则打印机将重置到默认行间距。

setPrintLeftMargin($margin)

设置打印区域左边距。通过 Printer::initialize() 重置为默认值。

参数

int $margin: 要设置到打印区域的左边距，以点为单位。

setPrintWidth($width)

设置打印区域宽度。这可以用来在打印区域添加右边距。通过 Printer::initialize() 重置为默认值。

参数

int $width: 页面打印区域的宽度，以点为单位。

setReverseColors($on)

设置黑白反转模式开启或关闭。在此模式下，文本以白色打印在黑色背景上。

参数

boolean $on：设置为true以启用，设置为false以禁用。

setTextSize($widthMultiplier, $heightMultiplier)

设置文本大小，以正常大小的倍数表示。

参数

int $widthMultiplier：要使用的常规高度的倍数（范围1-8）。
int $heightMultiplier：要使用的常规高度的倍数（范围1-8）。

setUnderline($underline)

设置打印文本的下划线。

参数

int $underline：可以是true/false，或者是Printer::UNDERLINE_NONE、Printer::UNDERLINE_SINGLE或Printer::UNDERLINE_DOUBLE之一。默认为Printer::UNDERLINE_SINGLE。

text($str)

将文本添加到缓冲区。文本应后跟换行符，或在之后调用feed()。

参数

string $str：要打印的字符串。

其他说明

为学习如何使用收据打印机的人写的帖子

什么是ESC/POS，我如何使用它？，该文档记录了example/demo.php的输出。
设置Epson收据打印机
在Linux上使USB收据打印机工作

开发

此代码是MIT许可的，鼓励您将任何修改贡献回项目。

对于开发，建议您加载imagick、gd和Xdebug PHP扩展。

测试在Travis CI上执行，使用PHP 7.3、7.4和8.0。当前版本不支持PHP的旧版本，也不支持HHVM。

使用composer获取此代码的副本并加载依赖项

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

通过phpunit执行单元测试

php vendor/bin/phpunit --coverage-text

此项目使用PSR-2标准，可以通过PHP_CodeSniffer进行检查

php vendor/bin/phpcs --standard=psr2 src/ -n

开发者文档是用doxygen构建的。重新构建它们以检查文档警告

make -C doc clean && make -C doc

欢迎提出拉取请求和错误报告。

mike42 / escpos-php

维护者

详细信息