escpos php
v4.0
Este projeto implementa um subconjunto do protocolo ESC/POS da Epson para impressoras térmicas de recibos. Ele permite gerar e imprimir recibos com formatação básica, corte e códigos de barras em uma impressora compatível.
A biblioteca foi desenvolvida para adicionar suporte imediato para impressão de recibos a qualquer aplicativo PHP, incluindo aplicativos de ponto de venda (POS) baseados na web.
Este driver é conhecido por funcionar com as seguintes combinações de sistema operacional/interface:
| Linux | Mac | Windows | |
|---|---|---|---|
| Ethernet | Sim | Sim | Sim |
| USB | Sim | Não testado | Sim |
| Serial USB | Sim | Sim | Sim |
| Serial | Sim | Sim | Sim |
| Paralelo | Sim | Não testado | Sim |
| PME compartilhado | Sim | Não | Sim |
| CUPS hospedado | Sim | Sim | Não |
Muitas impressoras térmicas de recibos suportam ESC/POS até certo ponto. Este driver é conhecido por funcionar com:
feedForm() para liberar papel).release() para liberar o deslizamento).Se você utiliza alguma outra impressora com este código, avise-nos para que ela possa ser adicionada à lista.
Esta biblioteca foi projetada para uso com o gerenciador de dependências PHP composer . Basta adicionar o pacote mike42/escpos-php para começar:
composer require mike42/escpos-php Se você nunca usou composer antes, você pode ler sobre ele em getcomposer.org.
Este projeto tem poucas dependências rígidas:
json , usada para carregar definições de impressora agrupadas (consulte a documentação)intl , usada para codificação de caracteres (ver documentação)zlib , usada para descompactar recursos agrupados (consulte a documentação). Também é sugerido que você instale imagick ou gd , pois eles podem ser usados para acelerar o processamento de imagens.
Várias extensões opcionais podem ser adicionadas para habilitar recursos mais específicos. Eles estão descritos na seção "sugerir" do compositor.json.
Para utilizar este driver, seu servidor (onde o PHP está instalado) deve ser capaz de se comunicar com sua impressora. Comece gerando um recibo simples e enviando-o para sua impressora usando a linha de comando.
<?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 ();Alguns exemplos estão abaixo para interfaces comuns.
Comunique-se com uma impressora com interface Ethernet usando netcat :
php hello-world.php | nc 10.x.x.x. 9100 Uma impressora local USB conectada com usblp no Linux possui um arquivo de dispositivo (inclui interfaces paralelas USB):
php hello-world.php > /dev/usb/lp0 Um computador instalado no servidor cups local é acessado através de lp ou lpr :
php hello-world.php > foo.txt
lpr -o raw -H localhost -P printer foo.txtUma impressora local ou em rede em um computador Windows é mapeada em um arquivo e geralmente exige que você compartilhe a impressora primeiro:
php hello-world.php > foo.txt
net use LPT1 \serverprinter
copy foo.txt LPT1
del foo.txt
Se você tiver problemas neste ponto, consulte a documentação do sistema operacional e do sistema da impressora para tentar encontrar um comando de impressão funcional.
Para imprimir recibos de PHP, use o PrintConnector mais aplicável para sua configuração. O conector simplesmente fornece o encanamento para levar os dados à impressora.
Por exemplo, um NetworkPrintConnector aceita um endereço IP e uma porta:
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 ();
}Embora uma impressora serial possa usar:
use Mike42 Escpos PrintConnectors FilePrintConnector ;
use Mike42 Escpos Printer ;
$ connector = new FilePrintConnector ( " /dev/ttyS0 " );
$ printer = new Printer ( $ connector ); Para cada combinação de sistema operacional/interface compatível, há exemplos na seção de compatibilidade de como um PrintConnector seria construído. Se você não conseguir fazer um PrintConnector funcionar, certifique-se de incluir o comando de impressão funcional em seu problema.
O suporte para comandos e páginas de código varia entre fornecedores e modelos de impressora. Por padrão, o driver aceitará UTF-8 e emitirá comandos adequados para impressoras da série Epson TM.
Ao experimentar uma nova marca de impressora, é uma boa ideia usar o "simples" CapabilityProfile , que instrui o driver a evitar o uso de recursos avançados (geralmente manipulação de imagens mais simples, texto somente 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 outro exemplo, as impressoras da marca Star usam comandos diferentes:
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 obter uma lista de perfis disponíveis ou para melhorar o suporte para sua impressora, consulte o projeto upstream recibo-print-hq/escpos-printer-db.
No Linux, o arquivo do dispositivo da sua impressora estará em algum lugar como /dev/lp0 (paralelo), /dev/usb/lp1 (USB), /dev/ttyUSB0 (USB-Serial), /dev/ttyS0 (serial).
No Windows, os arquivos do dispositivo serão semelhantes a LPT1 (paralelo) ou COM1 (serial). Use o WindowsPrintConnector para acessar a impressão do sistema no Windows (por exemplo, Windows USB, SMB ou Windows LPT) - isso envia trabalhos de impressão por meio de uma fila em vez de se comunicar diretamente com a impressora.
Um recibo completo do mundo real pode ser encontrado no código Auth em ReceiptPrinter.php. Inclui justificação, ousadia e código de barras.
Outros exemplos estão localizados no diretório example/.
Construa um novo objeto de impressão.
Parâmetros:
PrintConnector $connector : O PrintConnector para o qual enviar dados.CapabilityProfile $profile Recursos suportados por esta impressora. Se não for definido, será usado o CapabilityProfile "padrão", que é adequado para impressoras Epson.Veja exemplo/interface/ para maneiras de abrir conexões para diferentes plataformas e interfaces.
Imprima um código de barras.
Parâmetros:
string $content : as informações a serem codificadas.int $type : O padrão de código de barras para saída. Se não for especificado, Printer::BARCODE_CODE39 será usado.Os padrões de código de barras atualmente suportados são (dependendo da sua impressora):
BARCODE_UPCABARCODE_UPCEBARCODE_JAN13BARCODE_JAN8BARCODE_CODE39BARCODE_ITFBARCODE_CODABARObserve que alguns padrões de código de barras só podem codificar números, portanto, tentar imprimir códigos não numéricos com eles pode resultar em um comportamento estranho.
Veja gráficos() abaixo.
Corte o papel.
Parâmetros:
int $mode : Modo de corte, Printer::CUT_FULL ou Printer::CUT_PARTIAL . Se não for especificado, Printer::CUT_FULL será usado.int $lines : Número de linhas a serem alimentadas antes do corte. Se não for especificado, 3 será usado.Imprimir e alimentar linha / Imprimir e alimentar n linhas.
Parâmetros:
int $lines : Número de linhas para alimentarAlgumas impressoras exigem alimentação de formulário para liberar o papel. Na maioria das impressoras, esse comando só é útil no modo de página, que não está implementado neste driver.
Imprima e inverta a alimentação de n linhas.
Parâmetros:
int $lines : número de linhas para alimentar. Se não for especificado, 1 linha será alimentada.Imprima uma imagem na impressora.
Parâmetros:
EscposImage $img : A imagem a ser impressa.int $size : modificador de tamanho de saída para a imagem.Os modificadores de tamanho são:
IMG_DEFAULT (deixar a imagem no tamanho original)IMG_DOUBLE_WIDTHIMG_DOUBLE_HEIGHTUm exemplo mínimo:
<?php
$ img = EscposImage:: load ( " logo.png " );
$ printer -> graphics ( $ img );Veja o exemplo/pasta para exemplos detalhados.
A função bitImage() usa os mesmos parâmetros e pode ser usada se sua impressora não suportar os comandos gráficos mais recentes. Como alternativa adicional, a função bitImageColumnFormat() também é fornecida.
Inicialize a impressora. Isso redefine a formatação de volta aos padrões.
Imprima um código de dados bidimensional usando o padrão PDF417.
Parâmetros:
string $content : Texto ou números para armazenar no códigonumber $width : Largura de um módulo (pixel) no código impresso. O padrão é 3 pontos.number $heightMultiplier : Multiplicador da altura de um módulo. O padrão é 3 vezes a largura.number $dataColumnCount : número de colunas de dados a serem usadas. 0 (padrão) é para calcular automaticamente. Números menores resultarão em um código mais estreito, possibilitando tamanhos de pixels maiores. Números maiores requerem tamanhos de pixel menores.real $ec : Taxa de correção de erros, de 0,01 a 4,00. O padrão é 0,10 (10%).number $options : Código padrão Printer::PDF417_STANDARD com barras de início/fim ou código truncado Printer::PDF417_TRUNCATED apenas com barras de início.Gera um pulso para abrir uma gaveta de dinheiro, se houver alguma conectada. As configurações padrão (0, 120, 240) devem abrir uma gaveta Epson.
Parâmetros:
int $pin : 0 ou 1, para conector de saída do pino 2 ou pino 5, respectivamente.int $on_ms : tempo de ativação do pulso, em milissegundos.int $off_ms : tempo de desligamento do pulso, em milissegundos.Imprima os dados fornecidos como um código QR na impressora.
string $content : o conteúdo do código. Os dados numéricos serão compactados com mais eficiência.int $ec Nível de correção de erros a ser usado. Um de Printer::QR_ECLEVEL_L (padrão), Printer::QR_ECLEVEL_M , Printer::QR_ECLEVEL_Q ou Printer::QR_ECLEVEL_H . Uma maior correção de erros resulta em um código menos compacto.int $size : tamanho do pixel a ser usado. Deve ser de 1 a 16 (padrão 3)int $model : modelo de código QR a ser usado. Deve ser um dos Printer::QR_MODEL_1 , Printer::QR_MODEL_2 (padrão) ou Printer::QR_MICRO (não suportado por todas as impressoras).Selecione o(s) modo(s) de impressão.
Parâmetros:
int $mode : O modo a ser usado. O padrão é Printer::MODE_FONT_A , sem formatação especial. Isso tem um efeito semelhante à execução initialize() . Várias constantes MODE_* podem ser combinadas com OR e passadas para o argumento $mode desta função. Os modos válidos são:
MODE_FONT_AMODE_FONT_BMODE_EMPHASIZEDMODE_DOUBLE_HEIGHTMODE_DOUBLE_WIDTHMODE_UNDERLINEDefina a altura do código de barras.
Parâmetros:
int $height : Altura em pontos. Se não for especificado, 8 será usado.Defina a largura da barra do código de barras.
Parâmetros:
int $width : largura da barra em pontos. Se não for especificado, 3 será usado. Valores acima de 6 parecem não ter efeito.Selecione a cor de impressão - em impressoras que suportam múltiplas cores.
Parâmetros:
int $color : Cor a ser usada. Deve ser Printer::COLOR_1 (padrão) ou Printer::COLOR_2Ativar/desativar o modo de ataque duplo.
Parâmetros:
boolean $on : verdadeiro para ataque duplo, falso para nenhum ataque duplo.Ativar/desativar o modo enfatizado.
Parâmetros:
boolean $on : verdadeiro para ênfase, falso para sem ênfase.Selecione a fonte. A maioria das impressoras possui duas fontes (Fontes A e B) e algumas possuem uma terceira (Fonte C).
Parâmetros:
int $font : A fonte a ser usada. Deve ser Printer::FONT_A , Printer::FONT_B ou Printer::FONT_C .Selecione a justificativa.
Parâmetros:
int $justification : Um de Printer::JUSTIFY_LEFT , Printer::JUSTIFY_CENTER ou Printer::JUSTIFY_RIGHT .Defina a altura da linha.
Algumas impressoras permitem sobrepor linhas com um avanço de linha menor.
Parâmetros:
int $height : A altura de cada linha, em pontos. Se não for definido, a impressora será redefinida para o espaçamento entre linhas padrão. Defina a margem esquerda da área de impressão. Redefina para o padrão com Printer::initialize() .
Parâmetros:
int $margin : A margem esquerda a ser definida na área de impressão, em pontos. Defina a largura da área de impressão. Isso pode ser usado para adicionar uma margem direita à área de impressão. Redefina para o padrão com Printer::initialize() .
Parâmetros:
int $width : A largura da área de impressão da página, em pontos.Ative ou desative o modo reverso preto/branco. Neste modo, o texto é impresso em branco sobre fundo preto.
Parâmetros:
boolean $on : True para ativar, false para desativar.Defina o tamanho do texto como um múltiplo do tamanho normal.
Parâmetros:
int $widthMultiplier : Múltiplo da altura normal a ser usada (intervalo de 1 a 8).int $heightMultiplier : Múltiplo da altura normal a ser usada (intervalo de 1 a 8).Defina sublinhado para texto impresso.
Parâmetros:
int $underline : true / false , ou um de Printer::UNDERLINE_NONE , Printer::UNDERLINE_SINGLE ou Printer::UNDERLINE_DOUBLE . O padrão é Printer::UNDERLINE_SINGLE . Adicione texto ao buffer. O texto deve ser seguido por uma quebra de linha ou feed() deve ser chamado depois disso.
Parâmetros:
string $str : a string a ser impressa.Postagens que escrevi para pessoas que estão aprendendo a usar impressoras de recibos:
example/demo.php .Este código é licenciado pelo MIT e você é incentivado a contribuir com quaisquer modificações no projeto.
Para desenvolvimento, é sugerido que você carregue as extensões PHP imagick , gd e Xdebug .
Os testes são executados no Travis CI em PHP 7.3, 7.4 e 8.0. Versões mais antigas do PHP não são suportadas na versão atual, nem HHVM.
Obtenha uma cópia deste código e carregue as dependências com o compositor:
git clone https://github.com/mike42/escpos-php
cd escpos-php/
composer install
Execute testes unitários via phpunit :
php vendor/bin/phpunit --coverage-text
Este projeto utiliza o padrão PSR-2, que pode ser verificado via PHP_CodeSniffer:
php vendor/bin/phpcs --standard=psr2 src/ -n
Os documentos do desenvolvedor são construídos com doxygen. Recrie-os para verificar avisos de documentação:
make -C doc clean && make -C doc
Solicitações pull e relatórios de bugs são bem-vindos.
