Printing to POS printer from PHP

Printing to POS printer from PHP

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Printing to POS Printer from PHP

Handling point-of-sale (POS) printing in a server-side architecture requires a specific approach that differs significantly from standard web printing. When an application runs on a server—whether accessed via desktop or mobile devices like an iPad—the rendering engine must reside on that server, not the client. This is especially true for legacy hardware scenarios where USB printers are directly connected to terminals rather than networked via IP.

The common solution for this scenario involves the ESC/POS command set. This protocol allows software to send raw instructions to the printer to control text formatting, graphics, and layout. While PHP has historically relied on extensions like php-printer, which is largely outdated and Windows-specific, the modern standard for handling these commands in a cross-platform environment is the mijag/mijago-php library (often referred to as escpos-php).

Implementing Server-Side Printing with ESC/POS

The core challenge in your scenario is moving away from plain text generation or PDF conversion. PDF files generally do not work well with direct thermal printers because these devices expect raw ESC/POS commands, not rendered documents. Attempting to pipe a PDF file path to the printer driver usually results in blank pages because the driver interprets the request as "print this file using my default settings," which often defaults to screen or fails on USB-only paths without proper spooler configuration.

To achieve the desired output—complete bills with logos and formatted text—you must generate the ESC/POS command stream directly. The escpos-php library abstracts these raw bytes into an object-oriented interface, making it much easier to handle complex layouts than manually concatenating \chr() calls.

Here is a practical implementation pattern for server-side printing:

use Mijag\MijagoPhp\Printer;

// Initialize the printer driver. 
// You must ensure the path points to the correct library or vendor directory.
$printer = new Printer();

// Set the paper width if your specific model differs from standard 58mm or 80mm
$printer->setPaperWidth(Printer::PAPER_80); 

// Define a custom receipt content with logo and formatted text
$content = [
    'header' => "OFFICIAL RECEIPT", // ESC/POS command for bold header
    'line' => '',
    'text' => ['text' => 'Welcome to our store', 'size' => Printer::SIZE_MEDIUM],
    'image' => [
        'path' => '/path/to/logo.png', 
        'width' => 50, // Width in pixels
        'height' => 150, // Height in pixels
        'border' => false,
    ],
    'text' => ['text' => 'Total Amount: $100.00', 'size' => Printer::SIZE_LARGE],
    'line' => '',
    'footer' => "Thank you for shopping with us!",
];

// Render the receipt to a temporary file or stream directly
$printer->set($content);

// The critical step: sending data to the device.
// For USB printers connected locally, we use the raw socket path.
// This bypasses the system print spooler which often handles PDFs incorrectly.
$printer->raw(function ($output) {
    echo "Printing output:\n" . $output;
});

// Note: In a production environment, you would typically 
// write the output to a temporary file and send it via the printer's raw path.
// The exact method depends on how your OS handles USB redirection.

Handling USB vs. Network Printers

A critical distinction in your deployment is the hardware interface. Network printers (IP) allow you to use standard system print queues, where you can define different destinations for bills versus kitchen orders based on environment variables or request parameters. However, USB printers present a hurdle: they are often bound to the specific machine they are plugged into.

If your customers maintain local terminals with USB-connected printers, you cannot rely solely on a central Apache server to print directly unless you implement a spooler service or use raw socket communication (often requiring raw() calls as shown above). The library must be able to detect the printer's IP if using network connections, but for USB devices, the connection is local.

To support both without forcing hardware changes, your application logic should route the print request based on configuration:

  • Network Printer: Send data via TCP/IP socket directly to the printer's IP address.
  • USB Printer: Send data via raw socket to the local loopback interface or a specific file path managed by the OS spooler (if configured for ESC/POS).

This dual-capability approach ensures that your iPad users can trigger print jobs destined for networked POS terminals, while desktop users with USB hardware see immediate output. The escpos-php library supports both modes seamlessly if the correct driver and connection parameters are provided.

Trade-offs and Considerations

One significant trade-off is the complexity of managing raw printer connections versus relying on a system print spooler. While the spooler simplifies job management (allowing multiple destinations for the same file), it introduces latency and potential formatting inconsistencies, especially with non-standard paper sizes or thermal printers that lack color ink capabilities.

Furthermore, generating images requires careful consideration of resolution. ESC/POS commands are resolution-dependent; sending a 300 DPI image to a printer expecting 203 DPI will result in distorted graphics. The library handles this conversion internally if the image path is provided, but verifying the aspect ratio of your logo against the printer's native width is essential to avoid stretching artifacts.

By shifting from legacy text-based methods or broken PDF workflows to a dedicated ESC/POS library, you gain precise control over the output format, enabling rich media and distinct layouts for different order types without compromising on hardware flexibility.

Our network