escpos php
v4.0
Ce projet implémente un sous-ensemble du protocole ESC/POS d'Epson pour les imprimantes de reçus thermiques. Il vous permet de générer et d'imprimer des reçus avec un formatage, une découpe et des codes-barres de base sur une imprimante compatible.
La bibliothèque a été développée pour ajouter une prise en charge immédiate de l'impression de reçus à n'importe quelle application PHP, y compris les applications Web de point de vente (POS).
Ce pilote est connu pour fonctionner avec les combinaisons OS/interface suivantes :
| Linux | Mac | Fenêtres | |
|---|---|---|---|
| Ethernet | Oui | Oui | Oui |
| USB | Oui | Non testé | Oui |
| USB-série | Oui | Oui | Oui |
| En série | Oui | Oui | Oui |
| Parallèle | Oui | Non testé | Oui |
| PME partagée | Oui | Non | Oui |
| CUPS hébergées | Oui | Oui | Non |
De nombreuses imprimantes de reçus thermiques prennent en charge ESC/POS dans une certaine mesure. Ce pilote est connu pour fonctionner avec :
feedForm() pour libérer le papier).release() pour libérer le bordereau).Si vous utilisez une autre imprimante avec ce code, veuillez nous en informer afin qu'elle puisse être ajoutée à la liste.
Cette bibliothèque est conçue pour être utilisée avec le gestionnaire de dépendances PHP composer . Ajoutez simplement le package mike42/escpos-php pour commencer :
composer require mike42/escpos-php Si vous n'avez jamais utilisé composer auparavant, vous pouvez en savoir plus sur getcomposer.org.
Ce projet a quelques dépendances matérielles :
json , utilisée pour charger les définitions d'imprimantes groupées (voir documentation)intl , utilisée pour l'encodage des caractères (voir documentation)zlib , utilisée pour décompresser les ressources groupées (voir documentation). Il est également suggéré d'installer soit imagick soit gd , car ceux-ci peuvent être utilisés pour accélérer le traitement des images.
Un certain nombre d'extensions facultatives peuvent être ajoutées pour activer des fonctionnalités plus spécifiques. Ceux-ci sont décrits dans la section « suggérer » de composer.json.
Pour utiliser ce pilote, votre serveur (sur lequel PHP est installé) doit pouvoir communiquer avec votre imprimante. Commencez par générer un simple reçu et envoyez-le à votre imprimante à l’aide de la ligne de commande.
<?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 ();Quelques exemples sont ci-dessous pour les interfaces courantes.
Communiquez avec une imprimante avec une interface Ethernet en utilisant netcat :
php hello-world.php | nc 10.x.x.x. 9100 Une imprimante locale USB connectée avec usblp sous Linux possède un fichier de périphérique (inclut les interfaces USB-parallèles) :
php hello-world.php > /dev/usb/lp0 Un ordinateur installé sur le serveur cups local est accessible via lp ou lpr :
php hello-world.php > foo.txt
lpr -o raw -H localhost -P printer foo.txtUne imprimante locale ou en réseau sur un ordinateur Windows est mappée dans un fichier et nécessite généralement que vous partagiez d'abord l'imprimante :
php hello-world.php > foo.txt
net use LPT1 \serverprinter
copy foo.txt LPT1
del foo.txt
Si vous rencontrez des problèmes à ce stade, vous devez consulter la documentation de votre système d'exploitation et de votre imprimante pour essayer de trouver une commande d'impression fonctionnelle.
Pour imprimer des reçus depuis PHP, utilisez le PrintConnector le plus applicable à votre configuration. Le connecteur fournit simplement la plomberie pour acheminer les données vers l'imprimante.
Par exemple, un NetworkPrintConnector accepte une adresse IP et un port :
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 ();
}Alors qu'une imprimante série peut utiliser :
use Mike42 Escpos PrintConnectors FilePrintConnector ;
use Mike42 Escpos Printer ;
$ connector = new FilePrintConnector ( " /dev/ttyS0 " );
$ printer = new Printer ( $ connector ); Pour chaque combinaison système d'exploitation/interface prise en charge, il existe des exemples dans la section de compatibilité montrant comment un PrintConnector serait construit. Si vous ne parvenez pas à faire fonctionner un PrintConnector , assurez-vous d'inclure la commande d'impression fonctionnelle dans votre problème.
La prise en charge des commandes et des pages de codes varie selon les fournisseurs et les modèles d'imprimantes. Par défaut, le pilote acceptera UTF-8 et produira des commandes adaptées aux imprimantes Epson de la série TM.
Lorsque vous essayez une nouvelle marque d'imprimante, c'est une bonne idée d'utiliser le "simple" CapabilityProfile , qui demande au pilote d'éviter l'utilisation de fonctionnalités avancées (gestion généralement plus simple des images, texte uniquement 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 );Comme autre exemple, les imprimantes de marque Star utilisent différentes commandes :
use Mike42 Escpos PrintConnectors WindowsPrintConnector ;
use Mike42 Escpos CapabilityProfile ;
$ profile = CapabilityProfile:: load ( " SP2000 " )
$ connector = new WindowsPrintConnector ( " smb://computer/printer " );
$ printer = new Printer ( $ connector , $ profile );Pour obtenir la liste des profils disponibles ou pour améliorer la prise en charge de votre imprimante, veuillez consulter le projet en amont reçu-print-hq/escpos-printer-db.
Sous Linux, le fichier de votre périphérique d'imprimante se trouvera quelque part comme /dev/lp0 (parallèle), /dev/usb/lp1 (USB), /dev/ttyUSB0 (USB-série), /dev/ttyS0 (série).
Sous Windows, les fichiers de périphérique seront du type LPT1 (parallèle) ou COM1 (série). Utilisez WindowsPrintConnector pour accéder à l'impression système sous Windows (par exemple Windows USB, SMB ou Windows LPT) - cela soumet les travaux d'impression via une file d'attente plutôt que de communiquer directement avec l'imprimante.
Un reçu complet du monde réel peut être trouvé dans le code d'authentification dans ReceiptPrinter.php. Il comprend une justification, du gras et un code-barres.
D'autres exemples se trouvent dans le répertoire example/.
Construisez un nouvel objet d’impression.
Paramètres :
PrintConnector $connector : Le PrintConnector auquel envoyer les données.CapabilityProfile $profile Fonctionnalités prises en charge par cette imprimante. S'il n'est pas défini, le CapabilityProfile « par défaut » sera utilisé, ce qui convient aux imprimantes Epson.Voir example/interface/ pour savoir comment ouvrir des connexions pour différentes plates-formes et interfaces.
Imprimez un code-barres.
Paramètres :
string $content : Les informations à encoder.int $type : Le standard de code-barres à afficher. S’il n’est pas spécifié, Printer::BARCODE_CODE39 sera utilisé.Les normes de codes-barres actuellement prises en charge sont (en fonction de votre imprimante) :
BARCODE_UPCABARCODE_UPCEBARCODE_JAN13BARCODE_JAN8BARCODE_CODE39BARCODE_ITFBARCODE_CODABARNotez que certaines normes de codes-barres ne peuvent encoder que des chiffres. Par conséquent, tenter d'imprimer des codes non numériques avec celles-ci peut entraîner un comportement étrange.
Voir graphiques() ci-dessous.
Coupez le papier.
Paramètres :
int $mode : mode Coupe, soit Printer::CUT_FULL ou Printer::CUT_PARTIAL . S’il n’est pas spécifié, Printer::CUT_FULL sera utilisé.int $lines : Nombre de lignes à alimenter avant de couper. Si non spécifié, 3 seront utilisés.Imprimer et alimenter la ligne / Imprimer et alimenter n lignes.
Paramètres :
int $lines : Nombre de lignes à alimenterCertaines imprimantes nécessitent un saut de page pour libérer le papier. Sur la plupart des imprimantes, cette commande n'est utile qu'en mode page, qui n'est pas implémenté dans ce pilote.
Imprimez et avancez n lignes en arrière.
Paramètres :
int $lines : nombre de lignes à alimenter. Si non spécifié, 1 ligne sera alimentée.Imprimez une image sur l'imprimante.
Paramètres :
EscposImage $img : L'image à imprimer.int $size : Modificateur de taille de sortie pour l'image.Les modificateurs de taille sont :
IMG_DEFAULT (laisser l'image à sa taille d'origine)IMG_DOUBLE_WIDTHIMG_DOUBLE_HEIGHTUn exemple minimal :
<?php
$ img = EscposImage:: load ( " logo.png " );
$ printer -> graphics ( $ img );Voir le dossier example/ pour des exemples détaillés.
La fonction bitImage() prend les mêmes paramètres et peut être utilisée si votre imprimante ne prend pas en charge les commandes graphiques les plus récentes. Comme solution de secours supplémentaire, la fonction bitImageColumnFormat() est également fournie.
Initialisez l'imprimante. Cela réinitialise le formatage aux valeurs par défaut.
Imprimez un code de données bidimensionnel à l'aide de la norme PDF417.
Paramètres :
string $content : Texte ou nombres à stocker dans le codenumber $width : Largeur d'un module (pixel) dans le code imprimé. La valeur par défaut est 3 points.number $heightMultiplier : Multiplicateur de hauteur d'un module. La valeur par défaut est 3 fois la largeur.number $dataColumnCount : Nombre de colonnes de données à utiliser. 0 (par défaut) correspond au calcul automatique. Des nombres plus petits entraîneront un code plus étroit, permettant des tailles de pixels plus grandes. Des nombres plus grands nécessitent des tailles de pixels plus petites.real $ec : Taux de correction d'erreur, de 0,01 à 4,00. La valeur par défaut est 0,10 (10 %).number $options : Code standard Printer::PDF417_STANDARD avec barres de début/fin, ou code tronqué Printer::PDF417_TRUNCATED avec barres de début uniquement.Générer une impulsion, pour ouvrir un tiroir-caisse s'il y en a un connecté. Les paramètres par défaut (0, 120, 240) devraient ouvrir un tiroir Epson.
Paramètres :
int $pin : 0 ou 1, pour le connecteur de kick-out broche 2 ou broche 5 respectivement.int $on_ms : temps d'activation de l'impulsion, en millisecondes.int $off_ms : temps d'arrêt de l'impulsion, en millisecondes.Imprimez les données fournies sous forme de code QR sur l'imprimante.
string $content : Le contenu du code. Les données numériques seront compactées plus efficacement.int $ec Niveau de correction d'erreur à utiliser. L'un des Printer::QR_ECLEVEL_L (par défaut), Printer::QR_ECLEVEL_M , Printer::QR_ECLEVEL_Q ou Printer::QR_ECLEVEL_H . Une correction d'erreur plus élevée entraîne un code moins compact.int $size : Taille de pixel à utiliser. Doit être compris entre 1 et 16 (3 par défaut)int $model : modèle de code QR à utiliser. Doit être l'un des Printer::QR_MODEL_1 , Printer::QR_MODEL_2 (par défaut) ou Printer::QR_MICRO (non pris en charge par toutes les imprimantes).Sélectionnez le(s) mode(s) d'impression.
Paramètres :
int $mode : Le mode à utiliser. La valeur par défaut est Printer::MODE_FONT_A , sans formatage spécial. Cela a un effet similaire à l’exécution initialize() . Plusieurs constantes MODE_* peuvent être combinées par OU et transmises à l'argument $mode de cette fonction. Les modes valides sont :
MODE_FONT_AMODE_FONT_BMODE_EMPHASIZEDMODE_DOUBLE_HEIGHTMODE_DOUBLE_WIDTHMODE_UNDERLINEDéfinir la hauteur du code-barres.
Paramètres :
int $height : Hauteur en points. S’il n’est pas spécifié, 8 sera utilisé.Définir la largeur de la barre du code-barres.
Paramètres :
int $width : Largeur de la barre en points. Si non spécifié, 3 seront utilisés. Les valeurs supérieures à 6 semblent n’avoir aucun effet.Sélectionnez la couleur d'impression - sur les imprimantes prenant en charge plusieurs couleurs.
Paramètres :
int $color : Couleur à utiliser. Doit être soit Printer::COLOR_1 (par défaut), soit Printer::COLOR_2Activez/désactivez le mode double frappe.
Paramètres :
boolean $on : true pour une double frappe, false pour aucune double frappe.Activer/désactiver le mode accentué.
Paramètres :
boolean $on : vrai pour l'accentuation, faux pour l'absence d'accentuation.Sélectionnez la police. La plupart des imprimantes ont deux polices (polices A et B) et certaines en ont une troisième (police C).
Paramètres :
int $font : La police à utiliser. Doit être soit Printer::FONT_A , Printer::FONT_B ou Printer::FONT_C .Sélectionnez la justification.
Paramètres :
int $justification : l'un des Printer::JUSTIFY_LEFT , Printer::JUSTIFY_CENTER ou Printer::JUSTIFY_RIGHT .Définissez la hauteur de la ligne.
Certaines imprimantes vous permettront de superposer des lignes avec un saut de ligne plus petit.
Paramètres :
int $height : La hauteur de chaque ligne, en points. S’il n’est pas défini, l’imprimante sera réinitialisée à son espacement de ligne par défaut. Définir la marge gauche de la zone d’impression. Réinitialiser par défaut avec Printer::initialize() .
Paramètres :
int $margin : La marge gauche à définir sur la zone d'impression, en points. Définir la largeur de la zone d'impression. Cela peut être utilisé pour ajouter une marge droite à la zone d'impression. Réinitialiser par défaut avec Printer::initialize() .
Paramètres :
int $width : La largeur de la zone d'impression de la page, en points.Activez ou désactivez le mode inversé noir/blanc. Dans ce mode, le texte est imprimé en blanc sur fond noir.
Paramètres :
boolean $on : True pour activer, false pour désactiver.Définissez la taille du texte, en tant que multiple de la taille normale.
Paramètres :
int $widthMultiplier : Multiple de la hauteur normale à utiliser (plage 1 - 8).int $heightMultiplier : Multiple de la hauteur normale à utiliser (plage 1 - 8).Définir le soulignement pour le texte imprimé.
Paramètres :
int $underline : Soit true / false , soit l'un des Printer::UNDERLINE_NONE , Printer::UNDERLINE_SINGLE ou Printer::UNDERLINE_DOUBLE . La valeur par défaut est Printer::UNDERLINE_SINGLE . Ajoutez du texte au tampon. Le texte doit être suivi d'un saut de ligne ou feed() doit être appelé après cela.
Paramètres :
string $str : La chaîne à imprimer.Articles que j'ai rédigés pour les personnes qui apprennent à utiliser les imprimantes de reçus :
example/demo.php .Ce code est sous licence MIT et vous êtes encouragé à apporter toute modification au projet.
Pour le développement, il est suggéré de charger les extensions PHP imagick , gd et Xdebug .
Les tests sont exécutés sur Travis CI sur PHP 7.3, 7.4 et 8.0. Les anciennes versions de PHP ne sont pas prises en charge dans la version actuelle, pas plus que HHVM.
Récupérez une copie de ce code et chargez les dépendances avec composer :
git clone https://github.com/mike42/escpos-php
cd escpos-php/
composer install
Exécuter des tests unitaires via phpunit :
php vendor/bin/phpunit --coverage-text
Ce projet utilise le standard PSR-2, qui peut être vérifié via PHP_CodeSniffer :
php vendor/bin/phpcs --standard=psr2 src/ -n
Les documents du développeur sont construits avec doxygen. Reconstruisez-les pour vérifier les avertissements de la documentation :
make -C doc clean && make -C doc
Les demandes de tirage et les rapports de bogues sont les bienvenus.
