Introduction à Laravel
Ce document à pour but de présenter le framework PHP Laravel. Il s'adresse principalement à des développeurs ayant déjà certaines connaissances en PHP, mais aussi ayant au moins déjà manipulé Composer et son système d'installation de bibliothèques.
Introduction
Laravel est un framework PHP qui fournit un ensemble de fonctionnalités souvent utilisées pour le fonctionnement d'applications Web. Autrement dit, le framework propose un ensemble d'outils puissants, tels que l'injection de dépendances, une surcouche reliant programmation objet et modèles relationnels, de tests unitaires etc... Il est évolutif et intègre au fur et à mesure des ses mises à jours les outils retenus comme essentiels à l'écosystème Web PHP, comme par exemple le système de cache partagé Redis, ou encore l'outil de conteneurisation de services Docker. Le framework est open-source, et du fait de sa couverture d'utilisation, est une option de choix sur le long terme.
Ressources
Ce cours se base sur plusieurs ressources :
Création d'une application
Les étapes et élements requis pour créér une nouvelle application Laravel sont listées étapes par étapes sur la documentation :
Utilisant à titre personnel Ubuntu, et afin de gagner un peu de temps, cette première partie sera présentée pour les Linuxiens avec l'outil "Sail".
Le reste du cours sera applicable sur n'importe quel OS.
La plupart des commandes utilisées par la suite se présenteront sous la forme "sail artisan ...". Si vous n'utilisez pas la bibliothèque, il suffit de remplacer "sail" par "php" .
Développement d'un projet sur un serveur contenant déjà PHP et Composer
Il est possible de créer directement un nouveau projet sur un serveur disposant déjà de Composer, qui se chargera de récupérer les fichiers sources et bibliothèques propres au fonctionnement de Laravel. La machine distante devra cependant être configurée de manière à fournir les services et dépendances nécessaires à notre application. Elle devra contenir au minimum les extensions suivantes :
PHP >= 7.4
BCMath PHP Extension
Ctype PHP Extension
Fileinfo PHP extension
JSON PHP Extension
Mbstring PHP Extension
OpenSSL PHP Extension
PDO PHP Extension
Tokenizer PHP Extension
XML PHP Extension
Développement d'un projet en local
Un des prérequis pour développer une application directement en local est une installation de Docker et Docker-Compose. Laravel 8 s'accompagne d'une bibliothèque Docker "Sail" reconfigurable, qui contient toutes les briques nécessaires au bon fonctionnement d'un nouveau projet (PHP, MySQL, Composer, serveur SMTP, Redis etc...). Le montage des conteneurs au début peut prendre un peu de temps.
# Récupération du projet par défaut contenant les principaux fichiers sources
curl -s https://laravel.build/example-app | bash
# Libre a vous de renommer le dossier ce que vous voulez
mv example-app CoursLaravel
cd CoursLaravel
./vendor/bin/sail up
Architecture du dossier de l'application
Une fois le projet créé, une nouvelle arborescence s'est ajoutée dans son dossier. Celle-ci comporte tous les éléments nécessaires à son bon fonctionnement :
app : le dossier contenant le code principal de l'application. C'est en majorité dans celui-ci que nous serons amenés à développer. Ses sous-dossiers contiennent l'ensemble des objets mis à disposition par Laravel qui seront présentés par la suite.
bootstrap : ce dossier contient un fichier app.php sur lequel le framework "démarre". Il contient également une série de fichiers de cache générés automatiquement lors de l'utilisation de l'application, pour ses routes et services.
config : le dossier contenant les variables de configurations du projet. Dans l'ensemble ces variables sont insérées sous la forme de tableaux "Clé-Valeur" accessibles dans l'ensemble du projet lors de son exécution.
database : ce dossier va contenir tous les traitements associés à la base de données de notre application. Il contiendra : les "Migrations" : les requêtes associées aux modifications à la création / modification des tables. les "Seeders" : des fichiers sources associés à de l'insertion de données dans nos tables (pour de la création de lignes par défaut ou des tests unitaires). les "Factories" : des fichiers sources contenant la logique de génération des modèles insérés par les Seeders. C'est ici que nous instancierons des classes de test avec des valeurs aléatoires, ou bien au contraire des modèles fixés par défaut, qui pourront être nécessaires au bon fonctionnement de l'application. Les Seeders s'occupent de l'insertion en base, en utilisant les Factories pour la génération de données.
public : le dossier contenant tous les fichiers accessibles de l'extérieur. C'est dans ce dossier que vont se trouver nos fichiers CSS, JS, audio / images etc... C'est également ici que nous retrouverons notre fichier index.php, le point d'entrée de l'application.
resources : ce dossier contiendra les vues et les chaînes de traduction.
routes : ce dossier contiendra les différentes routes de l'application. Chaque fichier correspond à un point d'accès particulier, et liste les actions associées à nos différentes URI.
storage : ce dossier contient le cache des vues générées depuis les templates. Il contient également un dossier app/public stockant les fichiers associés aux utilisateurs (photo de profil, attestations PDF...), vers lequel un lien symbolique pourra être créé dans le dossier /public, de manière à les rendre accessibles depuis les postes clients. Une commande artisan est prévue à cet effet :
php artisan storage:linktests : le dossier qui contiendra l'ensemble de nos tests unitaires (PHPUnit)
vendor : le dossier contenant les dépendances Composer
D'autres fichiers sont également disponibles à la racine du dossier :
artisan : le point d'entrée des commandes éxécutables
php artisan.env : le fichier contenant toutes nos variables d'environnement (configurations/identifiants bases de données, clés API, valeurs par défaut ...). Si celui-ci n'existe pas, un fichier .env.example contenant certaines variables est copiable.
composer.json / composer.lock : le fichier de configuration associé à Composer
package.json / webpack.mix.js : Laravel peut se combiner avec Node.js, et certaines de ses bibliothèques en dépendent.
phpunit.xml : le fichier de configuration PHPUnit pour les tests unitaires
server.php : ce fichier pouvant servir de point d'entrée alternatif, de manière à simuler un mod_rewrite Apache.
Avant de continuer...
A minima les champs certains champs par défaut doivent être renseignés dans notre .env :
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=courslaravel
DB_USERNAME=sail
DB_PASSWORD=password
Afin d'indiquer à l'application quelle base de données utiliser pour la suite du cours.
A vérifier : Si vous utilisez une base de données sur un serveur distant, le schéma par défaut doit être au préalable créé
Cycle de vie d'une requête au travers de l'application
Le point d'entrée de l'application se situe dans le dossier "public/index.php".
Le schéma ci-dessous présente la liste des traitements effectués de la réception de la requête jusqu'à génération de la réponse.
En synthèse :
L'utilisateur envoie une requête à l'application
L'application reçoit la requête et instancie toutes les classes nécessaires à son bon fonctionnement
La requête est analysée puis traitée ou rejetée si jugée inconforme
La réponse est générée
Le Middleware est comme une surcouche permettant de vérifier les données / requêtes avant d'autoriser l'accès à celles-ci, ou un outil permettant de formater une réponse avant de la renvoyer au poste client. Certains d'entre eux existent par défaut lors de la création d'un nouveau projet, pour vérifier les jetons CSRF de nos futurs formulaires.
Les notions de conteneurs / fournisseurs de services feront l'objet d'un chapitre dédié, car ils sont associés à des fonctionnalités un peu plus poussées du framework, associées à de bonnes pratiques de programmation. Pour les plus curieux ou en avance, un tutoriel vidéo en français réalisé par Grafikart décrit très bien cette partie.
Invité de commandes Artisan
Le framework se munit d'un ensemble de commandes accessibles depuis la racine du projet. Les différentes commandes peuvent être listées de la manière suivante :
sail artisan
Laravel Framework 8.44.0
Usage:
command [options] [arguments]
Options:
-h, --help Display help for the given command. When no command is given display help for the list command
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi Force ANSI output
--no-ansi Disable ANSI output
-n, --no-interaction Do not ask any interactive question
--env[=ENV] The environment the command should run under
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
Available commands:
clear-compiled Remove the compiled class file
db Start a new database CLI session
down Put the application into maintenance / demo mode
env Display the current framework environment
help Display help for a command
inspire Display an inspiring quote
list List commands
migrate Run the database migrations
optimize Cache the framework bootstrap files
serve Serve the application on the PHP development server
test Run the application tests
tinker Interact with your application
up Bring the application out of maintenance mode
auth
auth:clear-resets Flush expired password reset tokens
cache
cache:clear Flush the application cache
cache:forget Remove an item from the cache
cache:table Create a migration for the cache database table
config
config:cache Create a cache file for faster configuration loading
config:clear Remove the configuration cache file
db
db:seed Seed the database with records
db:wipe Drop all tables, views, and types
event
event:cache Discover and cache the application's events and listeners
event:clear Clear all cached events and listeners
event:generate Generate the missing events and listeners based on registration
event:list List the application's events and listeners
key
key:generate Set the application key
make
make:cast Create a new custom Eloquent cast class
make:channel Create a new channel class
make:command Create a new Artisan command
make:component Create a new view component class
make:controller Create a new controller class
make:event Create a new event class
make:exception Create a new custom exception class
make:factory Create a new model factory
make:job Create a new job class
make:listener Create a new event listener class
make:mail Create a new email class
make:middleware Create a new middleware class
make:migration Create a new migration file
make:model Create a new Eloquent model class
make:notification Create a new notification class
make:observer Create a new observer class
make:policy Create a new policy class
make:provider Create a new service provider class
make:request Create a new form request class
make:resource Create a new resource
make:rule Create a new validation rule
make:seeder Create a new seeder class
make:test Create a new test class
migrate
migrate:fresh Drop all tables and re-run all migrations
migrate:install Create the migration repository
migrate:refresh Reset and re-run all migrations
migrate:reset Rollback all database migrations
migrate:rollback Rollback the last database migration
migrate:status Show the status of each migration
notifications
notifications:table Create a migration for the notifications table
optimize
optimize:clear Remove the cached bootstrap files
package
package:discover Rebuild the cached package manifest
queue
queue:batches-table Create a migration for the batches database table
queue:clear Delete all of the jobs from the specified queue
queue:failed List all of the failed queue jobs
queue:failed-table Create a migration for the failed queue jobs database table
queue:flush Flush all of the failed queue jobs
queue:forget Delete a failed queue job
queue:listen Listen to a given queue
queue:prune-batches Prune stale entries from the batches database
queue:restart Restart queue worker daemons after their current job
queue:retry Retry a failed queue job
queue:retry-batch Retry the failed jobs for a batch
queue:table Create a migration for the queue jobs database table
queue:work Start processing jobs on the queue as a daemon
route
route:cache Create a route cache file for faster route registration
route:clear Remove the route cache file
route:list List all registered routes
sail
sail:install Install Laravel Sail's default Docker Compose file
sail:publish Publish the Laravel Sail Docker files
schedule
schedule:list List the scheduled commands
schedule:run Run the scheduled commands
schedule:test Run a scheduled command
schedule:work Start the schedule worker
schema
schema:dump Dump the given database schema
session
session:table Create a migration for the session database table
storage
storage:link Create the symbolic links configured for the application
stub
stub:publish Publish all stubs that are available for customization
vendor
vendor:publish Publish any publishable assets from vendor packages
view
view:cache Compile all of the application's Blade templates
view:clear Clear all compiled view files
Cet ensemble de commande fournit une liste d'actions permettant d'accélérer le développement du projet et permet entre autres de générer des classes, vider un cache généré automatiquement par l'éxécution de l'application, gérer une liste de batch. Au fur et à mesure de l'avancement de ce cours, nous parcourerons chacune d'entres-elles, étant donné qu'elles sont reliées à toutes les fonctionnalités proposées par le framework.
Attardons nous pour l'instant sur 4 groupes de commandes qu'il est nécessaire de comprendre au minimum avant de commencer à programmer.
Key
La première étape à réaliser, une fois l'ensemble des bibliothèques Composer téléchargées et le serveur web configuré, est de générer la clé de chiffrement de l'application. Cette clé sera utilisée par tous les outils de chiffrement proposés par Laravel, comme par exemple le stockage des mots de passes.
sail artisan key:generate
Application key set successfully.
Une fois générée, cette clé est insérée dans les premières lignes du fichier .env situé à la racine du projet.
head .env | grep 'APP_KEY='
APP_KEY=base64:rWcRAE5HhLCm+zJhqWkz4G1BQFP7oHRBvnDSacCwXto=
Bien sûr cette clé doit être conservée dans ce fichier, et ne doit pas être divulguée.
Make
Les commandes Make sont associées à la création de classes et d'entités internes au framework, dans lesquelles nous serons amenés à développer au fil des leçons. Pour la majorité d'entres-elles, il est recommandé de passer par ces commandes pour les instancier, étant donné que la création de certaines d'entres-elles génèrent des liaisons dans certains fichiers de configuration.
A titre d'exemple, la création d'une migration, de son modèle et de son contrôleur dont nous nous servirons dans les chapitres suivants. Nous prendrons l'exemple métier dans ce cours d'une librairie, et nous utiliserons en principal objet un Book (celui sans les cornes).
sail artisan make:migration create_books_table
Created Migration: 2021_06_01_122828_create_books_table
sail artisan make:model Book
Model created successfully.
sail artisan make:controller BookController
Controller created successfully.
Route
Les routes de notre application associent le nom de la requête à l'action à réaliser. Celles-ci sont stockées dans un cache par le framework, qui se génère à la première connexion d'un utilisateur, ou manuellement avec la commande :
sail artisan route:cache
Route cache cleared!
Routes cached successfully!
On remarquera que ce cache est vidé avant d'être regénéré.
Il est possible de lister les différents points d'entrées de l'application avec un
sail artisan route:list
+--------+----------+----------+-----------------------------+---------+------------+
| Domain | Method | URI | Name | Action | Middleware |
+--------+----------+----------+-----------------------------+---------+------------+
| | GET|HEAD | / | generated::h9vCSQeMmoj9T4zr | Closure | web |
| | GET|HEAD | api/user | generated::4zejXk1O2fdhfTzi | Closure | api |
| | | | | | auth:api |
+--------+----------+----------+-----------------------------+---------+------------+
Domain : Si la route nous redirige vers un site externe
Method : Le type de requête HTTP acceptée par nos routes
URI : L'URI de référence
Name : Il est possible d'attribuer un nom à chacune de nos routes de manière à les identifier facilement dans l'ensemble du projet. Par défaut les noms sont générés aléatoirement.
Action : La méthode a appeler
Middleware : Les middlewares associés à la route, listés par ordre de parcours
Migrate
Ces commandes sont associées aux requêtes d'altération des tables et sont détaillées dans le chapitre suivant. De manière à sauvegarder l'ordre dans lequel nos migrations vont être effectuées, une table directement instanciable est prévue à cet effet.
sail artisan migrate:install
Migration table created successfully.