Migration de base de données

Si vous prévoyez d’étendre NexoPOS avec des modules, vous pourriez envisager d’interagir avec la base de données. Mais, sauf si vous avez l’intention d’utiliser la base de données existante, vous devrez créer vos tables ou peut-être ajouter de nouvelles colonnes aux tables existantes. Ce guide expliquera comment créer des migrations pour votre module.

Qu’est-ce qu’une migration ?

Une migration correspond à un fichier qui s’exécute pendant un processus de mise à niveau visant à modifier le schéma de la base de données. Mais elle ne s’y limite pas, car elle peut aussi être utilisée pour :

Créer de nouvelles autorisations et de nouveaux rôles
Effectuer une modification en masse sur les entrées actuelles
Etc.

Notez qu’une fois qu’une migration a été exécutée, elle ne peut pas être exécutée à nouveau, sauf si NexoPOS perd le suivi de cette migration. Cela peut être fait à l’aide de la commande migration forget.

Bonnes pratiques en matière de migration

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

La meilleure technique consiste à attribuer un nom unique à chacune de vos migrations, même si la tâche est effectuée sur la même table.

En général, les migrations qui mettent à jour des tables existantes doivent commencer par « Update », par exemple « UpdateBookingTableMarch10 » ou « UpdateBookingTablePriceColumn ». Dans tous les cas, vous devez vous assurer que le nom est unique, car vous pourriez avoir besoin de créer une autre migration pour cette table à l’avenir.

Si vous souhaitez créer de nouvelles tables dans votre fichier de migration, le nom de votre fichier peut commencer par « Create », par exemple « CreateBookingTable ».

Créer une migration avec une commande

NexoPOS est livré avec une commande qui vous aide à créer une migration pour votre module. Voici la signature de cette commande :

php artisan modules:migration {moduleNamespace}

Où {moduleNamespace} doit être remplacé par votre identifiant de module réel. Juste après avoir soumis cette commande, il vous sera demandé de fournir le nom de votre migration.

L’invite restera ouverte pour les migrations ultérieures ; tapez « Q » pour quitter.

Dans votre répertoire Migrations, vous pourrez voir votre fichier de migration.

Comment créer un tableau

Comme NexoPOS est construit sur Laravel, vous devrez suivre les instructions de la documentation Laravel pour les migrations. Toutefois, comme le fichier de migration peut être exécuté plus d’une fois, nous vous invitons à effectuer une vérification et à vérifier si :

Le tableau que vous souhaitez créer existe
La colonne que vous souhaitez ajouter/supprimer existe.

Ils sont décrits dans la même documentation ici.

Mise à jour en masse des enregistrements existants

Si vous avez certaines entrées dans votre système, après avoir effectué une migration qui modifie une structure, vous pouvez récupérer ces entrées à l’aide de leur modèle afin d’effectuer une mise à jour en masse. Pour les entrées trop volumineuses à mettre à jour, vous pouvez envisager de déclencher une tâche asynchrone.

Créer des rôles et des autorisations

Les migrations sont l’endroit idéal pour créer des rôles et des autorisations pour votre module. Vous pouvez suivre les instructions qui sont partagées pour la création d’un rôle et d’autorisations.

Quelles sont les méthodes « up » et « down » ?

NexoPOS utilise ces méthodes pour effectuer (up) et annuler (down) une modification dans la base de données. Cela signifie que si vous souhaitez que NexoPOS effectue une modification dans la base de données, vous devez écrire votre code dans la méthode « up ». Lorsque votre module est désinstallé, NexoPOS exécutera la méthode « down » pour toutes vos migrations.

En général, nous ne supprimons pas les colonnes ajoutées aux tables créées par le module. Toutefois, pour annuler les modifications apportées à des tables externes, vous devrez vérifier à nouveau si cette colonne existe.

Dépendances de migration

Vous pourriez parfois vouloir qu’une migration s’exécute si un autre module sur votre système est installé et activé. Cela garantira, au cas où vous voudriez modifier le schéma de ce module, que les tables du module soient créées.

Vous n’aurez qu’à fournir une constante DEPENDENCIES à votre module, qui est un tableau contenant les modules « 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();
                }
            });
        }
    }
}

Dans cet exemple, la méthode « up() » ne sera exécutée que si le module « NsGastro » (qui est l’espace de noms du module Gastro) est installé et activé. Notez que la migration peut dépendre de plusieurs modules à la fois.

Cela signifie que le module « YourModule » peut fonctionner normalement et mettra automatiquement à jour le schéma dès que Gastro est installé et activé. Cela garantira que le module fonctionne avec les dépendances comme sans elles.

# Comment exécuter les migrations

Vous n’avez pas besoin d’exécuter une migration ; NexoPOS effectuera la migration automatiquement. À chaque fois qu’une migration est effectuée pour le module, un enregistrement est sauvegardé dans la table « modules_migrations ». Supprimer cet enregistrement forcera NexoPOS à exécuter à nouveau cette migration. Pour que NexoPOS reste rapide, toutes les migrations exécutées sont mises en cache afin d’éviter des appels inutiles à la base de données. Vous devrez ensuite effacer le cache à l’aide de la commande suivante :

php artisan cache:clear

Annuler la migration du module

Au cours du développement de votre module, vous pourriez avoir besoin de réinitialiser la migration créée jusqu’à présent. Pour cela, vous utiliserez la commande suivante :

php artisan modules:migration --forget {moduleNamespace}

Assurez-vous de remplacer {moduleNamespace} par l’espace de noms du module pour lequel vous souhaitez réinitialiser les migrations.