escpos php
v4.0
يطبق هذا المشروع مجموعة فرعية من بروتوكول ESC/POS من إبسون لطابعات الإيصالات الحرارية. فهو يسمح لك بإنشاء وطباعة الإيصالات بالتنسيق الأساسي والقص والرموز الشريطية على طابعة متوافقة.
تم تطوير المكتبة لإضافة دعم مباشر لطباعة الإيصالات إلى أي تطبيق PHP، بما في ذلك تطبيقات نقاط البيع (POS) المستندة إلى الويب.
من المعروف أن برنامج التشغيل هذا يعمل مع مجموعات نظام التشغيل/الواجهة التالية:
| لينكس | ماك | ويندوز | |
|---|---|---|---|
| إيثرنت | نعم | نعم | نعم |
| USB | نعم | لم يتم اختباره | نعم |
| USB التسلسلي | نعم | نعم | نعم |
| مسلسل | نعم | نعم | نعم |
| موازي | نعم | لم يتم اختباره | نعم |
| مشاركة الشركات الصغيرة والمتوسطة | نعم | لا | نعم |
| استضافت 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 ); بالنسبة لكل مجموعة نظام تشغيل/واجهة مدعومة، توجد أمثلة في قسم التوافق لكيفية إنشاء PrintConnector . إذا لم تتمكن من تشغيل PrintConnector ، فتأكد من تضمين أمر الطباعة العامل في مشكلتك.
يختلف دعم الأوامر وصفحات التعليمات البرمجية بين بائعي الطابعات والطرازات. افتراضيًا، سيقبل برنامج التشغيل UTF-8 وأوامر الإخراج المناسبة لطابعات سلسلة Epson TM.
عند تجربة علامة تجارية جديدة للطابعة، من الجيد استخدام 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 (تسلسلي).
في نظام التشغيل Windows، ستكون ملفات الجهاز على غرار LPT1 (موازي) أو COM1 (مسلسل). استخدم WindowsPrintConnector للاستفادة من نظام الطباعة على نظام التشغيل Windows (على سبيل المثال Windows USB أو SMB أو Windows LPT) - حيث يقوم هذا بإرسال مهام الطباعة عبر قائمة انتظار بدلاً من الاتصال مباشرة بالطابعة.
يمكن العثور على إيصال كامل في العالم الحقيقي في رمز المصادقة في ReceiptPrinter.php. ويشمل التبرير والجرأة والباركود.
توجد أمثلة أخرى في الدليل/ المثال.
إنشاء كائن طباعة جديد.
حدود:
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 : وضع القطع، إما Printer::CUT_FULL أو Printer::CUT_PARTIAL . إذا لم يتم تحديده، سيتم استخدام Printer::CUT_FULL .int $lines : عدد الخطوط التي سيتم تغذيتها قبل القطع. إذا لم يتم تحديده، سيتم استخدام 3.خط الطباعة والتغذية / طباعة وتغذية الخطوط n.
حدود:
int $lines : عدد الأسطر المراد تغذيتهاتتطلب بعض الطابعات تغذية نموذج لتحرير الورق. في معظم الطابعات، يكون هذا الأمر مفيدًا فقط في وضع الصفحة، وهو ما لا يتم تنفيذه في برنامج التشغيل هذا.
طباعة وعكس خطوط التغذية n.
حدود:
int $lines : عدد الأسطر المراد تغذيتها. إذا لم يتم تحديده، سيتم تغذية سطر واحد.طباعة صورة إلى الطابعة.
حدود:
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 : صحيح للضربة المزدوجة، وخطأ لعدم وجود ضربة مزدوجة.تشغيل/إيقاف وضع التركيز.
حدود:
boolean $on : صحيح للتأكيد، وخطأ لعدم التركيز.حدد الخط. تحتوي معظم الطابعات على خطين (الخطان 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)، ونشجعك على المساهمة بأي تعديلات على المشروع.
من أجل التطوير، يُقترح تحميل امتدادات imagick و gd و Xdebug PHP.
يتم تنفيذ الاختبارات على 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
تم إنشاء مستندات المطور باستخدام الدوكسيجين. أعد بنائها للتحقق من تحذيرات التوثيق:
make -C doc clean && make -C doc
نرحب بطلبات السحب وتقارير الأخطاء.
