Migrazione del database

Se prevedi di estendere NexoPOS con moduli, potresti considerare l’interazione con il database. Tuttavia, a meno che tu non abbia intenzione di utilizzare il database esistente, dovrai creare le tue tabelle o magari aggiungere nuove colonne alle tabelle esistenti. Questa guida descriverà come puoi creare migrazioni per il tuo modulo.

Cos’è una migrazione

Una migrazione rappresenta un file che viene eseguito durante un processo di aggiornamento con l’obiettivo di modificare lo schema del database. Ma non si limita a questo, poiché può essere utilizzata anche per:

• Crea nuove autorizzazioni e ruoli
• Esegui una modifica in blocco sulle voci correnti
• Eccetera.

Nota che una volta eseguita una migrazione, non può essere eseguita di nuovo a meno che NexoPOS non perda traccia di quella migrazione. Questo può essere fatto utilizzando il comando migration forget.

Best Practices per le migrazioni

Les migrations sont stockées dans le dossier « Migrations » de votre module. Contrairement aux migrations Laravel, PSR-4 s’applique à ces fichiers, et ensuite, le nom de la classe doit correspondre beaucoup au nom du fichier. Vous n’êtes pas obligé de créer manuellement la migration, car vous pouvez utiliser la commande qui sera partagée ci-dessous.

La tecnica migliore consiste nel fornire un nome univoco per ciascuna delle tue migrazioni, anche se l’operazione viene eseguita sulla stessa tabella.

Di solito, le migrazioni che aggiornano tabelle esistenti dovrebbero iniziare con “Update”, ad esempio: “UpdateBookingTableMarch10” oppure “UpdateBookingTablePriceColumn”. In ogni caso, devi assicurarti che il nome sia univoco, poiché potresti dover creare un’altra migrazione per quella tabella in futuro.

Se vuoi creare nuove tabelle nel file di migrazione, il nome del file potrebbe iniziare con “Create”, ad esempio “CreateBookingTable”.

Creare una migrazione con un comando

NexoPOS viene con un comando che ti aiuta a creare una migrazione per il tuo modulo. Ecco la firma di quel comando:

php artisan modules:migration {moduleNamespace}

Dove {moduleNamespace} deve essere sostituito con il tuo identificatore di modulo effettivo. Subito dopo aver inviato questo comando, ti verrà chiesto di fornire il nome della tua migrazione.

Il prompt rimarrà aperto per le migrazioni successive; digita "Q" per uscire.

Nella tua directory delle migrazioni, potrai vedere il file di migrazione.

Come creare una tabella

Poiché NexoPOS è costruito su Laravel, dovrai seguire le istruzioni nella documentazione di Laravel per le migrazioni. Tuttavia, poiché il file di migrazione potrebbe essere eseguito più di una volta, ti invitiamo a effettuare una verifica e controllare se:

• La tabella che desideri creare esiste già.
• La colonna che desideri aggiungere/rimuovere esiste

Questi sono descritti nella stessa documentazione qui.

Aggiornamento massivo per record esistenti

Se hai alcune voci sul tuo sistema, dopo aver eseguito una migrazione che modifica una struttura, puoi recuperare queste voci utilizzando il loro modello per eseguire un aggiornamento in blocco. Per voci troppo grandi da aggiornare, potresti considerare l’invio di un job asincrono.

Creazione di ruoli e autorizzazioni

Le migrazioni sono il luogo perfetto per creare Ruoli e Permessi per il tuo modulo. Puoi seguire le istruzioni che sono condivise sulla creazione di un Ruolo e di un Permesso.

Quali sono i metodi "su" e "giù"

NexoPOS utiliza estos métodos para aplicar (up) y deshacer (down) una modificación en la base de datos. Esto significa que, si deseas que NexoPOS realice una modificación en la base de datos, debes escribir tu código en el método «up». Cuando se desinstale tu módulo, NexoPOS ejecutará el método «down» para todas tus migraciones.

Di solito, non annulliamo le colonne aggiunte alle tabelle create dal modulo. Tuttavia, per annullare le modifiche apportate alle tabelle esterne, dovrai controllare nuovamente se quella colonna esiste.

Dipendenze di migrazione

Potresti a volte voler eseguire una migrazione se un altro modulo sul tuo sistema è installato e abilitato. Questo garantirà, nel caso in cui tu voglia modificare lo schema di quel modulo, che le tabelle del modulo vengano create.

Dovrai semplicemente fornire una costante DEPENDENCIES al tuo modulo, che è un array con i moduli "namespace".

<?php
namespace Modules\YourModule\Migrations;

use App\Classes\Schema;
use Illuminate\Database\Schema\Blueprint;

class UpdateGastroModifiersGroup
{
    const DEPENDENCIES  =   [ 'NsGastro' ];
    
    public function up()
    {
        if ( ! Schema::hasTable('nexopos_gastro_modifiers_group') ) {
            Schema::table('nexopos_gastro_modifiers_group', function (Blueprint $table) {
                if (! Schema::hasColumn('nexopos_gastro_modifiers_group', 'wc_product_id')) {
                    $table->integer('wc_product_id')->nullable();
                }
            });
        }
    }
}

In questo esempio, il metodo "up()" verrà eseguito solo se il modulo "NsGastro" (che è lo spazio dei nomi del modulo Gastro) è installato e abilitato. Nota che la migrazione potrebbe dipendere da più moduli in quel momento.

Ciò significa che il modulo "YourModule" può funzionare normalmente e aggiornerà automaticamente lo schema ogni volta che Gastro viene installato e abilitato. Questo garantirà che il modulo funzioni sia con che senza le dipendenze.

# Come eseguire le migrazioni

Non è necessario eseguire una migrazione; NexoPOS eseguirà la migrazione automaticamente. Ogni volta che viene eseguita una migrazione per il modulo, viene salvata una registrazione nella tabella “modules_migrations”. Eliminare tale registrazione costringerà NexoPOS a eseguire nuovamente quella migrazione. Per mantenere NexoPOS veloce, tutte le migrazioni eseguite vengono memorizzate nella cache per evitare chiamate non necessarie al database. Successivamente, dovrai svuotare la cache utilizzando il seguente comando:

php artisan cache:clear

Ripristina migrazione del modulo

Durante lo sviluppo del tuo modulo, potresti dover reimpostare la migrazione creata finora. Per farlo, userai il seguente comando:

php artisan modules:migration --forget {moduleNamespace}

Assicurati di sostituire {moduleNamespace} con lo spazio dei nomi del modulo per cui vuoi ripristinare le migrazioni.