Kurdish Escpos Laravel Package

Getting Started

Install the current line explicitly:

composer require rawand201/kurdish-escpos:^0.5.1

Do not target 0.1.0 through 0.5.0; those Packagist versions are no longer installable because the repository history was rewritten. 0.5.1 contains the same code as 0.5.0, so behaviour is unchanged — only the installable version changed.

First steps:

1. Check the package README for the service provider/facade registration. If the package supports Laravel auto-discovery, no manual provider entry is needed; otherwise add it to config/app.php or the appropriate bootstrap file.
2. Publish any package config if available (php artisan vendor:publish --tag=...) and set printer connection details via environment variables rather than hard-coding IPs or device paths.
3. Confirm the transport you need: network ESC/POS printer, USB, or a shared print server. The connection configuration is the first thing to validate before formatting receipts.
4. Start with a minimal receipt: a few Kurdish lines, alignment, a total line, and a paper cut. Print it to a real printer or an ESC/POS emulator before building invoice or order logic.

The primary day-to-day use case is printing Kurdish-language receipts/invoices to thermal ESC/POS printers from a Laravel order, POS, or accounting flow.

Implementation Patterns

Keep printing out of the request cycle. Wrap print operations in queued jobs or dedicated service classes. A network printer can be slow or offline; the HTTP request that completes an order should not block on printer I/O.

ProcessOrderReceipt::dispatch($order)->onQueue('printing');

Centralise printer configuration. Put printer host/port, paper width, character encoding, and enabled features in config/ and environment variables. Avoid scattering printer IPs through controllers or jobs.

Build receipts with a formatter/builder layer. Compose receipts from reusable sections — header, order lines, totals, footer, barcode/QR, cut, cash drawer kick. This keeps Kurdish text, alignment, and column widths consistent across receipt types.

Handle Kurdish text deliberately. RTL and Arabic-script Kurdish characters often require the correct printer code page or encoding. Test with the exact printer model and firmware you deploy. Keep a small fixture receipt that exercises Kurdish letters, numbers, and mixed Latin/Kurdish lines.

Integrate via domain events. For example, listen to OrderPaid or InvoiceIssued, then dispatch a print job. Make the job idempotent where possible so retries do not produce duplicate receipts, or clearly document that duplicates are acceptable.

Use a fake transport in tests. If the package exposes a transport or printer abstraction, bind a fake in the test container and assert on the generated ESC/POS payload rather than hitting hardware. At minimum, unit-test receipt formatting separately from the printer connection.

Provide a manual reprint path. Operations teams will need to reprint a receipt without recreating the order. Expose an artisan command or admin action that dispatches the same print job.

Gotchas and Tips

• v0.5.1 is not a bug-fix release. It is the same code as 0.5.0, republished from cleaned git history. Do not expect behavioural changes or fixes in this version.
• Old versions cannot be installed. Any composer.json, lockfile, CI cache, or deployment script pinned to 0.1.0–0.5.0 will fail. Update constraints to ^0.5.1 and refresh the lockfile.
• Audit commit references. If your lockfile or internal documentation references a specific commit from the old history, verify it still resolves. After changing the constraint, run composer update rawand201/kurdish-escpos and commit the updated lockfile.
• Clear caches after upgrading. Run composer dump-autoload and clear Laravel config/package caches in deployment pipelines, especially if the package provider or config was cached.
• Printer encoding is the most common failure point. Kurdish glyphs may print as question marks or mojibake if the code page is wrong. Keep a known-good test receipt and compare output after any printer firmware or package change.
• Network printers fail quietly. Set connection timeouts and log failures. Queue retries should have a bounded attempt count, and failures should be visible to operators rather than silently dropping receipts.
• Debug with raw bytes. When output looks wrong, capture the generated ESC/POS payload and inspect it with a hex viewer. This distinguishes formatting bugs from printer/encoding problems.
• Check Laravel and PHP constraints. Because this is a pre-1.0 package, confirm the supported Laravel/PHP matrix in composer.json before upgrading framework versions.
• Treat pre-1.0 as unstable. Pin to ^0.5.1 and review release notes before moving to 0.6 or later; minor versions may contain breaking changes.