escpos php
v4.0
Этот проект реализует подмножество протокола ESC/POS компании Epson для термопринтеров чеков. Он позволяет создавать и печатать квитанции с базовым форматированием, обрезкой и штрих-кодами на совместимом принтере.
Библиотека была разработана для добавления поддержки печати чеков в любое приложение PHP, включая веб-приложения для торговых точек (POS).
Известно, что этот драйвер работает со следующими комбинациями ОС/интерфейсов:
| Линукс | Мак | Окна | |
|---|---|---|---|
| Ethernet | Да | Да | Да |
| USB | Да | Не проверено | Да |
| USB-последовательный | Да | Да | Да |
| Серийный | Да | Да | Да |
| Параллельно | Да | Не проверено | Да |
| Общий доступ для малого и среднего бизнеса | Да | Нет | Да |
| CUPS размещены | Да | Да | Нет |
Многие термопринтеры чеков в той или иной степени поддерживают ESC/POS. Известно, что этот драйвер работает с:
feedForm() ).release() ).Если вы используете какой-либо другой принтер с этим кодом, сообщите нам об этом, чтобы мы могли добавить его в список.
Эта библиотека предназначена для использования с менеджером зависимостей PHP composer . Чтобы начать, просто добавьте пакет mike42/escpos-php :
composer require mike42/escpos-php Если вы раньше не использовали composer , вы можете прочитать об этом на getcomposer.org.
Этот проект имеет несколько жестких зависимостей:
json , используемое для загрузки встроенных определений принтеров (см. документацию).intl , используемое для кодировки символов (см. документацию)zlib , используемое для распаковки связанных ресурсов (см. документацию). Также рекомендуется установить imagick или gd , поскольку их можно использовать для ускорения обработки изображений.
Можно добавить ряд дополнительных расширений для включения более конкретных функций. Они описаны в разделе «предложения» файла композитора.json.
Чтобы использовать этот драйвер, ваш сервер (на котором установлен 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 ();Ниже приведены некоторые примеры распространенных интерфейсов.
Подключитесь к принтеру с интерфейсом Ethernet с помощью netcat :
php hello-world.php | nc 10.x.x.x. 9100 Локальный USB-принтер, подключенный с помощью usblp в Linux, имеет файл устройства (включая параллельные 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 \serverprinter
copy foo.txt LPT1
del foo.txt
Если на этом этапе у вас возникли проблемы, вам следует обратиться к документации вашей ОС и системы принтера, чтобы попытаться найти работающую команду печати.
Чтобы распечатать квитанции из 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 работать, обязательно включите в свою задачу рабочую команду печати.
Поддержка команд и кодовых страниц варьируется в зависимости от производителя и модели принтера. По умолчанию драйвер принимает 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 );Список доступных профилей или информацию об улучшении поддержки вашего принтера см. в исходном проекте чека-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/.
Создайте новый объект печати.
Параметры:
PrintConnector $connector : PrintConnector для отправки данных.CapabilityProfile $profile Поддерживаемые функции этого принтера. Если этот параметр не установлен, будет использоваться профиль CapabilityProfile «по умолчанию», который подходит для принтеров Epson.См. example/interface/, чтобы узнать, как открыть соединения для разных платформ и интерфейсов.
Распечатайте штрих-код.
Параметры:
string $content : информация для кодирования.int $type : стандарт штрих-кода для вывода. Если не указано, будет использоваться Printer::BARCODE_CODE39 .В настоящее время поддерживаются следующие стандарты штрих-кодов (в зависимости от вашего принтера):
BARCODE_UPCABARCODE_UPCEBARCODE_JAN13BARCODE_JAN8BARCODE_CODE39BARCODE_ITFBARCODE_CODABARОбратите внимание, что некоторые стандарты штрих-кодов могут кодировать только числа, поэтому попытка распечатать с их помощью нечисловые коды может привести к странному поведению.
См. графику() ниже.
Разрежьте бумагу.
Параметры:
int $mode : Режим обрезки: Printer::CUT_FULL или Printer::CUT_PARTIAL . Если не указано, будет использоваться Printer::CUT_FULL .int $lines : Количество строк, которые необходимо заполнить перед обрезкой. Если не указано, будет использоваться 3.Печать и подача строки / Распечатка и подача n строк.
Параметры:
int $lines : Количество строк для подачиНекоторым принтерам для выпуска бумаги требуется подача страницы. На большинстве принтеров эта команда полезна только в страничном режиме, который не реализован в этом драйвере.
Распечатайте и переверните n строк.
Параметры:
int $lines : количество строк для подачи. Если не указано, будет подана 1 строка.Распечатайте изображение на принтере.
Параметры:
EscposImage $img : изображение для печати.int $size : Модификатор выходного размера изображения.Модификаторы размера:
IMG_DEFAULT (оставить изображение в исходном размере)IMG_DOUBLE_WIDTHIMG_DOUBLE_HEIGHTМинимальный пример:
<?php
$ img = EscposImage:: load ( " logo.png " );
$ printer -> graphics ( $ img );Подробные примеры см. в папке example/.
Функция bitImage() принимает те же параметры и может использоваться, если ваш принтер не поддерживает новые графические команды. В качестве дополнительной альтернативы также предоставляется функция bitImageColumnFormat() .
Инициализируйте принтер. Это сбрасывает форматирование обратно к значениям по умолчанию.
Распечатайте двумерный код данных, используя стандарт 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 только с начальной полосой.Сгенерируйте импульс для открытия денежного ящика, если он подключен. Настройки по умолчанию (0, 120, 240) должны открыть ящик Epson.
Параметры:
int $pin : 0 или 1, для выкидного разъема контакта 2 или контакта 5 соответственно.int $on_ms : время включения импульса в миллисекундах.int $off_ms : время выключения импульса в миллисекундах.Распечатайте данные в виде 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 (поддерживается не всеми принтерами).Выберите режим(ы) печати.
Параметры:
int $mode : используемый режим. По умолчанию используется Printer::MODE_FONT_A без специального форматирования. Это имеет аналогичный эффект при запуске initialize() . Несколько констант MODE_* могут быть переданы с помощью операции ИЛИ в аргумент $mode этой функции. Допустимые режимы:
MODE_FONT_AMODE_FONT_BMODE_EMPHASIZEDMODE_DOUBLE_HEIGHTMODE_DOUBLE_WIDTHMODE_UNDERLINEУстановите высоту штрих-кода.
Параметры:
int $height : Высота в точках. Если не указано, будет использоваться 8.Установите ширину полосы штрих-кода.
Параметры:
int $width : Ширина полосы в точках. Если не указано, будет использоваться 3. Значения выше 6, по-видимому, не имеют никакого эффекта.Выбор цвета печати — на принтерах, поддерживающих несколько цветов.
Параметры:
int $color : Используемый цвет. Должно быть либо Printer::COLOR_1 (по умолчанию), либо Printer::COLOR_2Включите/выключите режим двойного удара.
Параметры:
boolean $on : true для двойного удара, false — если двойного удара нет.Включите/выключите подчеркнутый режим.
Параметры:
boolean $on : true для выделения, false — для выделения.Выберите шрифт. Большинство принтеров имеют два шрифта (шрифты A и B), а некоторые — третий (шрифт C).
Параметры:
int $font : Используемый шрифт. Должно быть либо Printer::FONT_A , Printer::FONT_B , либо Printer::FONT_C .Выберите обоснование.
Параметры:
int $justification : один из Printer::JUSTIFY_LEFT , Printer::JUSTIFY_CENTER или Printer::JUSTIFY_RIGHT .Установите высоту линии.
Некоторые принтеры позволяют перекрывать строки с меньшим переводом строки.
Параметры:
int $height : Высота каждой строки в точках. Если этот параметр не установлен, принтер восстановит межстрочный интервал по умолчанию. Установите левое поле области печати. Сбросьте настройки по умолчанию с помощью Printer::initialize() .
Параметры:
int $margin : Левое поле, устанавливаемое в области печати, в точках. Установите ширину области печати. Это можно использовать для добавления правого поля в область печати. Сбросьте настройки по умолчанию с помощью Printer::initialize() .
Параметры:
int $width : Ширина области печати страницы в точках.Включите или выключите режим реверса черно-белого изображения. В этом режиме текст печатается белым цветом на черном фоне.
Параметры:
boolean $on : True для включения, false для отключения.Установите размер текста, кратный нормальному размеру.
Параметры:
int $widthMultiplier : кратно стандартной используемой высоте (диапазон 1–8).int $heightMultiplier : кратно стандартной используемой высоте (диапазон 1–8).Установить подчеркивание печатного текста.
Параметры:
int $underline : либо true / false , либо один из Printer::UNDERLINE_NONE , Printer::UNDERLINE_SINGLE или Printer::UNDERLINE_DOUBLE . По умолчанию Printer::UNDERLINE_SINGLE . Добавьте текст в буфер. За текстом должен следовать разрыв строки, либо после этого должна быть вызвана feed() .
Параметры:
string $str : строка для печати.Сообщения, которые я написал для людей, которые учатся пользоваться принтерами чеков:
example/demo.php .Этот код имеет лицензию MIT, и вам рекомендуется вносить любые изменения в проект.
Для разработки рекомендуется загрузить расширения PHP imagick , gd и Xdebug .
Тесты выполняются на Travis CI поверх PHP 7.3, 7.4 и 8.0. Текущая версия не поддерживает более старые версии PHP, равно как и HHVM.
Получите копию этого кода и загрузите зависимости с помощью композитора:
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
Запросы на включение и сообщения об ошибках приветствуются.
