Laravel et Backpack - 1ʳᵉ Partie

Cet article est le premier d'une série d'articles consacrés à Laravel et Backpack.

Introduction

Depuis sa sortie initiale en 2011, Laravel a connu une croissance exponentielle. En 2015, il est devenu le framework PHP le plus étoilé de GitHub et est devenu le framework incontournable pour les utilisateurs partout dans le monde. Quant à Backpack, il vous permet de gérer les données de votre application en automatisant la création de vues pour créer et modifier des éléments d'une table d'une application Laravel.

Mon but avec ce didacticiel Laravel est de créer un guide pour ceux qui veulent apprendre Laravel. Ce guide vous emmènera du tout début d'une idée à une véritable application déployable.

Ce guide ne sera pas exhaustif, mais si vous voulez une introduction plus exhaustive, je vous conseille de consulter la documentation proposée en ligne par Laravel et Backpack.

Les pré-requis

Vérifiez que vous disposez des pré-requis nécessaires pour installer Laravel  :

  • Un environnement de développement local pour PHP >= 7.2.5
  • Un gestionnaire de base de données (j'utiliserai MySQL)
  • Les extensions PHP suivantes : OpenSSL, PDO, Mbstring, Tokenizer

Remarques : En ce qui concerne le développement local de PHP, je recommande Mac OSX. Je suggère en outre d'utiliser Visual Studio Code (VSCode) comme éditeur de code.

J'essaie de suivre le processus de création d'une nouvelle demande comme je le ferais en milieu réel.

Le projet

Aux fins du présent guide, nous créerons une application simple pour gérer l'annuaire des employés.

Voici une liste des principaux objectifs de cette mini app :

  • Créez un formulaire pour définir les titres d'emploi
  • Créer une formule de saisie des dossiers des employés
  • Valider les formulaires
  • Insérer les données dans la base de données

Mise en route d'un nouveau projet Laravel

Avec ce simple plan d'attaque décrit ci-dessus, il est temps de créer un tout nouveau projet vide. J'aime placer tous mes projets dans un répertoire ~/Sites, et ce tutoriel utilisera cet endroit.

  1. Connectez-vous à Bash avec VSCode à l'aide du terminal intégré en cliquant sur "Terminal" et ensuite sur "Nouveau terminal" dans la barre de menu.
mkdir ~/Sites
cd ~/Sites

2. Créer un projet Laravel au moyen de Composer en saisissant la commande suivante dans le terminal. On appellera ce projet "rh" :

composer create-project --prefer-dist laravel/laravel rh

3. Un nouveau répertoire ~/Sites/rh est créer et Laravel y est installé.

4. Ouvrez le projet dans Visual Studio Code. Pour ce faire, cliquez sur "Fichier" puis sur "Ouvrir le dossier ..." dans la barre de menu, et sélectionnez le dossier "rh".

5. Configurer les paramètres de base de données : Ouvrez le fichier ". env" qui se trouve à la racine de votre projet, et changez les valeurs dans la section "DB_" pour refléter les informations de votre base de données.

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=rh
DB_USERNAME=root
DB_PASSWORD=mot_de_passe

6. Base de données : Créer la base de données rh en utilisant la commande mysql ou encore phpMyadmin.

7. Vérifier l'installation : La meilleure façon de vérifier la connexion de votre base de données est d'effectuer la migration des tables Laravel.

php artisan migrate

Si tout s'est bien passé, vous devriez voir quelque chose comme ceci après avoir exécuté la commande migrate :

php artisan migrate

8. Lancer l'application : Exécuter la commande php artisan serve dans le terminal de Visual Studio Code.

php artisan serve

Un serveur de développement local sera ainsi mis en service sur le port 8000. Vous pouvez alors y accéder à l'application en ouvrant un navigateur et en accédant à l'URL http://localhost:8000. À cette étape, la page d'accueil standard de Laravel apparaît.

Ajout du paquet Backpack

  1. Installer Backpack en utilisant Composer : Assurez-vous que le répertoire actuel correspond bien à celui du projet, ~/Sites/rh. Ensuite, tapez la commande suivante :
composer require backpack/crud

2. Générez les fichiers de configuration de Backpack au moyen de la commande :

php artisan backpack:install

3. À l'invite de création d'un compte d'administrateur, répondez aux questions.

4. Personnalisez les fichiers de configuration : Pour répondre aux besoins de cette mini app modifiez les paramètres suivants dans le fichier de configuration  config/backpack/base.php :

  • 'project_name' => 'Tuto RH'
  • 'home_link' => 'rh'
  • 'project_logo'   => '<b>Tuto RH</b>'
  • 'route_prefix' => 'rh'

Le paramètre 'locale' dans le fichier de configuration 'config/app.php' de Laravel permet de définir la langue par défaut de l'application :

  • 'locale' => 'fr'

Le paramètre 'locale' est utilisé par Laravel pour localiser l'application, c'est-à-dire pour afficher les messages d'erreur, les textes des boutons et des formulaires, les formats de dates et d'heures, etc. dans la langue spécifiée.

Modèle, vue et contrôleur (MVC)

Dans Laravel, l'architecture MVC permet de séparer les différentes parties de l'application en trois couches distinctes :

Modèle : Il représente les données de l'application et gère la logique de persistance de ces données dans une base de données.
Vue : Il s'occupe de l'affichage des données pour l'utilisateur final.
Contrôleur : Il joue le rôle d'intermédiaire entre le modèle et la vue. Il traite les requêtes HTTP et gère la logique de l'application.

En plus du MVC, les routes et les fichiers de migration sont deux autres aspects fondamentaux de Laravel.

Route : Les routes définissent la façon dont les URL sont mappées à des actions dans votre application. Elles peuvent correspondre à des URL spécifiques et sont associées à une méthode de contrôleur qui sera appelée pour gérer la requête.

Migration : Les fichiers de migration, quant à eux, permettent de gérer les modifications à votre base de données. Les fichiers de migration peuvent être utilisés pour créer, modifier ou supprimer des tables et des colonnes dans votre base de données, ainsi que pour ajouter les données initiales.

En gros, les modèles gèrent les données, les contrôleurs gèrent la logique de traitement de l'application, les vues gèrent la présentation de l'interface utilisateur., les routes définissent la façon dont les différentes parties de l'application sont liées entre elles et les fichiers de migration permettent de gérer les modifications de la base de données de manière organisée et documentée.

Dans la section suivante nous allons créer les modèles et les fichiers de migration de l'application et subséquemment dans les prochains articles nous utiliseront Backpack pour créer les vues, les contrôleurs et les routes de l'appli.

Les modèles et leur migration

Les modèles de l'appli

  1. Créons les deux modèles de l'appli par la commande Laravel suivante :
php artisan make:model Employe
php artisan make:model Titre
Diagramme 1 - Diagramme Entité Relation

Deux fichiers sont créés sous le répertoire app/Models : Employé.php et Titre.php.

2. Modifier le modèle titre.php comme suit :

class Titre extends Model
{
    use HasFactory;

    /*
    |-------------------------------------------------------------
    | GLOBAL VARIABLES
    |-------------------------------------------------------------
    */

    protected $table = 'titres';
    // protected $primaryKey = 'id';
    // public $timestamps = false;
    protected $guarded = ['id'];
    protected $fillable = [
        'titre',
        'categorie_emploi',
        'statut'
    ];

}

Le code ci-dessus définit une classe Titre qui étend la classe Model de Laravel. La classe Model est la classe de base pour les modèles Eloquent de Laravel.

La variable $table définit le nom de la table de la base de données qui sera associée à ce modèle. Dans ce cas, le nom de la table est titres.

La variable $guarded définit une liste de propriétés qui ne peuvent pas être remplies par des données externes, telles que les données envoyées par une requête HTTP. Dans ce cas, la propriété id est protégée et ne peut pas être remplie.

La variable $fillable définit une liste de propriétés qui peuvent être remplies par des données externes. Les propriétés titre, titre_normalisé et statut peuvent être remplies par des données externes.

En résumé, cette classe définit un modèle Titre qui peut être utilisé pour interagir avec des données enregistrées dans la table titres de la base de données. Le modèle définit les propriétés $table, $guarded et $fillable pour contrôler la façon dont les données sont enregistrées dans la base de données.

3. Définissons ensuite le modèle Employé qui fait appel aussi à une relation avec le modèle Titre telle que représenté dans le diagramme d'entité relation ci-haut.

class Employe extends Model
{
    use HasFactory;

    /*
    |----------------------------------------------------------------
    | GLOBAL VARIABLES
    |----------------------------------------------------------------
    */

    protected $table = 'employes';
    // protected $primaryKey = 'id';
    // public $timestamps = false;
    protected $guarded = ['id'];
    protected $fillable = [
        'nom',
        'prenom',
        'sexe',
        'date_naissance',
        'matricule',
        'statut',
        'titre_id'
    ];

        /*
    |--------------------------------------------------------------
    | RELATIONS
    |--------------------------------------------------------------
    */

    // Foreign and local keys
    // https://laravel.com/docs/8.x/eloquent-relationships#one-to-many

    public function titre()
    {
        return $this->belongsTo(Titre::class);
    }
    
}

La méthode titre() définit une relation "belongsTo" entre le modèle Employé et le modèle Titre. Cela signifie que chaque employé appartient à un seul titre. La relation est définie en utilisant la méthode belongsTo de Laravel.

Les conventions de dénomination Laravel

Les noms de modèles en Laravel doivent commencer par une lettre ou un underscore et ne doivent contenir que des caractères ASCII pour éviter les problèmes de compatibilité. Les caractères accentués ne sont pas recommandés dans les noms de modèle.

Pour les noms de table dans une base de données, il est recommandé d'utiliser uniquement des caractères ASCII. Certaines bases de données, telles que MySQL, peuvent prendre en charge les caractères accentués dans les noms de table, mais cela peut causer des problèmes de compatibilité lors de l'utilisation avec différentes plates-formes et différents langages de programmation.

En ce qui concerne les noms de colonnes, cela dépend du système de gestion de base de données que vous utilisez. Certains systèmes de gestion de base de données, comme MySQL, prennent en charge les caractères accentués dans les noms de colonnes, tandis que d'autres ne le font pas. Il est donc toujours recommandé de vérifier la documentation de votre système de gestion de base de données pour déterminer les caractères pris en charge dans les noms de colonnes et planifier votre schéma de base de données en conséquence.

Les fichiers de migration

Les classes Employé et Titre ont été définies mais les attributs de leurs champs respectifs tels que les types de données (entier, texte, caractère, etc.), la longueur maximale et les contraintes de validation, n'ont pas été définis.

Un fichier de migration définit les modifications à apporter à la structure de la base de données de votre application. Les migrations sont utilisées pour créer, modifier ou supprimer des tables, des colonnes, des contraintes, etc. dans la base de données de l'application.

L'avantage de l'utilisation des migrations est qu'elles permettent de conserver l'historique des modifications apportées à la structure de la base de données. Cela facilite énormément la gestion des versions et les mises à jour, car vous pouvez facilement savoir ce qui a été modifié dans le passé, et comment remettre en place une ancienne version de la base de données si nécessaire.

Nous créons les fichiers de migration d'Employé et de Titre par les commandes :

php artisan make:migration create_titres_table
php artisan make:migration create_employes_table
  1. Les commandes ont produits deux fichiers sous le répertoire /database/migrations.
  2. Modifions le fichier de migration pour le modèle Titre pour y ajouter les champs :
    public function up()
    {
        Schema::create('titres', function (Blueprint $table) {
            $table->id();
            $table->timestamps();
            $table->string('titre');
            $table->string('titre_normalisé');
            $table->char('statut', 1);
        });
    }

Quelques explications s'imposent :

  • $table->id() définit simplement une colonne "id" avec les propriétés par défaut de Laravel pour une colonne de clé primaire auto-incrémentée.
  • $table->timestamps() est une méthode de Laravel qui permet de définir deux colonnes dans la table de base de données: "created_at" et "updated_at" soit la date et l'heure à laquelle une entrée a été créée ou mise à jour dans la table.
  • $table->string('titre') et $table->string('titre_normalisé') définit la colonne avec le type de données "string". Les données de type "string" peuvent stocker des chaînes de caractères de longueur variable, telles que des noms, des adresses e-mail, des descriptions, etc.
  • $table->char('statut', 1) définit une colonne de type "char" ne pouvant stocker d'un caractère.

3. Modifions le fichier de migration pour le modèle Employé pour y ajouter les champs :

public function up()
    {
        Schema::create('employes', function (Blueprint $table) {
            $table->id();
            $table->timestamps();
            $table->string('nom');
            $table->string('prénom');
            $table->char('sexe', 1);
            $table->date('date_naissance');
            $table->string('matricule')->nullable($value = true);
            $table->char('statut', 1);
            $table->bigInteger('titre_id')->unsigned();

            $table->foreign('titre_id')
            ->references('id')
            ->on('titres');
        });
    }

La seule nouveauté ici est la définition d'une contrainte de clé étrangère pour une colonne dans une table de base de données. Cette contraite spécifie qu'une colonne dans une table doit contenir une valeur correspondant à une entrée existante dans une autre table.

Dans ce cas, la méthode définit une contrainte de clé étrangère pour la colonne "titre_id" dans la table actuelle. La colonne "titre_id" doit contenir une valeur correspondant à une entrée existante dans la colonne "id" de la table "titres". Cela garantit que pour chaque entrée dans la table actuelle, il y a une entrée correspondante dans la table "titres".

Prochain article

Dans le prochain article nous exécuterons la migration pour appliquer les modifications définies dans les fichiers de migration à la structure de la base de données. Nous développerons aussi notre premier CRUD.