README

此项目实现了Epson的ESC/POS协议的一部分，用于热敏收据打印机。它允许您在兼容的打印机上生成和打印具有基本格式、剪切和条形码的收据。

此库的开发是为了向任何PHP应用程序添加收据打印的即插即用支持，包括基于Web的点-of-销售（POS）应用程序。

兼容性

接口和操作系统

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

打印机

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

• Bematech-4200-TH

基本用法

包含库

Composer

如果您使用Composer，则将 grupocoqueiro/escpos-php 添加为依赖项

composer require grupocoqueiro/escpos-php

在这种情况下，您需要在源文件顶部包含Composer的自动加载器

<?php
require __DIR__ . '/vendor/autoload.php';

手动

如果您没有Composer，则只需下载代码并包含 autoload.php

git clone https://github.com/grupocoqueiro/escpos-php vendor/grupocoqueiro/escpos-php

<?php
require __DIR__ . '/vendor/grupocoqueiro/escpos-php/autoload.php';

要求

为了与尽可能多的系统保持兼容，此驱动程序只有少量硬依赖项

• PHP 7或更高版本。
• 需要 mbstring 扩展，因为驱动程序接受UTF-8编码。

还建议您安装 imagick 或 gd，以便您可以打印图像。

可以添加一些可选包以启用更具体的功能。这些在composer.json的“建议”部分中描述。

“Hello World”收据

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

<?php
/* Call this file 'hello-world.php' */
require __DIR__ . '/vendor/autoload.php';
use grupocoqueiro\Escpos\PrintConnectors\FilePrintConnector;
use grupocoqueiro\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 grupocoqueiro\Escpos\PrintConnectors\NetworkPrintConnector;
use grupocoqueiro\Escpos\Printer;
$connector = new NetworkPrintConnector("10.x.x.x", 9100);
$printer = new Printer($connector);
try {
    // ... Print stuff
} finally {
    $printer -> close();
}

而串行打印机可能会使用

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

对于每个支持的操作系统/界面组合，兼容性部分都有如何构建 PrintConnector 的示例。如果您无法使 PrintConnector 正常工作，请确保在错误报告中包含有效的打印命令。

使用 CapabilityProfile

命令和代码页的兼容性因打印机制造商和型号而异。默认情况下，驱动程序将接受 UTF-8，并输出适合 Epson TM 系列打印机的命令。

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

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

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

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

可用方法

__construct(PrintConnector $connector, CapabilityProfile $profile)

构造新的打印对象。

参数

• PrintConnector $connector: 要发送数据的 PrintConnector。
• CapabilityProfile $profile 此打印机的支持功能。如果未设置，将使用“默认”CapabilityProfile，它适用于 Epson 打印机。

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的输出。
• 设置爱普生收据打印机
• 在Linux上让USB收据打印机工作

开发

此代码为MIT许可证，鼓励您将任何修改反馈到项目中。

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

测试在 Travis CI 上执行，覆盖 PHP 5.4、5.5、5.6、7.0、7.1 和 7.2，以及 HHVM 的最新 LTS 版本 3.21。当前版本不支持旧版本的 PHP。

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

git clone https://github.com/grupocoqueiro/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

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