Receiptprinter Laravel Package

Getting Started

• Install with composer require charlieuki/receiptprinter. On Laravel 5.5+ the service provider should be auto-discovered; on older versions register Charlieuki\ReceiptPrinter\ReceiptPrinterServiceProvider manually.
• Publish the package config and inspect config/receiptprinter.php first. This is where the connector (network or cups), printer address/name, paper width, currency, and store details are defined.
• Configure the printer connection before writing application code:
  • Network printer: set host and raw port, usually 9100.
  • CUPS printer: set the CUPS queue name and ensure the queue exists on the host running Laravel.
• Define at least one store entry in the config. The receipt object expects a store ID so it can render the store name, address, phone, and footer.
• The first useful use case: print a hard-coded test receipt from a Tinker session or artisan command. Instantiate Charlieuki\ReceiptPrinter\ReceiptPrinter, set the store, currency, items, totals, paid amount, and change, then call printReceipt(). Confirm the physical output before wiring it to real orders.
• Read the ReceiptPrinter class early. It is a thin convenience wrapper around mike42/escpos-php, so most formatting and connector behavior ultimately comes from that underlying library.
• If you are on 1.2.5a or later, also try printLogo() and openDrawer() in the same Tinker smoke test. Both are new and explicitly flagged as untested upstream, so validate them on your hardware before relying on them.

Implementation Patterns

• Wrap printing in an application service rather than calling ReceiptPrinter directly from controllers. A ReceiptService or PrintOrderReceipt action keeps receipt construction, store lookup, and error handling in one place.
• Dispatch printing through a queued job. Printer I/O is slow and failure-prone; a synchronous call in a checkout request can block the customer response. Use ShouldQueue, sensible tries, backoff, and a failed() handler.
• Map Eloquent orders into the receipt shape explicitly: line item name, quantity, unit price, line total, subtotal, discount, tax, total, paid, and change. Keep money as integer minor units in your domain and format only at the receipt boundary.
• Use the store ID as the main multi-tenant switch. Store receipt metadata in config or a stores table, validate the ID before printing, and pass it via setStore(). This makes one deployment serve multiple outlets.
• Centralize per-store defaults: currency symbol, paper width, header/footer text, tax label, logo path (if using printLogo()), whether the drawer should be kicked, and whether the receipt should include item codes or SKUs.
• Add an idempotency guard. A queued job may retry after a timeout even though the printer already received the data. Record print attempts against the order or receipt number and avoid duplicate output where possible.
• Build a plain-text preview path for support and testing. Render the same data into a text representation for logs or an admin screen instead of requiring a physical printer for every check.
• In tests, bind a fake receipt printer or fake connector and assert the mapped data, not raw ESC/POS bytes. Keep one manual hardware smoke test for formatting, cut, encoding, logo rendering, and drawer kick.
• Log the printer target, store ID, order ID, duration, and exception on failure. Repeated queue failures usually mean an unreachable host, wrong port, or bad CUPS queue rather than bad receipt data.
• Since 1.2.5a you can call printLogo() before the body to place a store logo at the top of the receipt, and openDrawer() to kick the cash drawer wired to the printer’s RJ11 port. Treat the drawer kick as a separate concern from the receipt itself: call it on cash-tender flows, not on card payments or reprints, and consider isolating it in its own small service method so a drawer failure does not prevent the receipt from printing (and vice versa).

Gotchas and Tips

• Maintenance risk is the biggest issue. The package’s last release was in 2021 and it depends on the ecosystem around mike42/escpos-php, which is effectively unmaintained. Check PHP 8.x compatibility, pin versions, and be prepared to fork or patch if you rely on it long-term.
• printLogo() and openDrawer() are brand new in 1.2.5a and the maintainer states they still need testing. Do not assume the method signatures, argument order, or behavior are stable, and do not silently depend on them in production without a hardware smoke test on each printer model and paper width you support.
• Logos are raster data sent as ESC/POS bit images. They must be monochrome (1-bit), correctly sized for the paper width (roughly 384 dots for 58 mm, 576 for 80 mm), and reasonably small, or the print job becomes slow or gets truncated. If printLogo() fails or produces garbage, pre-process the image yourself (greyscale, threshold, resize) rather than passing arbitrary PNG/JPG files.
• openDrawer() only works if the drawer is physically connected to the printer’s drawer port and the printer supports the standard kick command with the expected pin (usually pin 2, sometimes pin 5). A no-op drawer usually means wiring or pin number, not code.
• Network printing uses raw TCP, typically port 9100. There is no authentication or transport security. Ensure the queue worker host can reach the printer, open the firewall where needed, and set connection timeouts so jobs fail fast.
• CUPS printing requires the CUPS client and a configured printer queue on the same host as the Laravel worker. It is not portable across environments and can behave differently in containers.
• Character encoding is a common failure point. Thermal printers use ESC/POS code pages, so non-ASCII characters, emoji, and some currency symbols may print as garbage or blanks. Test with the actual hardware and transliterate or convert encoding where necessary.
• Paper width matters. A 58 mm printer is typically around 40 columns and an 80 mm printer around 48. Setting the wrong width causes wrapping, truncation, or misaligned totals — and mis-sized logos.
• After changing config or .env, run php artisan config:clear or php artisan config:cache. Printer host, store, and logo path changes will not apply while an old config cache is active.
• Failures can be quiet or inconsistent depending on the connector. Wrap printReceipt(), printLogo(), and openDrawer() in try/catch, log the exception, and monitor failed jobs. Test the unreachable-printer path deliberately.
• Avoid floating-point arithmetic for totals and tax. Rounding differences between your order calculation and the receipt renderer produce visibly wrong totals. Use integer cents and explicit rounding rules.
• Validate store IDs before printing. A missing store config can produce an incomplete receipt or a null-related error deep in the wrapper.
• Do not edit vendor files. If you need custom layout behavior, or you need to work around a bug in the new logo/drawer methods, subclass the receipt printer or wrap it in your own service. If a real patch is required, fork the package and document the divergence.