Démarrer avec Lumen

Ce tutoriel détaille l’installation de Lumen dans un environnement de dev et s’adresse à des personnes possédant des connaissances de base sur Laravel / Lumen :

  • les routes
  • php artisan
  • le design pattern MVC

Les commandes utilisées au cours du tutoriel sont des commandes bash pour Linux / Mac, pour les utilisateurs de Windows, bonne chance ! ;)

Installer Lumen

Pour installer Lumen, il faut utiliser Composer

php -r "readfile('https://getcomposer.org/installer');" > composer-setup.php 
php -r "if (hash('SHA384', file_get_contents('composer-setup.php')) === '41e71d86b40f28e771d4bb662b997f79625196afcca95a5abf44391188c695c6c1456e16154c75a211d238cc3bc5cb47') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;" 
php composer-setup.php 
php -r "unlink('composer-setup.php');"

On peut placer ensuite composer.phar où l’on veut, par exemple dans /Users/nicolas/bin et le renommer composer.

Sur Mac, le « vrai » nom des dossiers n’est pas traduit. Le dossier Utilisateurs est en réalité Users.

Une fois qu’on a Composer, on va télécharger l’installeur de Lumen

composer global require "laravel/lumen-installer"

Il faut ensuite ajouter ~/.composer/vendor/bin au PATH ou créer un alias. Pour se faire, il faut ajouter alias lumen=”~/.composer/vendor/bin/lumen” dans le fichier ~/.bashrc (ou .bash_aliases), ou ~/.zshrc pour ZSH, ~/.fishrc pour Fish.

Sur mac, vous pouvez le mettre dans ~/.bash_profile où “~” correspond à votre répertoire personnel. Si le fichier n’existe pas, il faudra le créer à la main.

Si vous avez déjà l’installer de Laravel, vous risquez d’obtenir une erreur suite à l’installation en global, en attendant une correction de la part des équipes Laravel / Lumen, il faudra en installer 1 en local et ajouter son chemin au PATH. Si vous souhaitez installer Laravel après avoir installé Lumen, vous aurez le même problème. Une solution consiste à supprimer guzzlehttp de votre dossier ~/.composer/vendor entre les 2 installations.

Créer son projet

Une fois Lumen installé, il est possible d’utiliser la commande lumen dans le terminal pour créer un nouveau projet avec le framework déjà déployé.

lumen new mon-super-projet

Cela va nous créer le dossier mon-super-projet.

Pour ne pas se prendre la tête avec l’URL Rewrite, apache, les .htaccess et ce genre de chose, on peut utiliser le serveur intégré à artisan :

Note : Depuis Lumen 5.2 le script serve n’est plus intégré à Lumen, on peut cependant utiliser le serveur inclus avec php avec la commande suivante, à la racine du dossier projet

php -S 127.0.0.1:8000 -t ./public

On peut alors accéder à la page d’accueil de Lumen à l’adresse http://localhost:8000

Configuration

Toute la configuration se passe dans le fichier .env.example qu’il faudra renommer en .env par la suite.

On y définit notamment :

  • la base de donnée à laquelle se connecter
  • le système de cache
DB_CONNECTION=mysql
DB_HOST=ADRESSE:PORT
DB_DATABASE=LE_NOM_DE_VOTRE_BDD
DB_USERNAME=VOTRE_USERNAME_MYSQL DB_PASSWORD=VOTRE_MOT_DE_PASSE_MYSQL
CACHE_DRIVER=array
SESSION_DRIVER=cookie
QUEUE_DRIVER=database

On donne à Lumen les informations nécessaires pour qu’il se connecte à la base de données. Je ne sais pas s’il crée pour vous la base de données, si elle n’existe pas.

Par défaut, Lumen utilise memcached pour gérer son cache et ses sessions, mais on peut le remplacer par n’importe quel autre driver défini dans la documentation de Laravel.

Fonctionnalités

Avec bootstrap/app.php, on indique à Lumen les différentes fonctionnalités à activer pour notre projet. Nous allons ici principalement décommenter des lignes déjà présentes dans le fichier.

Dotenv::load(__DIR__.'/../'); // ligne 5 
$app->withFacades(); // ligne 22 & 23 
$app->withEloquent();

Authentification

On peut également activer le système de compte intégré à Lumen en ajoutant au fichier .env :

AUTH_DRIVER=database
AUTH_MODEL=User
AUTH_TABLE=users

On lui dit de gérer l’authentification en se basant sur la table users de la base de données qui est gérée par le modèle User.

Il faut alors décommenter dans bootstrap/app.php :

<?php $app->middleware([
// 'Illuminate\Cookie\Middleware\EncryptCookies', 'Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse', 'Illuminate\Session\Middleware\StartSession',
// 'Illuminate\View\Middleware\ShareErrorsFromSession',
// 'Laravel\Lumen\Http\Middleware\VerifyCsrfToken',
]);

Migrations

Comme dans Laravel, il est possible avec Lumen d’utiliser des migrations pour gérer sa base de données. Il faut dans un premier temps initialiser la fonctionnalité via le terminal, en se plaçant à la racine du projet :

php artisan migrate:install

Toutes nos migrations vont se trouver dans le dossier database / migrations et on va créer la première (toujours à la racine) :

php artisan make:migration --create=users create_users_table

Un nouveau fichier va être créé, dans mon cas 2015_05_12_134841_create_users_table.php qui contient le minimum pour créer une table et la remplir.

Nous allons uniquement modifier la fonction up(), afin d’ajouter des colonnes supplémentaires à notre future table. Par défaut, Lumen crée une table avec un id, la date de création et la date de dernière modification. On va lui rajouter :

$table->string('email');
$table->string('password');
$table->string('remember_token');

On peut ensuite « push » la migration sur la base de données :

php artisan migrate

Modèle

Pour que tout fonctionne, on doit créer notre modèle User, mais avant ça, on doit même créer notre répertoire Models avant d’y créer User.php, même si on va se contenter d’un fichier plutôt vide :

namespace App\Models;
use Illuminate\Database\Eloquent\Model;
final class User extends Model { }

Lumen se chargera pour nous de remplir le modèle avec toutes les colonnes de la table correspondante.

Peupler la base

On va créer dans database/seeds le fichier UserTableSeeder.php que l’on va utiliser pour ajouter des éléments de test dans notre table users :

use App\Models\User;
use Illuminate\Database\Seeder;
class UserTableSeeder extends Seeder
{
public function run()
{
User::create([
'email' => "claude@gmail.com",
"password" => Hash::make("jean")
]);
User::create([
'email' => "francis@gmail.com",
"password" => Hash::make("benoit")
]);
}
}

On va donc créer 2 faux utilisateurs pour notre application, en prenant soin de hasher le mot de passe, chose que fera également Lumen lorsqu’il vérifiera si les informations entrées correspondent à un utilisateur.

Il faut ensuite qu’on ajoute dans la fonction run() de database/seeds/DatabaseSeeder :

$this->call('UserTableSeeder');

et qu’on mette à jour la liste des fichiers de composer via le terminal, à la racine du projet :

composer dump-autoload

Si vous obtenez un message d’erreur indiquant que le numéro de version de composer est invalide, il va falloir le mettre à jour :

composer self-update

On peut alors peupler notre base de données :

php artisan db:seed

Tester nos modifications

On va ajouter 2 routes dans app/Http/routes.php pour tester que notre installation fonctionne bien.

Check

Route toute simple qui va uniquement exécuter Auth::check() et retourner son résultat. Comme la fonction retourne un booléen, on utilise json_encode() pour que Lumen accepte d’afficher la valeur (et pas une horrible exception).

$app->get('/check', function() {
return response()->json(Auth::check());
});

En allant sur http://localhost:8000/check, on obtient normalement false. La fonction Auth::check() sert à vérifier si un utilisateur est déjà connecté.

Co

Pour vérifier que tout marche, on va définir une nouvelle route dans laquelle on va connecter un de nos utilisateurs :

$app->get("/co", function() {
if (\Auth::attempt(array("email" => "claude@gmail.com", "password" => "jean"))) {
return "It works";
} else {
return json_encode(\Auth::check());
}
});

Si on va sur http://localhost:8000/co, on obtient le résultat It works (si vous avez utilisez les mêmes utilisateurs que moi). Si on modifie l’email ou le mot de passe, on obtient false : le résultat de Auth::check()avec un utilisateur non connecté.

Une fois les tests terminés, il est conseillé de supprimer ces routes, surtout la dernière qui donne accès à une session connectée à n’importe qui.

Originally published at blog.justenico.fr.