escpos php
v4.0
โปรเจ็กต์นี้ใช้ชุดย่อยของโปรโตคอล ESC/POS ของเอปสันสำหรับเครื่องพิมพ์ใบเสร็จเทอร์มอล ช่วยให้คุณสามารถสร้างและพิมพ์ใบเสร็จรับเงินด้วยการจัดรูปแบบพื้นฐาน การตัด และบาร์โค้ดบนเครื่องพิมพ์ที่รองรับ
ไลบรารีนี้ได้รับการพัฒนาเพื่อเพิ่มการรองรับแบบดรอปอินสำหรับการพิมพ์ใบเสร็จไปยังแอป PHP ใดๆ รวมถึงแอปพลิเคชัน ณ จุดขาย (POS) บนเว็บ
เป็นที่ทราบกันว่าไดรเวอร์นี้ทำงานร่วมกับระบบปฏิบัติการ/อินเทอร์เฟซต่อไปนี้:
| ลินุกซ์ | แม็ค | หน้าต่าง | |
|---|---|---|---|
| อีเทอร์เน็ต | ใช่ | ใช่ | ใช่ |
| ยูเอสบี | ใช่ | ไม่ได้ทดสอบ | ใช่ |
| USB-อนุกรม | ใช่ | ใช่ | ใช่ |
| อนุกรม | ใช่ | ใช่ | ใช่ |
| ขนาน | ใช่ | ไม่ได้ทดสอบ | ใช่ |
| SMB แบ่งปันแล้ว | ใช่ | เลขที่ | ใช่ |
| CUPS เป็นเจ้าภาพ | ใช่ | ใช่ | เลขที่ |
เครื่องพิมพ์ใบเสร็จความร้อนหลายรุ่นรองรับ ESC/POS ในระดับหนึ่ง เป็นที่รู้กันว่าไดรเวอร์นี้ใช้งานได้กับ:
feedForm() เพื่อปล่อยกระดาษ)release() เพื่อปล่อยสลิป)หากคุณใช้เครื่องพิมพ์อื่นที่มีรหัสนี้ โปรดแจ้งให้เราทราบเพื่อให้สามารถเพิ่มเข้าไปในรายการได้
ไลบรารีนี้ออกแบบมาเพื่อใช้กับตัวจัดการการพึ่งพา PHP composer เพียงเพิ่มแพ็คเกจ mike42/escpos-php เพื่อเริ่มต้น:
composer require mike42/escpos-php หากคุณยังไม่เคยใช้ composer มาก่อน คุณสามารถอ่านรายละเอียดได้ที่ getcomposer.org
โปรเจ็กต์นี้มีการขึ้นต่อกันที่ยากบางประการ:
json ใช้เพื่อโหลดคำจำกัดความเครื่องพิมพ์แบบรวม (ดูเอกสารประกอบ)intl ใช้สำหรับการเข้ารหัสอักขระ (ดูเอกสารประกอบ)zlib ใช้สำหรับคลายการบีบอัดทรัพยากรที่รวมกลุ่ม (ดูเอกสารประกอบ) ขอแนะนำให้คุณติดตั้ง imagick หรือ gd เนื่องจากสามารถใช้เพื่อเร่งการประมวลผลภาพได้
คุณสามารถเพิ่มส่วนขยายเพิ่มเติมได้จำนวนหนึ่งเพื่อเปิดใช้งานคุณลักษณะเฉพาะเจาะจงมากขึ้น สิ่งเหล่านี้อธิบายไว้ในส่วน "แนะนำ" ของ composer.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 ); สำหรับการรวม OS/อินเทอร์เฟซแต่ละรายการที่รองรับ มีตัวอย่างในส่วนความเข้ากันได้ของวิธีสร้าง PrintConnector หากคุณไม่สามารถใช้งาน PrintConnector ได้ ตรวจสอบให้แน่ใจว่าได้รวมคำสั่งการพิมพ์ที่ใช้งานได้ไว้ในปัญหาของคุณ
การรองรับคำสั่งและโค้ดเพจจะแตกต่างกันไปตามผู้จำหน่ายเครื่องพิมพ์และรุ่น ตามค่าเริ่มต้น ไดรเวอร์จะยอมรับ UTF-8 และคำสั่งเอาท์พุตที่เหมาะสำหรับเครื่องพิมพ์ Epson TM-series
เมื่อลองใช้เครื่องพิมพ์แบรนด์ใหม่ เป็นความคิดที่ดีที่จะใช้ 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-Serial), /dev/ttyS0 (serial)
บน Windows ไฟล์ของอุปกรณ์จะอยู่ในบรรทัด LPT1 (ขนาน) หรือ COM1 (อนุกรม) ใช้ WindowsPrintConnector เพื่อแตะการพิมพ์ของระบบบน Windows (เช่น Windows USB, SMB หรือ Windows LPT) ซึ่งจะส่งงานพิมพ์ผ่านคิวแทนที่จะสื่อสารโดยตรงกับเครื่องพิมพ์
คุณสามารถดูใบเสร็จรับเงินในชีวิตจริงฉบับสมบูรณ์ได้ในรหัส Auth ใน ReceiptPrinter.php รวมถึงการให้เหตุผล ความกล้า และบาร์โค้ด
ตัวอย่างอื่นๆ จะอยู่ในไดเร็กทอรี example/
สร้างวัตถุพิมพ์ใหม่
พารามิเตอร์:
PrintConnector $connector : PrintConnector ที่จะส่งข้อมูลไปCapabilityProfile $profile คุณสมบัติที่สนับสนุนของเครื่องพิมพ์นี้ หากไม่ได้ตั้งค่า จะใช้ CapabilityProfile "เริ่มต้น" ซึ่งเหมาะสำหรับเครื่องพิมพ์ Epsonดูตัวอย่าง/interface/ สำหรับวิธีเปิดการเชื่อมต่อสำหรับแพลตฟอร์มและอินเทอร์เฟซต่างๆ
พิมพ์บาร์โค้ด
พารามิเตอร์:
string $content : ข้อมูลที่จะเข้ารหัสint $type : มาตรฐานบาร์โค้ดที่จะส่งออก ถ้าไม่ระบุ จะใช้ Printer::BARCODE_CODE39มาตรฐานบาร์โค้ดที่รองรับในปัจจุบันคือ (ขึ้นอยู่กับเครื่องพิมพ์ของคุณ):
BARCODE_UPCABARCODE_UPCEBARCODE_JAN13BARCODE_JAN8BARCODE_CODE39BARCODE_ITFBARCODE_CODABARโปรดทราบว่ามาตรฐานบาร์โค้ดบางประเภทสามารถเข้ารหัสได้เฉพาะตัวเลขเท่านั้น ดังนั้นการพยายามพิมพ์รหัสที่ไม่ใช่ตัวเลขด้วยรหัสเหล่านั้นอาจส่งผลให้เกิดพฤติกรรมที่ผิดปกติ
ดูกราฟิก () ด้านล่าง
ตัดกระดาษ.
พารามิเตอร์:
int $mode : โหมด Cut ทั้ง Printer::CUT_FULL หรือ Printer::CUT_PARTIAL ถ้าไม่ระบุ จะใช้ Printer::CUT_FULLint $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 );ดูตัวอย่าง/ โฟลเดอร์สำหรับตัวอย่างโดยละเอียด
ฟังก์ชัน 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 : จริงสำหรับการนัดหยุดงานสองครั้ง, 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 : จริงเพื่อเปิดใช้งาน, เท็จเพื่อปิดการใช้งานกำหนดขนาดของข้อความให้เป็นจำนวนเท่าของขนาดปกติ
พารามิเตอร์:
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
ยินดีต้อนรับคำขอดึงและรายงานข้อผิดพลาด
