escpos php
v4.0
Este proyecto implementa un subconjunto del protocolo ESC/POS de Epson para impresoras térmicas de recibos. Le permite generar e imprimir recibos con formato, corte y códigos de barras básicos en una impresora compatible.
La biblioteca fue desarrollada para agregar soporte directo para la impresión de recibos a cualquier aplicación PHP, incluidas las aplicaciones de punto de venta (POS) basadas en web.
Se sabe que este controlador funciona con las siguientes combinaciones de sistema operativo/interfaz:
| linux | Impermeable | ventanas | |
|---|---|---|---|
| Ethernet | Sí | Sí | Sí |
| USB | Sí | No probado | Sí |
| USB-serie | Sí | Sí | Sí |
| De serie | Sí | Sí | Sí |
| Paralelo | Sí | No probado | Sí |
| PYME compartida | Sí | No | Sí |
| CUPS alojados | Sí | Sí | No |
Muchas impresoras térmicas de recibos admiten ESC/POS hasta cierto punto. Se sabe que este controlador funciona con:
feedForm() para liberar el papel).release() para liberar el resbalón).Si utiliza cualquier otra impresora con este código, háganoslo saber para que podamos agregarla a la lista.
Esta biblioteca está diseñada para usarse con el administrador de dependencias de PHP composer . Simplemente agregue el paquete mike42/escpos-php para comenzar:
composer require mike42/escpos-php Si no ha usado composer antes, puede leer sobre él en getcomposer.org.
Este proyecto tiene pocas dependencias estrictas:
json , utilizada para cargar definiciones de impresoras incluidas (consulte la documentación)intl , utilizada para codificación de caracteres (ver documentación)zlib , utilizada para descomprimir recursos empaquetados (ver documentación). También se sugiere que instale imagick o gd , ya que pueden usarse para acelerar el procesamiento de imágenes.
Se pueden agregar varias extensiones opcionales para habilitar funciones más específicas. Estos se describen en la sección "sugerencias" de compositor.json.
Para utilizar este controlador, su servidor (donde está instalado PHP) debe poder comunicarse con su impresora. Comience generando un recibo simple y enviándolo a su impresora usando la línea de comandos.
<?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 ();A continuación se muestran algunos ejemplos de interfaces comunes.
Comunicarse con una impresora con una interfaz Ethernet usando netcat :
php hello-world.php | nc 10.x.x.x. 9100 Una impresora local USB conectada con usblp en Linux tiene un archivo de dispositivo (incluye interfaces USB paralelas):
php hello-world.php > /dev/usb/lp0 Se accede a una computadora instalada en el servidor cups local a través de lp o lpr :
php hello-world.php > foo.txt
lpr -o raw -H localhost -P printer foo.txtUna impresora local o en red en una computadora con Windows está asignada a un archivo y, por lo general, requiere que usted comparta la impresora primero:
php hello-world.php > foo.txt
net use LPT1 \serverprinter
copy foo.txt LPT1
del foo.txt
Si tiene problemas en este punto, debe consultar la documentación del sistema operativo y de la impresora para intentar encontrar un comando de impresión que funcione.
Para imprimir recibos desde PHP, utilice el PrintConnector más aplicable para su configuración. El conector simplemente proporciona la tubería para llevar datos a la impresora.
Por ejemplo, un NetworkPrintConnector acepta una dirección IP y un puerto:
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 ();
}Mientras que una impresora en serie podría usar:
use Mike42 Escpos PrintConnectors FilePrintConnector ;
use Mike42 Escpos Printer ;
$ connector = new FilePrintConnector ( " /dev/ttyS0 " );
$ printer = new Printer ( $ connector ); Para cada combinación de sistema operativo/interfaz compatible, hay ejemplos en la sección de compatibilidad de cómo se construiría un PrintConnector . Si no puede hacer que un PrintConnector funcione, asegúrese de incluir el comando de impresión que funcione en su problema.
La compatibilidad con comandos y páginas de códigos varía según el proveedor y el modelo de impresora. De forma predeterminada, el controlador aceptará UTF-8 y generará comandos adecuados para las impresoras de la serie Epson TM.
Al probar una nueva marca de impresora, es una buena idea utilizar el CapabilityProfile "simple", que indica al controlador que evite el uso de funciones avanzadas (generalmente manejo de imágenes más simple, texto solo 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 );Como otro ejemplo, las impresoras de la marca Star utilizan diferentes comandos:
use Mike42 Escpos PrintConnectors WindowsPrintConnector ;
use Mike42 Escpos CapabilityProfile ;
$ profile = CapabilityProfile:: load ( " SP2000 " )
$ connector = new WindowsPrintConnector ( " smb://computer/printer " );
$ printer = new Printer ( $ connector , $ profile );Para obtener una lista de perfiles disponibles o para mejorar la compatibilidad con su impresora, consulte el proyecto ascendente recibo-print-hq/escpos-printer-db.
En Linux, el archivo del dispositivo de su impresora estará en algún lugar como /dev/lp0 (paralelo), /dev/usb/lp1 (USB), /dev/ttyUSB0 (USB-Serial), /dev/ttyS0 (serial).
En Windows, los archivos del dispositivo estarán en la línea LPT1 (paralelo) o COM1 (serie). Utilice WindowsPrintConnector para aprovechar la impresión del sistema en Windows (por ejemplo, Windows USB, SMB o Windows LPT); esto envía los trabajos de impresión a través de una cola en lugar de comunicarse directamente con la impresora.
Se puede encontrar un recibo completo del mundo real en el código de autenticación en ReceiptPrinter.php. Incluye justificación, negrita y código de barras.
Otros ejemplos se encuentran en el directorio ejemplo/.
Construya un nuevo objeto de impresión.
Parámetros:
PrintConnector $connector : El PrintConnector al que enviar datos.CapabilityProfile $profile Funciones admitidas de esta impresora. Si no se configura, se utilizará el CapabilityProfile "predeterminado", que es adecuado para impresoras Epson.Consulte ejemplo/interfaz/ para conocer formas de abrir conexiones para diferentes plataformas e interfaces.
Imprime un código de barras.
Parámetros:
string $content : La información a codificar.int $type : El estándar de código de barras a generar. Si no se especifica, se utilizará Printer::BARCODE_CODE39 .Los estándares de códigos de barras actualmente admitidos son (según su impresora):
BARCODE_UPCABARCODE_UPCEBARCODE_JAN13BARCODE_JAN8BARCODE_CODE39BARCODE_ITFBARCODE_CODABARTenga en cuenta que algunos estándares de códigos de barras solo pueden codificar números, por lo que intentar imprimir códigos no numéricos con ellos puede provocar un comportamiento extraño.
Vea los gráficos() a continuación.
Corta el papel.
Parámetros:
int $mode : modo de corte, ya sea Printer::CUT_FULL o Printer::CUT_PARTIAL . Si no se especifica, se utilizará Printer::CUT_FULL .int $lines : Número de líneas a alimentar antes de cortar. Si no se especifica, se utilizará 3.Imprimir y alimentar línea / Imprimir y alimentar n líneas.
Parámetros:
int $lines : Número de líneas para alimentarAlgunas impresoras requieren un avance de página para liberar el papel. En la mayoría de las impresoras, este comando sólo es útil en el modo de página, que no está implementado en este controlador.
Imprime y retrocede n líneas.
Parámetros:
int $lines : número de líneas a alimentar. Si no se especifica, se alimentará 1 línea.Imprima una imagen en la impresora.
Parámetros:
EscposImage $img : La imagen a imprimir.int $size : modificador de tamaño de salida para la imagen.Los modificadores de tamaño son:
IMG_DEFAULT (dejar la imagen en tamaño original)IMG_DOUBLE_WIDTHIMG_DOUBLE_HEIGHTUn ejemplo mínimo:
<?php
$ img = EscposImage:: load ( " logo.png " );
$ printer -> graphics ( $ img );Consulte la carpeta ejemplo/ para ver ejemplos detallados.
La función bitImage() toma los mismos parámetros y puede usarse si su impresora no admite los comandos gráficos más nuevos. Como alternativa adicional, también se proporciona la función bitImageColumnFormat() .
Inicialice la impresora. Esto restablece el formato a los valores predeterminados.
Imprima un código de datos bidimensional utilizando el estándar PDF417.
Parámetros:
string $content : Texto o números para almacenar en el códigonumber $width : Ancho de un módulo (píxel) en el código impreso. El valor predeterminado es 3 puntos.number $heightMultiplier : Multiplicador de la altura de un módulo. El valor predeterminado es 3 veces el ancho.number $dataColumnCount : número de columnas de datos a utilizar. 0 (predeterminado) es para calcular automáticamente. Números más pequeños darán como resultado un código más estrecho, lo que hará posibles tamaños de píxeles más grandes. Números mayores requieren tamaños de píxeles más pequeños.real $ec : Relación de corrección de errores, de 0,01 a 4,00. El valor predeterminado es 0,10 (10%).number $options : Código estándar Printer::PDF417_STANDARD con barras de inicio/final, o código truncado Printer::PDF417_TRUNCATED solo con barras de inicio.Generar un pulso para abrir un cajón de dinero si hay uno conectado. La configuración predeterminada (0, 120, 240) debería abrir un cajón Epson.
Parámetros:
int $pin : 0 o 1, para el conector de desconexión del pin 2 o 5 respectivamente.int $on_ms : tiempo de encendido del pulso, en milisegundos.int $off_ms : tiempo de apagado del pulso, en milisegundos.Imprima los datos proporcionados como un código QR en la impresora.
string $content : El contenido del código. Los datos numéricos se compactarán de manera más eficiente.int $ec Nivel de corrección de errores a utilizar. Uno de Printer::QR_ECLEVEL_L (predeterminado), Printer::QR_ECLEVEL_M , Printer::QR_ECLEVEL_Q o Printer::QR_ECLEVEL_H . Una mayor corrección de errores da como resultado un código menos compacto.int $size : Tamaño de píxel a utilizar. Debe ser 1-16 (predeterminado 3)int $model : modelo de código QR a utilizar. Debe ser uno de Printer::QR_MODEL_1 , Printer::QR_MODEL_2 (predeterminado) o Printer::QR_MICRO (no compatible con todas las impresoras).Seleccione los modos de impresión.
Parámetros:
int $mode : el modo a utilizar. El valor predeterminado es Printer::MODE_FONT_A , sin formato especial. Esto tiene un efecto similar a ejecutar initialize() . Se pueden aplicar operaciones OR a varias constantes MODE_* al argumento $mode de esta función. Los modos válidos son:
MODE_FONT_AMODE_FONT_BMODE_EMPHASIZEDMODE_DOUBLE_HEIGHTMODE_DOUBLE_WIDTHMODE_UNDERLINEEstablecer la altura del código de barras.
Parámetros:
int $height : altura en puntos. Si no se especifica, se utilizará 8.Establecer el ancho de la barra del código de barras.
Parámetros:
int $width : Ancho de la barra en puntos. Si no se especifica, se utilizará 3. Los valores superiores a 6 parecen no tener ningún efecto.Seleccione el color de impresión: en impresoras que admiten varios colores.
Parámetros:
int $color : Color a utilizar. Debe ser Printer::COLOR_1 (predeterminado) o Printer::COLOR_2Activa o desactiva el modo de doble golpe.
Parámetros:
boolean $on : verdadero para doble strike, falso para ningún doble strike.Activa o desactiva el modo enfatizado.
Parámetros:
boolean $on : verdadero para enfatizar, falso para no enfatizar.Seleccione fuente. La mayoría de las impresoras tienen dos fuentes (fuentes A y B) y algunas tienen una tercera (fuente C).
Parámetros:
int $font : la fuente a utilizar. Debe ser Printer::FONT_A , Printer::FONT_B o Printer::FONT_C .Seleccione justificación.
Parámetros:
int $justification : Uno de Printer::JUSTIFY_LEFT , Printer::JUSTIFY_CENTER o Printer::JUSTIFY_RIGHT .Establece la altura de la línea.
Algunas impresoras le permitirán superponer líneas con un avance de línea más pequeño.
Parámetros:
int $height : la altura de cada línea, en puntos. Si no se configura, la impresora se restablecerá a su interlineado predeterminado. Establezca el margen izquierdo del área de impresión. Restablecer los valores predeterminados con Printer::initialize() .
Parámetros:
int $margin : el margen izquierdo para establecer en el área de impresión, en puntos. Establezca el ancho del área de impresión. Esto se puede utilizar para agregar un margen derecho al área de impresión. Restablecer los valores predeterminados con Printer::initialize() .
Parámetros:
int $width : El ancho del área de impresión de la página, en puntos.Activa o desactiva el modo inverso blanco/negro. En este modo, el texto se imprime en blanco sobre un fondo negro.
Parámetros:
boolean $on : Verdadero para habilitar, falso para deshabilitar.Establece el tamaño del texto como un múltiplo del tamaño normal.
Parámetros:
int $widthMultiplier : múltiplo de la altura normal a usar (rango 1 - 8).int $heightMultiplier : múltiplo de la altura normal a utilizar (rango 1 - 8).Establecer subrayado para el texto impreso.
Parámetros:
int $underline : true / false , o uno de Printer::UNDERLINE_NONE , Printer::UNDERLINE_SINGLE o Printer::UNDERLINE_DOUBLE . El valor predeterminado es Printer::UNDERLINE_SINGLE . Agregue texto al búfer. El texto debe ir seguido de un salto de línea o se debe llamar feed() después de esto.
Parámetros:
string $str : la cadena a imprimir.Publicaciones que escribí para personas que están aprendiendo a usar impresoras de recibos:
example/demo.php .Este código tiene licencia del MIT y le recomendamos que contribuya con cualquier modificación al proyecto.
Para el desarrollo, se sugiere cargar las extensiones PHP imagick , gd y Xdebug .
Las pruebas se ejecutan en Travis CI sobre PHP 7.3, 7.4 y 8.0. Las versiones anteriores de PHP no son compatibles con la versión actual, ni tampoco HHVM.
Obtenga una copia de este código y cargue las dependencias con el compositor:
git clone https://github.com/mike42/escpos-php
cd escpos-php/
composer install
Ejecute pruebas unitarias a través de phpunit :
php vendor/bin/phpunit --coverage-text
Este proyecto utiliza el estándar PSR-2, que se puede comprobar mediante PHP_CodeSniffer:
php vendor/bin/phpcs --standard=psr2 src/ -n
Los documentos para desarrolladores están creados con doxygen. Reconstrúyalos para comprobar si hay advertencias en la documentación:
make -C doc clean && make -C doc
Se aceptan solicitudes de extracción e informes de errores.
