🖨️ Cómo Crear un Nuevo Tipo de Ticket en FacturaScripts

Este documento describe cómo extender el plugin de Tickets de FacturaScripts para añadir nuevos tipos de tickets, permitiendo la personalización de la impresión de documentos.

1. 📄 Crea tu Clase de Ticket Personalizada

Deberás crear una nueva clase que extienda la clase abstracta FacturaScripts\Dinamic\Lib\Tickets\BaseTicket. Esta clase contiene la lógica específica para tu tipo de ticket y la interfaz básica.

Debes añadir a esa clase obligatoriamente el método print() y también añadir setBody() para la personalización.

Por ejemplo: Crear un ticket personalizado TestNewTicket\Lib\Tickets\TestTicket que imprima pedidos y facturas:

<?php

namespace FacturaScripts\Plugins\TestNewTicket\Lib\Tickets;

use FacturaScripts\Core\Template\ExtensionsTrait;
use FacturaScripts\Dinamic\Model\Agente;
use FacturaScripts\Dinamic\Model\TicketPrinter;
use FacturaScripts\Dinamic\Model\User;
use FacturaScripts\Core\Template\ModelClass;
use FacturaScripts\Plugins\Tickets\Lib\Tickets\BaseTicket;
use FacturaScripts\Dinamic\Model\Ticket;

class TestTicket extends BaseTicket
{
    use ExtensionsTrait;

    /**
     * Método estático para imprimir el ticket.
     * Aquí es donde implementarás la lógica de impresión.
     * Normalmente el código aquí siempre es el mismo
     *
     * @param ModelClass $model
     * @param TicketPrinter $printer
     * @param User $user
     * @param Agente|null $agent
     * @return bool
     */
    public static function print(ModelClass $model, TicketPrinter $printer, User $user, ?Agente $agent = null): bool
    {
        // Inicializa la impresora virtual
        static::init();

        // Creamos el ticket donde se guardará la salida
        $ticket = new Ticket();
        $ticket->idprinter = $printer->id;
        $ticket->nick = $user->nick;

        // cambia el título al nombre de tu ticket personalizado
        $ticket->title = self::$i18n->trans('test-ticket-min') . ' ' . $model->codigo;

        // el agente es opcional así que se asigna si existe
        if ($agent) {
            $ticket->codagente = $agent->codagente;
        }

        // generamos el header por defecto o personalizado
        static::setHeader($model, $printer, 'TICKET DE PRUEBA');
        // generamos el cuerpo del ticket por defecto o personalizado
        static::setBody($model, $printer);
        // generamos el footer por defecto o personalizado
        static::setFooter($model, $printer);

        // guardamos el ticket
        $ticket->body = static::getBody();
        $ticket->base64 = true;
        $ticket->appversion = 1;

        // devolvemos si se ha podido guardar correctamente
        // si se guarda, se añade automáticamente a la cola de impresión
        return $ticket->save();
    }

    /**
     * Sobrescribe este método para personalizar el cuerpo del ticket.
     * Aquí puedes añadir o modificar las líneas de los artículos, totales, etc.
     *
     * @param ModelClass $model
     * @param TicketPrinter $printer
     */
    protected static function setBody(ModelClass $model, TicketPrinter $printer): void
    {
        // Ejemplo de cómo añadir una línea personalizada
        self::$escpos->text("--- ESTE ES UN TICKET DE PRUEBA ---\n\n");

        // comprobar si es una factura
        if (in_array($model->modelClassName(), ['FacturaCliente', 'FacturaProveedor'])) {
            // imprimir detalles
            self::$escpos->text(self::$i18n->trans('factura') . ": " . $model->codigo . "\n");
        }
        // comprobar si es un pedido
        if (in_array($model->modelClassName(), ['PedidoCliente', 'PedidoProveedor'])) {
            // imprimir detalles
            self::$escpos->text(self::$i18n->trans('pedido') . ": " . $model->idpedido . "\n");
        }

        // propiedades comunes de pedido y factura
        self::$escpos->text(self::$i18n->trans('fecha') . ": " . $model->fecha . "\n");
        self::$escpos->text(self::$i18n->trans('cliente') . ": " . $model->nombrecliente . "\n\n");

        ///// Gestión del ancho del papel:

        // imprimir texto teniendo en cuenta el ancho total disponible en caracteres
        $anchoTotal = $printer->linelen;
        $textoIzquierda = "Precio";
        $textoDerecha = "12,34";

        // Calcula el espacio de relleno para alinear el texto a la derecha
        // si es negativo entonces no cabe
        $relleno = $anchoTotal - strlen($textoIzquierda) - strlen($textoDerecha);

        // Imprime la línea rellenando el espacio entre los caracteres
        self::$escpos->text($textoIzquierda . str_repeat('.', $relleno) . $textoDerecha . "\n");

        // Llama a la implementación de la clase padre para mantener la lógica original
        parent::setBody($model, $printer);
    }
}

2. ✍️ Registra tu Nuevo Tipo de Ticket

Para que FacturaScripts reconozca tu nuevo tipo de ticket, debes registrarlo en el método init() de la clase Init de tu plugin. Para ello se utiliza el método SendTicket::addFormat(), que requiere tres parámetros:

$className: El nombre completo de tu clase de ticket (ej: MiTicketPersonalizado::class).
$modelName: El nombre del modelo de documento al que se aplica (ej: 'FacturaCliente').
$label: El texto que se mostrará en la interfaz de usuario para seleccionar este formato.

Ejemplo: TestNewTicket/Init.php

<?php

namespace FacturaScripts\Plugins\TestNewTicket;

use FacturaScripts\Core\Template\InitClass;
use FacturaScripts\Plugins\TestNewTicket\Lib\Tickets\TestTicket;
use FacturaScripts\Dinamic\Controller\SendTicket;

class Init extends InitClass
{
    public function init(): void
    {
        // Registra el nuevo tipo de ticket para Facturas de Cliente y Factura proveedor
        SendTicket::addFormat(
            TestTicket::class,
            'FacturaCliente',
            'Ticket de Prueba'
        );
        SendTicket::addFormat(
            TestTicket::class,
            'FacturaProveedor',
            'Ticket de Prueba'
        );

        // Registra el nuevo tipo de ticket para Pedidos de Cliente y Pedido proveedor
        SendTicket::addFormat(
            TestTicket::class,
            'PedidoCliente',
            'Ticket de Prueba'
        );
        SendTicket::addFormat(
            TestTicket::class,
            'PedidoProveedor',
            'Ticket de Prueba'
        );
    }

    public function uninstall(): void
    {
        // Limpieza de datos o configuraciones al desinstalar el plugin
    }

    public function update(): void
    {
        // Ajustes al instalar o actualizar el plugin
    }
}

3. 🤔 Consideraciones Adicionales

BaseTicket: Esta clase base proporciona una estructura fundamental y métodos de ayuda para la impresión (como setHeader, setBody, setFooter). Al extenderla, puedes sobrescribir estos métodos para personalizar completamente el contenido de tu ticket.
SendTicket: Este controlador es el encargado de gestionar y despachar los diferentes formatos de ticket. El método addFormat() es crucial para que tu tipo de ticket sea reconocido.
Traductor : Es importante usar el objeto static::$i18n disponible en BaseTicket para todas las traducciones dentro de tu ticket. NO debes usar Tools::trans() en los métodos del ticket personalizado.
Librería de Impresión: El plugin de Tickets utiliza la librería mike42/escpos-php para interactuar con impresoras de tickets. Asegúrate de consultar su documentación para opciones avanzadas de formato. Concretamente en los métodos set se usa \Mike42\Escpos\Printer, si necesitas consultar las limitaciones podrías empezar revisando esa clase.
No te olvides de añadir en el facturascripts.ini de tu plugin la linea require = 'Tickets' porque tu plugin dependerá de Tickets y por lo tanto si no está cargado Tickets no funcionará.