---
title: "Introduction"
description: "PHP Library for ESC/POS Printers"
type: "docs"
category: "doc"
tags: []
authors: [Anonymous]
date: "2026-09-09"
last_update: "2026-09-09"
time_minutes: 3
draft: false
unlisted: false
url: "https://www.derafu.dev/docs/utils/escpos/introduction"
---

# PHP Library for ESC/POS Printers

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/escpos/main)
![CI Workflow](https://github.com/derafu/escpos/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/escpos)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/escpos)
![Total Downloads](https://poser.pugx.org/derafu/escpos/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/escpos/d/monthly)

A PHP library for generating ESC/POS commands to communicate with thermal receipt printers.

Underneath, it uses [mike42/escpos-php](https://github.com/mike42/escpos-php) to talk to the printer, but that library is an implementation detail: nothing in this package's public API exposes a `Mike42\Escpos\*` type or constant. See [Architecture](./architecture) for why that matters and how it is enforced.

## Features

- Fluent, chainable API for common receipt printing tasks.
- Own vocabulary (enums and constants) for every ESC/POS value, instead of the underlying library's constants — see [Vocabulary](./vocabulary).
- 1D and 2D barcode generation, including PDF417 (native command or as a printed bitmap when the printer has no native support) — see [Printing Images](./images).
- Sending the generated bytes to a real network printer, without a raw socket or the underlying library's connectors — see [Network Delivery](./network-delivery).
- Special character handling and replacement.
- Receipt cutting and cash drawer opening.

## Installation

```bash
composer require derafu/escpos
```

## Quick Start

```php
use Derafu\Escpos\Enum\Justification;
use Derafu\Escpos\EscposPrinter;

// Initialize the printer. With no options, it buffers ESC/POS bytes in
// memory instead of talking to a real printer — useful for building the
// receipt and deciding what to do with the bytes afterwards.
$printer = new EscposPrinter();

// Print some text.
$printer
    ->println('Hello World!')
    ->setJustification(Justification::Center)
    ->println('Centered Text')
    ->println('Multiple lines')
    ->feed(2); // Add some empty lines.

// Finalize the receipt (adds final line breaks, cuts paper, opens the
// drawer if configured) and get the ESC/POS bytes.
$escposData = $printer->end();

// Do whatever you need with the bytes: return them from an API, save them
// to a file, or send them to a real printer (see Network Delivery).
echo $escposData;
```

## Configuration Options

The `EscposPrinter` constructor accepts an options array as its first argument:

| Option         | Type   | Default                                         | Description                                |
|-----------------|--------|--------------------------------------------------|---------------------------------------------|
| `connector`     | array  | `['type' => 'memory']`                          | Printer connector configuration. `memory` is the only type supported today — it buffers bytes so `dump()`/`end()` can return them. |
| `profile`       | string | `'default'`                                     | Printer capability profile (from Mike42's `capabilities.json`). |
| `cut`           | bool   | `true`                                          | Automatically cut the paper when `end()` is called. |
| `specialchars`  | bool   | `true`                                          | When `false`, accented characters (á, ñ, etc.) are replaced by their unaccented equivalent instead of being sent as-is. |
| `pulse`         | array  | `['pin' => 0, 'on_ms' => 120, 'off_ms' => 240]` | Cash drawer pulse, sent together with the cut when `cut` is `true`. |

A second, optional constructor argument lets you replace the default backend — see [Architecture](./architecture).

## Full Example

The repository's `examples/full-example.php` exercises every feature (text formatting, image, barcode, PDF417, special characters). Run it with:

```shell
php examples/full-example.php | nc 172.16.1.5 9100
```

**Note**: you need `netcat` installed, and `172.16.1.5`/`9100` should be the IP and port of your thermal printer. See [Network Delivery](./network-delivery) for a pure-PHP alternative to `nc`.



---
Last updated on 09/09/2026