Como añadir firma en una extensión o controlador de mi plugin

Este plugin trae de serie la pestaña de firma en presupuestos, pedidos, albaranes y facturas de cliente. Pero el mecanismo es genérico: cualquier modelo puede tener firma, porque el modelo FirmaDocumento guarda la referencia como model_name + model_code en la tabla firma_documentos.

Para añadir la firma a tus propios modelos tienes el trait FacturaScripts\Plugins\FirmarDocumentos\Lib\DocSignatureTrait.

Por qué todos los métodos devuelven un Closure

DocSignatureTrait está pensado para usarse indistintamente en una clase de Extension/ o en un controlador propio. Al registrar una extensión, el core recorre por reflexión todos los métodos públicos de la clase y exige que cada uno devuelva un Closure. Por eso el trait devuelve closures, y por eso la forma de invocarlos cambia según el contexto:

En una extensión la llamada pasa por ExtensionsTrait::__call, que liga el Closure al controlador y lo ejecuta. En un controlador propio hay que invocar el Closure devuelto: ya viene ligado a $this y a la clase del controlador, así que puede llamar a addHtmlView(), $this->permissions, etc.

Métodos del trait

saveFirmaAction() y deleteFirmaAction() devuelven true a propósito, para cortar el flujo normal del controlador después de procesar la acción.

Caso 1: extender un controlador existente

Es lo habitual cuando el controlador es del core o de otro plugin.

1. Crea la extensión

<?php
namespace FacturaScripts\Plugins\MiPlugin\Extension\Controller;

use Closure;
use FacturaScripts\Plugins\FirmarDocumentos\Lib\DocSignatureTrait;

/**
 * Añade la pestaña de firma a EditMiModelo.
 */
class EditMiModelo
{
    use DocSignatureTrait;

    public function createViews(): Closure
    {
        return function () {
            $this->createViewFirmaDocumento('firma');
        };
    }

    public function execPreviousAction(): Closure
    {
        return function ($action) {
            if ($action === 'save-firma') {
                return $this->saveFirmaAction();
            }

            if ($action === 'delete-firma') {
                return $this->deleteFirmaAction();
            }
        };
    }

    public function loadData(): Closure
    {
        return function ($viewName, $view) {
            $this->loadDataFirmaDocumento($viewName, $view);
        };
    }
}

Fíjate en que execPreviousAction no devuelve nada cuando la acción no es suya: así el core sigue con el flujo normal del controlador.

2. Regístrala en tu Init.php

public function init(): void
{
    $this->loadExtension(new Extension\Controller\EditMiModelo());
}

La ruta bajo Extension/ tiene que coincidir con la del controlador destino en Dinamic/.

Caso 2: un controlador propio

Si el controlador es tuyo, usa el trait directamente e invoca los closures:

<?php
namespace FacturaScripts\Plugins\MiPlugin\Controller;

use FacturaScripts\Core\Lib\ExtendedController\EditController;
use FacturaScripts\Plugins\FirmarDocumentos\Lib\DocSignatureTrait;

class EditMiModelo extends EditController
{
    use DocSignatureTrait;

    public function getModelClassName(): string
    {
        return 'MiModelo';
    }

    protected function createViews(): void
    {
        parent::createViews();

        ($this->createViewFirmaDocumento())('firma');
    }

    protected function execPreviousAction($action): bool
    {
        if ($action === 'save-firma') {
            return ($this->saveFirmaAction())();
        }

        if ($action === 'delete-firma') {
            return ($this->deleteFirmaAction())();
        }

        return parent::execPreviousAction($action);
    }

    protected function loadData($viewName, $view): void
    {
        parent::loadData($viewName, $view);

        ($this->loadDataFirmaDocumento())($viewName, $view);
    }
}

Con eso ya tienes la pestaña, el canvas, el guardado, el borrado, la validación de permisos y el enlace público funcionando.

El modelo FirmaDocumento

use FacturaScripts\Dinamic\Model\FirmaDocumento;

$firma = new FirmaDocumento();
if ($firma->loadFromModel('MiModelo', $codigo)) {
    echo $firma->getUrl();       // url de la imagen png, con token MyFiles
    echo $firma->signerLabel();  // nick del ERP, o nombre del firmante externo
    echo $firma->shareUrl();     // enlace público para firmar / consultar
    echo $firma->creation_date;
    echo $firma->ip;
}

Columnas relevantes:

Para guardar una firma desde código, usa Lib\FirmaStorage::save(), que se encarga del png, del registro y de sobrescribir la firma anterior si existía.

El enlace público

Lib\FirmaToken cifra model_name + model_code con AES-256-CBC y añade un HMAC de integridad, con una clave derivada de los datos de conexión de la instalación. Es determinista: el enlace de un documento es siempre el mismo. Deja de ser válido si cambia la contraseña de la base de datos.

El controlador Controller\FirmaPublica atiende ese enlace con $requiresAuth = false y un getPageData() vacío, así que no aparece en el menú ni en la lista de permisos. Acciones soportadas por querystring:

Si el token es inválido o el documento ya no existe, muestra sólo un aviso genérico.

Personalizar el PDF del enlace público

El PDF lo genera Lib\FirmaPdf: usa el FormatoDocumento de FacturaScripts para presupuestos, pedidos, albaranes y facturas, y la ficha del modelo (las columnas de su XMLView/Edit<Modelo>.xml) para cualquier otro modelo.

FirmaPdf usa ExtensionsTrait, así que no hay que heredar de nada: se personaliza con una extensión y pipes.

Devolver null significa "no me aplica": el pipe pasa a la siguiente extensión y, si ninguna responde, se usa el comportamiento por defecto. Comprueba siempre el modelo, para no cambiar el PDF de los demás.

<?php
namespace FacturaScripts\Plugins\MiPlugin\Extension\Lib;

use Closure;
use FacturaScripts\Dinamic\Model\MiModelo;

class FirmaPdf
{
    // opción sencilla: misma ficha, pero sólo con mis columnas
    public function pdfXmlView(): Closure
    {
        return function (string $modelName) {
            return $modelName === 'MiModelo' ? 'FirmaMiModelo' : null;
        };
    }

    // opción avanzada: genero yo el pdf entero
    public function pdfContent(): Closure
    {
        return function ($model) {
            if (false === $model instanceof MiModelo) {
                return null;
            }

            $export = new MiPdfExport();
            $export->newDoc('...');
            // ...
            return $export->getDoc();
        };
    }
}

// MiPlugin/Init.php
$this->loadExtension(new Extension\Lib\FirmaPdf());

Como en cualquier extensión, los métodos deben devolver un Closure y la ruta bajo Extension/ tiene que coincidir con la de la clase destino en Dinamic/ (Extension/Lib/FirmaPdf.php → Dinamic\Lib\FirmaPdf).

Propagación al transformar documentos

Extension/Lib/BusinessDocumentGenerator copia la firma al documento destino cuando se transforma un documento de venta (presupuesto → pedido → albarán → factura). Se reutiliza el mismo path, así que FirmaDocumento::delete() sólo borra la imagen del disco cuando ya no queda ningún registro apuntando a ella.

Cómo se incrusta la firma en el PDF

Se hace con dos extensiones del core, que ya vienen en el plugin:

• Extension/Lib/PDF/PDFDocument
• Extension/Lib/PlantillasPDF/BaseTemplate

Es decir, funciona tanto con las plantillas PDF clásicas como con las del plugin PlantillasPDF.