Receipt Printer

laulamanapps/receipt-printer is a PHP library for building and printing receipts on POS receipt printers. It builds a receipt from a fluent, framework-agnostic command model and a driver turns that into the raw instruction bytes your printer understands.

This is the core package: the domain model, the ReceiptBuilder, the transports and the Printer/PrinterFactory. To actually talk to a printer you also install a driver for your hardware (see Ecosystem).

Features

• Fluent builder API with block nesting (api-reference)
• Text formatting: bold, negative (invert), underline, upperline, alignment, magnify, font
• Columns for items and prices, with wrapping
• Separators, feed, cut and cash-drawer
• Logos (printer-stored) and images (rasterised from a file)
• QR codes, PDF417, GS1 DataBar and 1D barcodes (EAN13, CODE128, …)
• Multiple transports: socket, USB, CUPS, Bluetooth, IPP
• Multiple models via pluggable drivers (tested printers)

---

Installation

The core package plus a driver — for Star Micronics printers:

composer require laulamanapps/receipt-printer laulamanapps/receipt-printer-driver-star-micronics

Minimum PHP 8.2

Using Symfony or Laravel? Use the integration package instead — it wires everything up from configuration (see Ecosystem).

---

Usage

1. Build a printer

A Printer is a printer settings object + a driver + a transport. The PrinterFactory wires the driver and transport together for you:

use LauLamanApps\ReceiptPrinter\Application\PrinterFactory;
use LauLamanApps\ReceiptPrinter\Domain\Enum\PaperWidth;
use LauLamanApps\ReceiptPrinter\StarMicronics\PrinterModel;
use LauLamanApps\ReceiptPrinter\StarMicronics\PrinterSettingsFactory;

// Settings describe the model + paper width (from the driver package)
$settings = (new PrinterSettingsFactory())->create(PrinterModel::MC_PRINT2, PaperWidth::SMALL);

// create() registers the bundled Star Micronics driver
$printer = PrinterFactory::create()->socket($settings, '192.168.0.12'); // host, port defaults to 9100

Or inject the driver(s) yourself:

use LauLamanApps\ReceiptPrinter\Application\PrinterFactory;
use LauLamanApps\ReceiptPrinter\StarMicronics\Driver\PrinterDriverFactory;

$factory = new PrinterFactory((new PrinterDriverFactory())->create());
$printer = $factory->socket($settings, '192.168.0.12');

2. Choose a transport

Pick the transport that matches how the printer is connected:

$factory->socket($settings, '192.168.0.12', 9100);   // network
$factory->usb($settings, '/dev/usb/lp0');             // USB (Linux)
$factory->cups($settings, 'Star_mC_Print2');          // CUPS queue (macOS/Linux)
$factory->bluetooth($settings, '00:11:62:00:00:00');  // Bluetooth
$factory->Ipp($settings, 'ipp://printer.local/...');  // IPP

You can add your own by implementing LauLamanApps\ReceiptPrinter\Domain\Contract\PrinterTransportInterface.

Only the socket transport is verified against real hardware so far. If you can confirm another transport works, please open a GitHub issue.

3. Print something

The quickest path is send() with a few commands:

use LauLamanApps\ReceiptPrinter\Domain\Command\Action\Cut;
use LauLamanApps\ReceiptPrinter\Domain\Command\Draw\Text;

$printer->send(
    [], // print settings (optional)
    new Text('Hello World!'),
    new Cut(partial: true),
);

4. Use the builder

For real receipts, use the ReceiptBuilder. Blocks opened with a style/layout method are closed with ->end():

use LauLamanApps\ReceiptPrinter\Domain\Enum\Alignment;
use LauLamanApps\ReceiptPrinter\Domain\Enum\FontType;
use LauLamanApps\ReceiptPrinter\Domain\ReceiptBuilder;

$date = (new \DateTime('+24 hours'))->format('Y-m-d H:i:s');

$receipt = ReceiptBuilder::create()
    ->align(Alignment::CENTER)          // enter center alignment
        ->bold()
            ->magnify(3)
                ->text('WiFi')
            ->end()
        ->end()
        ->newline()
        ->magnify(2, text: 'YourWifi')
        ->newline()
        ->separator()
        ->magnify(2)
            ->negative('12345-67890')   // white on black
        ->end()
        ->newline()
        ->font(FontType::B)
            ->text("Valid until {$date}")
        ->end()
        ->newline()
        ->separator('#')
        ->qrCode('WIFI:T:nopass;S:SSID;;', 8)
    ->end()
    ->cut(partial: true)
    ->build();

$printer->print($receipt);

A store receipt with a logo, columns and a barcode:

use LauLamanApps\ReceiptPrinter\Domain\Enum\Alignment;
use LauLamanApps\ReceiptPrinter\Domain\Enum\BarcodeType;
use LauLamanApps\ReceiptPrinter\Domain\ReceiptBuilder;
use LauLamanApps\ReceiptPrinter\StarMicronics\PrintSetting\CodePageSetting;

$receipt = ReceiptBuilder::create(new CodePageSetting())
    ->align(Alignment::CENTER)
        ->logo(2)                                   // logo stored in the printer's memory
        ->bold()
            ->magnify(2, text: 'MY STORE')
        ->end()
        ->text('123 Main Street')
        ->text('City, State 12345')
    ->end()
    ->feed()
    ->separator()
    ->column('1 x Cappuccino', '€4.50')             // left text, right-aligned price
    ->column('1 x Pizza', '€13.50')
    ->column('    2 x Deposit', fn ($right) => $right->negative('€0.30'))
    ->separator()
    ->bold()
        ->column('TOTAL', '€43.30')
    ->end()
    ->feed()
    ->align(Alignment::CENTER)
        ->text('Thank you for your purchase!')
        ->feed(2)
        ->barcode('123456', BarcodeType::CODE128)
    ->end()
    ->cut()
    ->build();

$printer->print($receipt);

Printing an image

$receipt = ReceiptBuilder::create()
    ->align(Alignment::CENTER)
        ->imageFile(__DIR__.'/logo.png', 384, 0) // width 384 dots, height 0 keeps aspect ratio
    ->end()
    ->cut(partial: true)
    ->build();

The driver rasterises the image (Floyd–Steinberg dithering, requires ext-gd) and clamps it to the printable width.

---

Ecosystem

Package	Purpose
laulamanapps/receipt-printer	Core domain model, builder, transports
laulamanapps/receipt-printer-driver-star-micronics	Driver for Star Micronics (mC-Print2/3, TSP650 II)
laulamanapps/receipt-printer-star-document-markup	Serialise a receipt to/from a text markup
laulamanapps/receipt-printer-cloudprnt	Star CloudPRNT server (printers pull jobs over http)
laulamanapps/receipt-printer-symfony-bundle	Symfony integration
laulamanapps/receipt-printer-laravel	Laravel integration

---

Contributing

1. Fork the repository
2. Make your changes and add tests
3. Run composer test
4. Submit a pull request