Statamic Peak

Article

Démarrer avec Lumen

Nicolas Kempf Le Stanc

Nicolas Kempf Le Stanc

0 min

Premier article consacré à Lumen, on voit comment l'installer et l'utiliser pour un nouveau projet.

Cet article date de 2015 et concerne Lumen 5.0.

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

Pour des informations sur les nouvelles versions du framework, vous pouvez consulter mon compendium sur Laravel.

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

Installer Lumen

Pour installer Lumen, il faut utiliser Composer.

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === 'e0012edf3e80b6978849f5eff0d4b4e4c79ff1609dd1e613307e16318854d24ae64f26d17af3ef0bf7cfb710ca74755a') { 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 autre solution consiste à supprimer guzzlehttp de votre dossier ~/.composer/vendor entre les 2 installations.

Le problème a été corrigé depuis.

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 :

php artisan serve
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, comme cet article concerne le développement à installer, on lui dit d’utiliser à la place des cookies.

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.

<?php 
// ligne 5 
Dotenv::load(__DIR__.'/../');
// ligne 22 & 23 
$app->withFacades();
$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 :

<?php
$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 :

<?php
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 :

<?php 
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.

Route de vérification de l'utilisateur

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).

<?php
$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é.

Route de connexion

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

<?php 
$app->get("/co", function() {
	if (\Auth::attempt(["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.