escpos php

Driver Cetak ESC/POS untuk PHP

Proyek ini mengimplementasikan subset protokol ESC/POS Epson untuk printer resi termal. Ini memungkinkan Anda membuat dan mencetak tanda terima dengan format dasar, pemotongan, dan kode batang pada printer yang kompatibel.

Pustaka ini dikembangkan untuk menambahkan dukungan drop-in untuk pencetakan tanda terima ke aplikasi PHP apa pun, termasuk aplikasi point-of-sale (POS) berbasis web.

Kesesuaian

Antarmuka dan sistem operasi

Driver ini diketahui bekerja dengan kombinasi OS/antarmuka berikut:

	Linux	Mac	jendela
Ethernet	Ya	Ya	Ya
USB	Ya	Tidak diuji	Ya
Serial USB	Ya	Ya	Ya
Serial	Ya	Ya	Ya
Paralel	Ya	Tidak diuji	Ya
UKM dibagikan	Ya	TIDAK	Ya
CUPS dihosting	Ya	Ya	TIDAK

pencetak

Banyak printer resi termal mendukung ESC/POS sampai tingkat tertentu. Pengemudi ini diketahui bekerja dengan:

• 3nBintang RPT-008
• Kira-kira APPPOS80AM
• AURES ODP-333
• AURES ODP-500
• Bematech-4200-TH
• Bematech LR2000E
• Birch PRP-085III
• Bixolon SRP-350III
• Bixolon SRP-350Plus
• Tembaga Hitam BC-85AC
• PJK TH-305N
• Warga negara CBM1000-II
• Warga CT-S310II
• Necis-Geyi Q583P
• Daruma DR800
• DR-MP200 (produsen tidak diketahui)
• EPOS TEP 220M
• Elgin i9
• Epson EU-T332C
• Epson FX-890 (membutuhkan feedForm() untuk mengeluarkan kertas).
• Epson TM-T20
• EpsonTM-T20II
• Epson TM-T70
• EpsonTM-T70II
• Epson TM-T81
• Epson TM-T82II
• Epson TM-T88II
• Epson TM-T88III
• Epson TM-T88IV
• Epson TM-T88V
• Epson TM-U220
• Epson TM-U295 (membutuhkan release() untuk melepaskan slip).
• Epson TM-U590 dan TM-U590P
• Sama (EQ-IT-001) POS-58
• Everycom EC-58
• Excelvan HOP-E200
• Excelvan HOP-E58
• Excelvan HOP-E801
• Keuntungan GP-2120TF
• Gainscha GP-5890x (Juga dipasarkan sebagai EC Line 5890x)
• Gainscha GP-U80300I (Juga dipasarkan sebagai gprinter GP-U80300I)
• gprinter GP-U80160I
• HOIN HOP-H58
• Ithaca iTherm 28
• Hasar HTP 250
• Metapase T-1
• Metapase T-25
• Nexa PX700
• Ntahun NP100
• Oke RT322
• OKI 80 Ditambah III
• Orientasi BTP-R580
• P-822D
• P85A-401 (tidak diketahui)
• Teknologi Mitra RP320
• POSLIGNE ODP200H-III-G
• QPOS Q58M
• Rongta RP326US
• Rongta RP58-U
• Rongta RP80USE
• SAM4S RAKSASA-100DB
• Senor TP-100
• Sewoo SLK-TS400
• SEYPOS PRP-96
• SEYPOS PRP-300 (Juga dipasarkan sebagai TYSSO PRP-300)
• SNBC BTP-R880NPIII
• Solux SX-TP-88300
• Sicar POS-80
• Silikon SP-201 / RP80USE
• SPRT SP-POS88V
• Bintang BSC10
• Bintang TSP100 ECO
• Bintang TSP100III FuturePRNT
• Bintang TSP-650
• Bintang TUP-592
• Toko TVS RP45
• Venus V248T
• SM-8330 yang lebih rendah
• Xprinter F-900
• Xprinter XP-365B
• Seri Xprinter XP-58
• Xprinter XP-80C
• Xprinter XP-90
• XPrinter XP-Q20011
• Xprinter XP-Q800
• Zjiang NT-58H
• Zjiang ZJ-5870
• Zjiang ZJ-5890 (Juga dijual sebagai POS-5890 oleh banyak vendor; ZJ-5890K, ZJ-5890T juga berfungsi).
• Zjiang ZJ-8220 (Juga dipasarkan sebagai Excelvan ZJ-8220)
• Zjiang ZJ-8250

Jika Anda menggunakan printer lain dengan kode ini, harap beri tahu kami agar dapat ditambahkan ke daftar.

Penggunaan dasar

Sertakan perpustakaan

Komposer

Pustaka ini dirancang untuk digunakan dengan manajer ketergantungan composer PHP. Cukup tambahkan paket mike42/escpos-php untuk memulai:

composer require mike42/escpos-php

Jika Anda belum pernah menggunakan composer , Anda dapat membacanya di getcomposer.org.

Persyaratan

Proyek ini memiliki sedikit ketergantungan yang sulit:

• PHP 7.3 atau lebih baru.
• ekstensi json , digunakan untuk memuat definisi printer yang dibundel (lihat dokumentasi)
• ekstensi intl , digunakan untuk pengkodean karakter (lihat dokumentasi)
• ekstensi zlib , digunakan untuk mendekompresi sumber daya yang dibundel (lihat dokumentasi).

Anda juga disarankan untuk menginstal imagick atau gd , karena ini dapat digunakan untuk mempercepat pemrosesan gambar.

Sejumlah ekstensi opsional dapat ditambahkan untuk mengaktifkan fitur yang lebih spesifik. Ini dijelaskan di bagian "sarankan" di composer.json.

Tanda terima 'Halo Dunia'

Untuk menggunakan driver ini, server Anda (tempat PHP diinstal) harus dapat berkomunikasi dengan printer Anda. Mulailah dengan membuat tanda terima sederhana dan mengirimkannya ke printer Anda menggunakan baris perintah.

 <?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 ();

Beberapa contoh di bawah ini untuk antarmuka umum.

Berkomunikasi dengan printer dengan antarmuka Ethernet menggunakan netcat :

php hello-world.php | nc 10.x.x.x. 9100

Printer lokal USB yang terhubung dengan usblp di Linux memiliki file perangkat (Termasuk antarmuka paralel USB):

php hello-world.php > /dev/usb/lp0

Komputer yang diinstal pada server cups lokal diakses melalui lp atau lpr :

php hello-world.php > foo.txt
lpr -o raw -H localhost -P printer foo.txt

Printer lokal atau jaringan di komputer Windows dipetakan ke dalam file, dan biasanya mengharuskan Anda berbagi printer terlebih dahulu:

 php hello-world.php > foo.txt
net use LPT1 \serverprinter
copy foo.txt LPT1
del foo.txt

Jika Anda mengalami masalah saat ini, Anda harus membaca dokumentasi OS dan sistem printer Anda untuk mencoba menemukan perintah cetak yang berfungsi.

Menggunakan PrintConnector

Untuk mencetak tanda terima dari PHP, gunakan PrintConnector yang paling sesuai untuk pengaturan Anda. Konektor hanya menyediakan pipa untuk mengalirkan data ke printer.

Misalnya, NetworkPrintConnector menerima alamat IP dan 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 ();
}

Meskipun printer serial mungkin menggunakan:

 use Mike42  Escpos  PrintConnectors  FilePrintConnector ;
use Mike42  Escpos  Printer ;
$ connector = new FilePrintConnector ( " /dev/ttyS0 " );
$ printer = new Printer ( $ connector );

Untuk setiap kombinasi OS/antarmuka yang didukung, terdapat contoh di bagian kompatibilitas tentang bagaimana PrintConnector akan dibuat. Jika Anda tidak bisa membuat PrintConnector berfungsi, pastikan untuk menyertakan perintah print yang berfungsi dalam masalah Anda.

Menggunakan Profil Kemampuan

Dukungan untuk perintah dan halaman kode bervariasi antara vendor dan model printer. Secara default, driver akan menerima UTF-8, dan perintah keluaran yang sesuai untuk printer seri Epson TM.

Saat mencoba printer merek baru, sebaiknya gunakan CapabilityProfile "sederhana", yang menginstruksikan pengemudi untuk menghindari penggunaan fitur-fitur canggih (umumnya penanganan gambar lebih sederhana, teks khusus 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 );

Contoh lainnya, printer bermerek Star menggunakan perintah berbeda:

 use Mike42  Escpos  PrintConnectors  WindowsPrintConnector ;
use Mike42  Escpos  CapabilityProfile ;
$ profile = CapabilityProfile:: load ( " SP2000 " )
$ connector = new WindowsPrintConnector ( " smb://computer/printer " );
$ printer = new Printer ( $ connector , $ profile );

Untuk daftar profil yang tersedia, atau untuk meningkatkan dukungan bagi printer Anda, silakan lihat proyek hulu receipt-print-hq/escpos-printer-db.

Tip & contoh

Di Linux, file perangkat printer Anda akan berada di suatu tempat seperti /dev/lp0 (paralel), /dev/usb/lp1 (USB), /dev/ttyUSB0 (USB-Serial), /dev/ttyS0 (serial).

Di Windows, file perangkat akan berada di sepanjang baris LPT1 (paralel) atau COM1 (serial). Gunakan WindowsPrintConnector untuk memanfaatkan pencetakan sistem pada Windows (mis. Windows USB, SMB, atau Windows LPT) - ini mengirimkan pekerjaan pencetakan melalui antrian daripada berkomunikasi langsung dengan printer.

Tanda terima dunia nyata yang lengkap dapat ditemukan dalam kode Auth di ReceiptPrinter.php. Ini mencakup pembenaran, keberanian, dan kode batang.

Contoh lain terletak di direktori example/.

Metode yang tersedia

__construct(PrintConnector $konektor, CapabilityProfile $profil)

Buat objek cetak baru.

Parameter:

• PrintConnector $connector : PrintConnector tujuan pengiriman data.
• CapabilityProfile $profile Fitur yang didukung pada printer ini. Jika tidak disetel, CapabilityProfile "default" akan digunakan, yang cocok untuk printer Epson.

Lihat contoh/antarmuka/ untuk mengetahui cara membuka koneksi untuk berbagai platform dan antarmuka.

kode batang($konten, $tipe)

Cetak kode batang.

Parameter:

• string $content : Informasi yang akan dikodekan.
• int $type : Standar barcode yang akan dikeluarkan. Jika tidak ditentukan, Printer::BARCODE_CODE39 akan digunakan.

Standar kode batang yang didukung saat ini adalah (tergantung pada printer Anda):

• BARCODE_UPCA
• BARCODE_UPCE
• BARCODE_JAN13
• BARCODE_JAN8
• BARCODE_CODE39
• BARCODE_ITF
• BARCODE_CODABAR

Perhatikan bahwa beberapa standar kode batang hanya dapat mengkodekan angka, jadi mencoba mencetak kode non-numerik dengan kode tersebut dapat mengakibatkan perilaku yang aneh.

bitImage(EscposImage $gambar, $ukuran)

Lihat grafik() di bawah.

potong($mode, $garis)

Potong kertasnya.

Parameter:

• int $mode : Mode potong, baik Printer::CUT_FULL atau Printer::CUT_PARTIAL . Jika tidak ditentukan, Printer::CUT_FULL akan digunakan.
• int $lines : Jumlah baris yang akan dimasukkan sebelum dipotong. Jika tidak ditentukan, 3 akan digunakan.

umpan($garis)

Cetak dan umpankan baris / Cetak dan umpankan n baris.

Parameter:

• int $lines : Jumlah baris yang akan diumpankan

formulir umpan()

Beberapa printer memerlukan pengumpan formulir untuk mengeluarkan kertas. Pada sebagian besar printer, perintah ini hanya berguna dalam mode halaman, yang tidak diterapkan pada driver ini.

feedReverse($garis)

Cetak dan balikkan umpan n baris.

Parameter:

• int $lines : jumlah baris yang akan diumpankan. Jika tidak ditentukan, 1 baris akan diumpankan.

grafis(EscposImage $gambar, $ukuran)

Cetak gambar ke printer.

Parameter:

• EscposImage $img : Gambar yang akan dicetak.
• int $size : Pengubah ukuran keluaran untuk gambar.

Pengubah ukuran adalah:

• IMG_DEFAULT (biarkan gambar dalam ukuran aslinya)
• IMG_DOUBLE_WIDTH
• IMG_DOUBLE_HEIGHT

Contoh minimal:

 <?php
$ img = EscposImage:: load ( " logo.png " );
$ printer -> graphics ( $ img );

Lihat folder contoh/ untuk contoh detailnya.

Fungsi bitImage() menggunakan parameter yang sama, dan dapat digunakan jika printer Anda tidak mendukung perintah grafis yang lebih baru. Sebagai cadangan tambahan, fungsi bitImageColumnFormat() juga disediakan.

inisialisasi()

Inisialisasi pencetak. Ini mengatur ulang pemformatan kembali ke default.

pdf417Code($konten, $lebar, $tinggiPengganda, $dataColumnCount, $ec, $pilihan)

Cetak kode data dua dimensi menggunakan standar PDF417.

Parameter:

• string $content : Teks atau angka untuk disimpan dalam kode
• number $width : Lebar modul (piksel) pada kode yang dicetak. Standarnya adalah 3 titik.
• number $heightMultiplier : Pengganda untuk tinggi modul. Standarnya adalah 3 kali lebarnya.
• number $dataColumnCount : Jumlah kolom data yang akan digunakan. 0 (default) adalah menghitung otomatis. Angka yang lebih kecil akan menghasilkan kode yang lebih sempit, sehingga memungkinkan ukuran piksel lebih besar. Angka yang lebih besar memerlukan ukuran piksel yang lebih kecil.
• real $ec : Rasio koreksi kesalahan, dari 0,01 hingga 4,00. Standarnya adalah 0,10 (10%).
• number $options : Kode standar Printer::PDF417_STANDARD dengan bilah awal/akhir, atau kode terpotong Printer::PDF417_TRUNCATED dengan bilah awal saja.

pulsa($pin, $on_ms, $off_ms)

Menghasilkan pulsa, untuk membuka laci kas jika ada yang terhubung. Pengaturan default (0, 120, 240) akan membuka laci Epson.

Parameter:

• int $pin : 0 atau 1, masing-masing untuk konektor kick-out pin 2 atau pin 5.
• int $on_ms : waktu pulsa AKTIF, dalam milidetik.
• int $off_ms : waktu pulsa MATI, dalam milidetik.

qrCode($isi, $ec, $ukuran, $model)

Cetak data yang diberikan sebagai kode QR pada printer.

• string $content : Isi kode. Data numerik akan dipadatkan dengan lebih efisien.
• int $ec Tingkat koreksi kesalahan yang akan digunakan. Salah satu Printer::QR_ECLEVEL_L (default), Printer::QR_ECLEVEL_M , Printer::QR_ECLEVEL_Q atau Printer::QR_ECLEVEL_H . Koreksi kesalahan yang lebih tinggi menghasilkan kode yang kurang ringkas.
• int $size : Ukuran piksel yang akan digunakan. Harus 1-16 (default 3)
• int $model : model kode QR yang akan digunakan. Harus salah satu dari Printer::QR_MODEL_1 , Printer::QR_MODEL_2 (default) atau Printer::QR_MICRO (tidak didukung oleh semua printer).

pilihModeCetak($mode)

Pilih mode cetak.

Parameter:

• int $mode : Mode yang akan digunakan. Defaultnya adalah Printer::MODE_FONT_A , tanpa format khusus. Ini memiliki efek yang mirip dengan menjalankan initialize() .

Beberapa konstanta MODE_* dapat di OR bersama-sama diteruskan ke argumen $mode fungsi ini. Mode yang valid adalah:

• MODE_FONT_A
• MODE_FONT_B
• MODE_EMPHASIZED
• MODE_DOUBLE_HEIGHT
• MODE_DOUBLE_WIDTH
• MODE_UNDERLINE

setBarcodeHeight($tinggi)

Atur tinggi kode batang.

Parameter:

• int $height : Tinggi dalam titik. Jika tidak ditentukan, 8 akan digunakan.

setLebar Kode Batang($lebar)

Atur lebar bilah kode batang.

Parameter:

• int $width : Lebar batang dalam titik. Jika tidak ditentukan, 3 akan digunakan. Nilai di atas 6 tampaknya tidak berpengaruh.

setWarna($warna)

Pilih warna cetak - pada printer yang mendukung banyak warna.

Parameter:

• int $color : Warna yang akan digunakan. Harus berupa Printer::COLOR_1 (default), atau Printer::COLOR_2

setDoubleStrike($on)

Mengaktifkan/menonaktifkan mode serangan ganda.

Parameter:

• boolean $on : benar untuk teguran ganda, salah jika tidak ada teguran ganda.

setPenekanan($on)

Mengaktifkan/menonaktifkan mode yang ditekankan.

Parameter:

• boolean $on : benar untuk penekanan, salah untuk tanpa penekanan.

setFont($font)

Pilih font. Kebanyakan printer memiliki dua font (Font A dan B), dan beberapa memiliki font ketiga (Font C).

Parameter:

• int $font : Font yang akan digunakan. Harus berupa Printer::FONT_A , Printer::FONT_B , atau Printer::FONT_C .

setJustifikasi($justifikasi)

Pilih pembenaran.

Parameter:

• int $justification : Salah satu dari Printer::JUSTIFY_LEFT , Printer::JUSTIFY_CENTER , atau Printer::JUSTIFY_RIGHT .

setLineSpacing($tinggi)

Atur ketinggian garis.

Beberapa printer memungkinkan Anda tumpang tindih garis dengan pengumpan garis yang lebih kecil.

Parameter:

• int $height : Ketinggian setiap garis, dalam titik. Jika tidak disetel, printer akan diatur ulang ke spasi baris default.

setPrintLeftMargin($margin)

Mengatur margin kiri area cetak. Reset ke default dengan Printer::initialize() .

Parameter:

• int $margin : Margin kiri untuk area pencetakan, dalam titik.

setPrintWidth($lebar)

Atur lebar area cetak. Ini dapat digunakan untuk menambahkan margin kanan pada area pencetakan. Reset ke default dengan Printer::initialize() .

Parameter:

• int $width : Lebar area pencetakan halaman, dalam titik.

setReverseColors($on)

Mengaktifkan atau menonaktifkan mode mundur hitam/putih. Dalam mode ini, teks dicetak putih dengan latar belakang hitam.

Parameter:

• boolean $on : Benar untuk mengaktifkan, salah untuk menonaktifkan.

setTextSize($widthMultiplier, $heightMultiplier)

Atur ukuran teks, sebagai kelipatan dari ukuran normal.

Parameter:

• int $widthMultiplier : Kelipatan tinggi biasa yang akan digunakan (kisaran 1 - 8).
• int $heightMultiplier : Kelipatan tinggi biasa yang akan digunakan (kisaran 1 - 8).

setGaris Bawah($garis bawah)

Atur garis bawah untuk teks yang dicetak.

Parameter:

• int $underline : true / false , atau salah satu dari Printer::UNDERLINE_NONE , Printer::UNDERLINE_SINGLE atau Printer::UNDERLINE_DOUBLE . Defaultnya adalah Printer::UNDERLINE_SINGLE .

teks($str)

Tambahkan teks ke buffer. Teks harus diikuti dengan jeda baris, atau feed() harus dipanggil setelah ini.

Parameter:

• string $str : String yang akan dicetak.

Catatan lebih lanjut

Postingan yang saya tulis untuk orang-orang yang sedang mempelajari cara menggunakan printer resi:

• Apa itu ESC/POS, dan bagaimana cara menggunakannya?, yang mendokumentasikan keluaran example/demo.php .
• Menyiapkan printer resi Epson
• Membuat printer resi USB berfungsi di Linux

Perkembangan

Kode ini berlisensi MIT, dan Anda dianjurkan untuk menyumbangkan modifikasi apa pun kembali ke proyek.

Untuk pengembangan, disarankan agar Anda memuat ekstensi PHP imagick , gd dan Xdebug .

Pengujian dijalankan pada Travis CI melalui PHP 7.3, 7.4 dan 8.0. Versi PHP yang lebih lama tidak didukung pada rilis saat ini, begitu pula HHVM.

Ambil salinan kode ini dan muat dependensi dengan komposer:

 git clone https://github.com/mike42/escpos-php
cd escpos-php/
composer install

Jalankan pengujian unit melalui phpunit :

 php vendor/bin/phpunit --coverage-text

Proyek ini menggunakan standar PSR-2, yang dapat diperiksa melalui PHP_CodeSniffer:

 php vendor/bin/phpcs --standard=psr2 src/ -n

Dokumen pengembang dibuat dengan doxygen. Bangun kembali untuk memeriksa peringatan dokumentasi:

 make -C doc clean && make -C doc

Permintaan tarik dan laporan bug diterima.