PHPackages                             puyu-pe/smeargle-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility &amp; Helpers](/categories/utility)
4. /
5. puyu-pe/smeargle-php

ActiveLibrary[Utility &amp; Helpers](/categories/utility)

puyu-pe/smeargle-php
====================

Utility for SweetTicketDesign and PukaHTTP

1.3.3(1y ago)1125MITPHPPHP &gt;=8.2.0

Since Aug 28Pushed 1y ago2 watchersCompare

[ Source](https://github.com/puyu-pe/smeargle-php)[ Packagist](https://packagist.org/packages/puyu-pe/smeargle-php)[ RSS](/packages/puyu-pe-smeargle-php/feed)WikiDiscussions main Synced today

READMEChangelog (8)DependenciesVersions (13)Used By (0)

 [![imagen smeargle](logo.png)](logo.png)

```
   ▄▄▄▄▄   █▀▄▀█ ▄███▄   ██   █▄▄▄▄   ▄▀  █     ▄███▄
  █     ▀▄ █ █ █ █▀   ▀  █ █  █  ▄▀ ▄▀    █     █▀   ▀
▄  ▀▀▀▀▄   █ ▄ █ ██▄▄    █▄▄█ █▀▀▌  █ ▀▄  █     ██▄▄
 ▀▄▄▄▄▀    █   █ █▄   ▄▀ █  █ █  █  █   █ ███▄  █▄   ▄▀
              █  ▀███▀      █   █    ███      ▀ ▀███▀
             ▀             █   ▀
                          ▀

```

[![Packagist License](https://camo.githubusercontent.com/0582a61335467617e75efaa3246974b7d7e4f1e5c9fdcbadcdae572310471556/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f707579752d70652f736d656172676c652d706870)](https://camo.githubusercontent.com/0582a61335467617e75efaa3246974b7d7e4f1e5c9fdcbadcdae572310471556/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f707579752d70652f736d656172676c652d706870)[![Packagist Version](https://camo.githubusercontent.com/e1a00f84411b85279697547fe064345db7ec0311d43ab467d015ccc8c2999340/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f707579752d70652f736d656172676c652d706870)](https://camo.githubusercontent.com/e1a00f84411b85279697547fe064345db7ec0311d43ab467d015ccc8c2999340/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f707579752d70652f736d656172676c652d706870)[![Packagist Stars](https://camo.githubusercontent.com/fbecc5ae001fc020f2cb9786712bea13f83e3d1249f9fb5f660ffce49d3fc699/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f707579752d70652f736d656172676c652d706870)](https://camo.githubusercontent.com/fbecc5ae001fc020f2cb9786712bea13f83e3d1249f9fb5f660ffce49d3fc699/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f707579752d70652f736d656172676c652d706870)

[Smeargle](https://www.youtube.com/watch?v=Y9DENCQMSgQ) es un conjunto de utilidades y clases escrita en php según las especificaciones en formato json de [SweetTicketDesign](https://github.com/puyu-pe/SweetTicketDesign/tree/develop)para el diseño de tickets que seran emitidas a ticketeras termicas con la ayuda de [PukaHTTP](https://github.com/puyu-pe/puka-http).

Indice 🗂️
---------

[](#indice-card_index_dividers)

1. [¿Cómo funciona?](#funcionamiento-bookmark_tabs)
2. [Utilidades](#utilidades-toolbox)
3. [Bloques de texto](#textos-y-tablas-con-estilos)
4. [Imágenes](#im%C3%A1genes)
5. [Código QR](#c%C3%B3digo-qr)

Comenzando 🚀
------------

[](#comenzando-rocket)

Agregar la libreria mediante composer.

```
composer require puyu-pe/smeargle-php
```

[![Packagist Downloads](https://camo.githubusercontent.com/819ab107ba01a6a830184d2498006062f22d4a5615858ae3edb3676ecadfab1a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f707579752d70652f736d656172676c652d706870)](https://camo.githubusercontent.com/819ab107ba01a6a830184d2498006062f22d4a5615858ae3edb3676ecadfab1a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f707579752d70652f736d656172676c652d706870)[![GitHub Release Date](https://camo.githubusercontent.com/a170ff7f85bffb85afe6d79ae039f94b68451516d99eeef18e7380f69319468d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652d646174652f707579752d70652f736d656172676c652d706870)](https://camo.githubusercontent.com/a170ff7f85bffb85afe6d79ae039f94b68451516d99eeef18e7380f69319468d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652d646174652f707579752d70652f736d656172676c652d706870)

Funcionamiento 📑
----------------

[](#funcionamiento-bookmark_tabs)

Smeargle es un conjunto de clases y utilidades para la generación de un objecto json que representa un documento de impresión para [PukaHTTP](https://github.com/puyu-pe/puka-http). El objecto json esta construido segun la api de [SweetTicketDesign](https://github.com/puyu-pe/SweetTicketDesign/tree/develop).

### Core de la libreria

[](#core-de-la-libreria)

Los componentes principales de la libreria son 4, según las especificaciones de SweetTicketDesign.

```
{
    "properties": {
    },
    "data": {
    },
    "openDrawer": {
    },
    "styles": {
    }
}
```

Para cada uno de los componentes principales existen sus respectivas clases SmgProperties (properties), SmgTextBlock - SmgImageBlock - SmgQrBlock (data), SmgDrawer (opendrawer) y SmgMapStyles (styles).

```
$styles = SmgMapStyles::builder()
    ->addGlobalStyle(Smg::normalize())
    ->set("centerBoldStyleClass", Smg::centerBold());

$properties = SmgProperties::builder()
    ->setBlockWidth(48);

$text = SmgTextBlock::builder()
    ->addText("hello world. áéíóú")
    ->addCell(SmgCell::build("title", "centerBoldStyleClass"));
$image = SmgImageBlock::builder()->setPath("/home/images/logo.png");
$qr = SmgQrBlock::builder()->setData("dfadsf|sadfsadf|dsfasdf|dafsa|fadsfsa");
```

El objeto json que representa a todos los componentes se le denomina SmgPrintObject, una instancia de esta clase ayuda a registrar cada componente en el objeto de impresión.

```
$printObject = SmgPrintObject::builder()
    ->setStyles($styles)
    ->setProperties($properties)
    ->openDrawer()
    ->addBlock($text)
    ->addBlock($qr)
    ->addBlock($image);
```

El metodo toJson() del objeto SmgPrintObject genera el json string que es lo que finalmente se enviará a PukaHTTP

```
echo json_encode(json_decode($printObject->toJson(), true), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
```

Diseñar con smeargle puro implica crear primeramente los estilos asociados a clases para luego diseñar la disposición de los textos, images y qr en base a estas clases. El objeto SmgPrintObject es el que finalmmente ayuda a integrar cada uno de los 4 componentes representando de esta manera un objeto de impresión.

```
$printObject = SmgPrintObject::builder()
    ->setStyles($styles)         // styles
    ->setProperties($properties) // properties
    ->openDrawer()               // openDrawer
    ->addText("hello world")     // data
    ->addBlock($text)            // data
    ->addBlock($qr)              // data
    ->addBlock($image);          // data
    ->toJson();                  // json string to send PukaHTTP
```

Jugar con los 4 componentes permite crear varios diseños de impresión, sin embargo sigue siendo algo complejo de administrar. Es por ello que smeargle-php trae incluido una serie de utilidades para diseñar de forma mas descriptiva y sencilla los documentos de impresión.

Utilidades 🧰
------------

[](#utilidades-toolbox)

Jugar con los 4 componentes permite crear varios diseños de impresión, sin embargo sigue siendo algo complejo de administrar. Es por ello que smeargle-php trae incluido una serie de utilidades para diseñar de forma mas descriptiva y sencilla los documentos de impresión.

- **Smg**, shortcuts para styles y properties
- **SmgStylizedRow**, representa una fila de impresión con estilos y generación de clases automáticas.
- **SmgTextLayout**, mejora el modo de diseño de bloques de texto y tambien aprovecha la generación de clases automáticas
- **SmgTicket**, incluye una serie de metodos para mejorar el mecanismo de diseño de los documentos de impresión.

### La clase SmgTicket

[](#la-clase-smgticket)

SmgTicket pretende ser una plantilla generica para el diseño de tickets Se puede crear una instancia de la clase SmgTicket con su método estatico builder().

```
$ticket = SmgTicket::builder()
```

Opcionalmente se puede pasar un objeto properties y un conjunto de estilos.

```
$properties = SmgProperties::builder()->setBlockWidth(48);
$styles = new SmgMapStyles();
$styles->addGlobalStyle(Smg::normalize(true));
$ticket1 = SmgTicket::builder($properties, $styles)
$ticket2 = SmgTicket::builder($properties);
$ticket3 = SmgTicket::builder(null, $styles);
```

Con una instancia de SmgProperties se configura el blockWidth que es una representación abstracta del número de caracteres máximo con tamaño de fuente pequeña, que puede contener una linea en el papel termico. Es importante establecer este valor, de acuerdo al ancho del papel termico, por lo general sus valores suelen ser 42 y 48 para la mayoria de papeles termicos.

Opcionalmente también se pude personalizar el método de corte que se realiza siempre al finalizar el trabajo de impresión.

```
$properties = SmgProperties::builder()
    ->setCut(SmgCutProperty::builder()
        ->feed(2)
        ->mode(SmgCutMode::FULL))
    ->setBlockWidth(48);
```

También se puede configurar estilos globales validos en todo el objeto de impresión, esto puede ser util si en caso sea necesario normalizar todo el documento de impresión o aplicar algun estilo global por defecto.

```
$styles = SmgMapStyles::builder()
    ->addGlobalStyle(Smg::normalize(true))
    ->addGlobalStyle(Smg::center());
```

### Textos y tablas con estilos.

[](#textos-y-tablas-con-estilos)

Utilizando una instancia de la clase SmgTicket podemos diseñar bloques de texto que ocupen todo una linea del documento de impresión o tambien se puede dividir la linea en columnas, para representar columnas se necesita una instancia de SmgStylizedRow.

```
$ticket = SmgTicket::builder()
    ->addText("title", Smg::title())
    ->addRow(SmgStylizedRow::build()
        ->add("column1", Smg::leftBold())
        ->add("column2", Smg::centerBold()))
    ->addLine('*')
    ->addLine('-')
    ->addLine();
```

### Imágenes

[](#imágenes)

Para representar una imágen creamos una instancia de la clase SmgImageBlock mediante su método estatico builder(), utilizando esta instancia se puede configurar una ruta local a la imagen.

```
$imageBlock = SmgImageBlock::builder()->setPath("/home/images/logo.png");
```

Los estilos configurables para las imágenes, son width, height, scale, align

```
$imageBlock = SmgImageBlock::builder()->setPath("/home/images/logo.png");
$ticket = SmgTicket::builder($properties, $styles)
    ->addImage($img, Smg::width(290)->height(290)->scale(SmgScale::SMOOTH)->center())
```

Importante mencionar que que si la imagen no esta correctamente alineada, puede deberse a que el parametro blockWidth no tiene un valor acertado. El valor de blockWidth por defecto es de 42 caracteres por linea, para papeles termicos de 72 mm el tamaño deseado seria 48.

### Código Qr

[](#código-qr)

Para representar un código qr, se debe instanciar un objeto SmgQrBlock mediante su método estatico builder() y se configurar el stringQr mediante el método setData().

```
$qr = SmgQrBlock::builder()->setData("20450523381|01|F001|00000006|0|9.00|30/09/2019|6|sdfsdfsdf|");
```

Igual que las imágenes, tambien es posible configurar estilos para un objeto qr como width, height, scale y align.

```
$qr = SmgQrBlock::builder()->setData("20450523381|01|F001|00000006|0|9.00|30/09/2019|6|sdfsdfsdf|");
$ticketJson = SmgTicket::builder()
    ->addQrCode($qr, Smg::width(290)
        ->height(290)
        ->scale(SmgScale::SMOOTH)
        ->center())
    ->toJson();
```

#### Configuración propiedades Qr

[](#configuración-propiedades-qr)

Opcionalmente se puede configurar el nivel de corrección de error, y el tipo de QR.

```
$qr = SmgQrBlock::builder()
    ->setData("20450523381|01|F001|00000006|0|9.00|30/09/2019|6|sdfsdfsdf|")
    ->setCorrectionLevel(SmgQrErrorLevel::H)
    ->setQrType(SmgQrType::NATIVE);
```

Los niveles de corrección de error permitidos son low, medium, high y quartile. Por defecto, si no se configura, es quartile.

```
$qr = SmgQrBlock::builder()
    ->setCorrectionLevel(SmgQrErrorLevel::L)
    ->setCorrectionLevel(SmgQrErrorLevel::M)
    ->setCorrectionLevel(SmgQrErrorLevel::H)
    ->setCorrectionLevel(SmgQrErrorLevel::Q);
...
```

##### ¿Qr Type?

[](#qr-type)

El tipo de qr es una propiedad especial que indica como debe ser tratado el Qr, existen dos formas, "native" y "img". El modo "native" significa que el qr sera tratado de forma nativa por la impresora termica y "img" índica que el qr sera tratado previamente como imagen y luego imprimirse como imagen.

###### ¿Cual escoger?

[](#cual-escoger)

Por defecto el tipo es "img", ya que asegura que se respetara la propiedad blockWidth para alinear correctamente el qr. Existen ticketeras que no son compatibles con los comandos de alineación, es por eso que SweetTicketDesign se encarga de tratar el qr como imagen para redimensionarlo y alinearlo y enviarlo en formato imagen a la impresora termica. Asegurando la correcta alineación del qr en cualquier ticketera (siempre y cuando la impresora termica soporte imágenes).

```
$qr = SmgQrBlock::builder()->setQrType(SmgQrType::IMG) // por defecto;
```

Si se configura como "native", entonces sera la misma ticketera encargada de generar y alinear el qr. esto no asegura la correcta impresión del código qr en algunas ticketeras, ya que cada impresora termica interpreta el código qr de forma distinta. Esto quizas sea util si la impresora termica no soporta imágenes, pero puede que si soporte impresión de código qr de forma nativa.

```
$qr = SmgQrBlock::builder()->setQrType(SmgQrType::NATIVE);
```

Otra diferencias son:

- La propiedad "scale" solo funciona si el Qr Type es "img".
- La propiedad "size" varia de 1 a 16 si el Qr Type es "native", siendo 16 el tamaño maximo posible.
- En cambio si es "img", la propiedad "size", no tiene limite, siendo 16 un tamaño muy pequeño y 290 un tamaño aceptable (similar a size=16 en nativo.).

###  Health Score

33

—

LowBetter than 77% of packages

Maintenance39

Infrequent updates — may be unmaintained

Popularity13

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~5 days

Total

11

Last Release

515d ago

Major Versions

0.1.2 → 1.0.02024-09-10

### Community

Maintainers

![](https://www.gravatar.com/avatar/c642eee481d7256c466e884d7b0098c28e57e5309d3afd148fd90c9696bf9ea6?d=identicon)[PuyuPe](/maintainers/PuyuPe)

---

Top Contributors

[![OscarDevCPP](https://avatars.githubusercontent.com/u/143469741?v=4)](https://github.com/OscarDevCPP "OscarDevCPP (83 commits)")

### Embed Badge

![Health badge](/badges/puyu-pe-smeargle-php/health.svg)

```
[![Health](https://phpackages.com/badges/puyu-pe-smeargle-php/health.svg)](https://phpackages.com/packages/puyu-pe-smeargle-php)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
