migraciones

Skill: Migraciones en FacturaScripts

Las migraciones permiten ejecutar operaciones sobre datos de la base de datos de forma controlada, una única vez, tras instalar o actualizar un plugin. Se registran en MyFiles/migrations.json para evitar su re-ejecución.

Importante: Las migraciones son para cambios en datos, NO para cambios en la estructura de las tablas. La estructura se gestiona automáticamente mediante los archivos XML en Table/.

Cuándo usar migraciones

• Rellenar nuevos campos con valores por defecto para registros existentes
• Migrar valores al nuevo formato cuando cambia un campo
• Normalizar datos de versiones anteriores
• Limpiar registros huérfanos o referencias rotas
• Corregir valores incorrectos detectados en versiones anteriores

Generar con fsmaker

fsmaker migration

Genera un archivo base en Migration/ listo para completar.

Estructura de archivos

Plugins/MiPlugin/
├── Init.php
└── Migration/
    ├── RellenarEstadoPedidos.php
    ├── NormalizarCodigosPostales.php
    └── LimpiarDatosLegacy.php

Paso 1: Crear la clase de migración

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

use FacturaScripts\Core\Template\MigrationClass;

/**
 * Rellena el campo 'prioridad' para clientes existentes al actualizar a v1.2.0.
 */
class RellenarPrioridadClientes extends MigrationClass
{
    // Identificador único — debe ser descriptivo e incluir versión o fecha
    const MIGRATION_NAME = 'rellenar_prioridad_clientes_v1.2.0';

    public function run(): void
    {
        // Siempre verificar que la tabla existe
        if (!$this->db()->tableExists('clientes')) {
            return;
        }

        $sql = "UPDATE clientes SET prioridad = 'normal' WHERE prioridad IS NULL OR prioridad = ''";
        $this->db()->exec($sql);
    }
}

Paso 2: Registrar en Init.php

Las migraciones se ejecutan en el método update() del Init.php:

<?php
namespace FacturaScripts\Plugins\MiPlugin;

use FacturaScripts\Core\Base\InitClass;
use FacturaScripts\Core\Migrations;

class Init extends InitClass
{
    public function init(): void
    {
    }

    public function update(): void
    {
        // Una sola migración
        Migrations::runPluginMigration(new Migration\RellenarPrioridadClientes());

        // O varias migraciones en orden cronológico
        Migrations::runPluginMigrations([
            new Migration\FixV1_0_0(),
            new Migration\FixV1_1_0(),
            new Migration\RellenarPrioridadClientes(),
        ]);
    }
}