#1 découverte FilamentPHP : installation & listing

Dans cette série de tutoriels, nous allons progressivement explorer les fonctionnalités de FilamentPHP jusqu'à la mise en place d'un panel d'administration (backoffice) gérant vos utilisateurs à la fois complet et fonctionnel.

• #1 Installation & listing
• #2 Création et édition
• #3 Les relations

Pour ce premier chapitre, nous allons uniquement nous focaliser sur l'installation du package, découvrir son vocabulaire et créer notre première page d'un CRUD !

1. À quoi est destiné FilamentPHP ?
2. Vocabulaire
3. L'installation
4. Authentification
5. Le provider
6. Première page du CRUD : le listing

À quoi est destiné FilamentPHP ?

Filament se décrit lui-même comme un ensemble de composants facilitant la création d'un backoffice complet et fonctionnel entièrement en PHP.

Le design, la validation des données, le listing, l'édition, la création ... tout sera géré en quelques lignes de PHP, dans une approche minimaliste, vous n'aurez aucunement besoin d'écrire des lignes de HTML ou de JavaScript pour constituer vos pages et formulaires.

Le package est propulsé par un puissant couple Livewire et Tailwind CSS permettant d'obtenir à la fois des pages responsives et interactives tout en étant bien évidemment soutenu par Laravel.

Bien que proposant des composants ouverts à l'extension et déjà bien fourni en fonctionnalités, Filament reste un cadre relativement strict qui impose sa vision d'un backoffice.

Si votre besoin est complexe ou relativement exotique, l'utilisation de ce package pourrait s'avérer contre-productive, nous vous recommandons fortement d'embrasser les contraintes de Filament si vous souhaitez pleinement profiter de l'outil.

Filament ne répondra pas à tous vos cas d'usage et des questions de performances et de sécurité pourraient également rapidement apparaître, dans tous les cas, le package sera un allié judicieux pour créer les backoffice de vos applications ou atteindre rapidement un MVP à la fois viable et totalement fonctionnel !

Vocabulaire

Avant d'installer le package, essayons d'appréhender davantage son vocabulaire.

Filament permet la création de panels, un panel englobe toute la configuration de haut niveau telle que l'authentification, que nous aborderons dans la suite de cet article, et possède des ressources.

De plus, chaque ressource comprend plusieurs pages dédiées à l'encapsulation des actions spécifiques pour chaque types d'opérations, comme la création, le listing et l'édition d'un modèle.

Au fil de ces articles, nous étudierons les différentes fonctionnalités de Filament aboutissant à la création d'un véritable CRUD !

L'installation

À ce jour, le package est dans sa version majeure 3.* depuis aout 2023, il nécessite au minimum une version 8.1 de PHP :

1composer require filament/filament:"^3.0-stable" -W

Une roadmap complète du projet est disponible à cette URL.

Une fois le package installé dans votre Laravel, créons notre premier panel qui deviendra par la suite la base de ce tutoriel à l'aide de la commande suivante :

1php artisan filament:install --panels

Au lancement de cette commande, Filament vous demandera de nommer votre panel, ce qui déterminera son URL, dans le cadre de ce tutoriel nous l'appellerons "admin" et sera disponible à l'URL : /admin.

Une fois la commande exécutée, un nouveau provider sera ajouté à votre application : App\Providers\Filament\AdminPanelProvider, ce dernier contient l'intégralité de la configuration de votre panel que nous allons désormais décortiquer.

Le provider

Voyons étape par étape les principales fonctionnalités présentes dans notre AdminPanelProvider :

1->default()
2->id('admin')
3->path('admin')
4->login()
5->colors([
6    'primary' => Color::Amber,
7])

La méthode path détermine l'URL racine de votre panel qui contiendra par la suite des pages et des ressources.

La méthode login permet quant à elle de configurer la page d'authentification permettant d'accéder à votre Panel, par défaut, si vous ne renseignez aucune classe spécifique, la classe Filament\Pages\Auth\Login sera instanciée et correspondra à la page par défaut d'authentification de Filament.

Nous vous encourageons fortement à parcourir cette classe Filament\Pages\Auth\Login afin de comprendre les grandes étapes d'une authentification avec Filament et peut-être verrez-vous l'opportunité de l'étendre afin d'y ajouter vos propres fonctionnalités !

1->login(CustomPage::class)

Nous traiterons des pages dans un autre article de cette série de tutoriels.

Par nature, Filament est hautement configurable et vous permet d'ajouter des fonctionnalités à la volée, ajoutez les méthodes registration, passwordReset et profile activera automatiquement une page d'enregistrement pour vos utilisateurs, la possibilité de réinitialiser leur mot de passe ainsi que d'afficher leur profil ... c'est tout, sans la moindre configuration supplémentaire de votre part !

1->login()
2->registration() 
3->passwordReset() 
4->profile() 
5->colors([
6    'primary' => Color::Amber,
7])

Vous accéderez à ces différentes pages aux URL suivantes :

• /admin/register
• /admin/password-reset/request
• /admin/profile

Vous trouverez également sur cette page l'ensemble des possibilités offertes par Filament pour gérer vos utilisateurs.

Auto discover

À la création de notre Panel tout un ensemble de ressources et de pages ont été ajoutées automatiquement à votre projet.

Ces ressources doivent être référencées et liées à notre Panel grâce aux méthodes suivantes :

1->discoverResources(in: app_path('Filament/Resources'), for: 'App\\Filament\\Resources')
2->discoverPages(in: app_path('Filament/Pages'), for: 'App\\Filament\\Pages')
3->discoverWidgets(in: app_path('Filament/Widgets'), for: 'App\\Filament\\Widgets')

À moins que l'organisation interne des fichiers de Filament ne vous déplaise, vous n'aurez probablement pas l'occasion de modifier ces quelques méthodes.

Middleware

Un panel avec ses pages et ressources définissent automatiquement tout un ensemble de routes, cette méthode middleware permet simplement de définir les middlewares à exécuter avant d'arriver sur l'une d'entre elle.

 1->middleware([
 2    EncryptCookies::class,
 3    AddQueuedCookiesToResponse::class,
 4    StartSession::class,
 5    AuthenticateSession::class,
 6    ShareErrorsFromSession::class,
 7    VerifyCsrfToken::class,
 8    SubstituteBindings::class,
 9    DisableBladeIconComponents::class,
10    DispatchServingFilamentEvent::class,
11])
12->authMiddleware([
13    Authenticate::class,
14]);

Dans cette méthode, vous retrouverez les classiques middlewares que l'on pourrait normalement configurer dans le fichier App\Http\Kernel appliqués à vos routes de Laravel.

Les middlewares DisableBladeIconComponents et DispatchServingFilamentEvent sont quant à eux propres à la bonne exécution de Filament.

Authentification

Attention, par défaut vos panels seront accessibles à l'ensemble de vos utilisateurs sans aucune restriction.

Pour restreindre l'accès à vos panels, il sera nécessaire d'ajouter la méthode canAccessPanel ainsi que le trait FilamentUser à votre modèle User :

 1 namespace App\Models;
 2 
 3use Filament\Models\Contracts\FilamentUser; 
 4use Filament\Panel;
 5use Illuminate\Foundation\Auth\User as Authenticatable;
 6 
 7class User extends Authenticatable implements FilamentUser 
 8{ 
 9    public function canAccessPanel(Panel $panel): bool 
10    { 
11        return true; 
12    } 
13} 

La méthode canAccessPanel reçoit l'instance du panel auquel l'utilisateur cherche à accéder, cela vous sera utile si votre application dispose de plusieurs panels !

Filament dispose également d'une gestion multitenant que nous aborderons dans un futur article.

Première page du CRUD : le listing

Maintenant que Filament est installé à notre Laravel et que nous en savons un peu plus sur son vocabulaire, nous pouvons créer la première page de notre backoffice : le listing des utilisateurs.

Pour commencer, nous allons peupler la table users à l'aide de la factory présente par défaut dans votre application Laravel :

1\App\Models\User::factory(10)->create();

Une fois les lignes insérées en base de données, créons notre nouvelle ressource Filament à l'aide de la commande suivante :

1php artisan make:filament-resource User

Analysons la classe App\Filament\Resources\UserResource fraîchement créée, cette dernière possède plusieurs méthodes et propriétés intéressantes.

Tout d'abord, la propriété $model détermine le modèle associé à votre ressource, toutes les opérations d'écriture et de lecture partiront donc ce modèle :

1protected static ?string $model = User::class;

Notre ressource possède également les méthodes form, table, getRelations et getPages. Dans le cadre de ce tutoriel, nous nous concentrerons uniquement sur la méthode table permettant de configurer l'affichage de notre modèle et les actions associées :

 1public static function table(Table $table): Table
 2{
 3    return $table
 4        ->columns([
 5            //
 6        ])
 7        ->filters([
 8            //
 9        ])
10        ->actions([
11            Tables\Actions\EditAction::make(),
12        ])
13        ->bulkActions([
14            Tables\Actions\BulkActionGroup::make([
15                Tables\Actions\DeleteBulkAction::make(),
16            ]),
17        ]);
18}

Nous allons utiliser notre premier composant TextColumn afin d'afficher quelques informations basiques provenant du modèle User :

 1public static function table(Table $table): Table
 2{
 3    return $table
 4        ->columns([
 5            TextColumn::make('name') 
 6            TextColumn::make('email') 
 7            TextColumn::make('created_at'), 
 8        ])
 9    // [...]
10}

Dès lors, votre listing sera directement accessible en vous rendant à l'URL suivante : /admin/user !

Bien que fonctionnel, ce listing est encore limité et la grande force de Filament réside de la multitude de configurations disponibles permettant de rapidement personnaliser vos pages.

Par exemple, rendons le champ created_at triable et modifions son affichage pour connaître le nombre de jours depuis sa création :

 1public static function table(Table $table): Table
 2{
 3    return $table
 4        ->columns([
 5            TextColumn::make('name')
 6            TextColumn::make('email')
 7            TextColumn::make('created_at')
 8                ->since() 
 9                ->sortable(), 
10        ])
11    // [...]
12}

Nous pouvons également rendre la colonne facilement recherchable à l'aide de la méthode searchable :

 1public static function table(Table $table): Table
 2{
 3    return $table
 4        ->columns([
 5            TextColumn::make('name')
 6                ->searchable(), 
 7            TextColumn::make('email')
 8            TextColumn::make('created_at')
 9                ->since()
10                ->sortable(),
11        ])
12    // [...]
13}

Cette recherche est une simple requête like, Filament ne gère pas encore d'intégration de Laravel Scout pour effectuer une recherche full text !

Nous utilisions jusqu'à présent le même composant TextColumn mais Filament en dispose de plus d'une dizaine, par exemple, IconColumn sera parfait pour mettre en place des icônes de toute sorte :

 1public static function table(Table $table): Table
 2{
 3    return $table
 4        ->columns([
 5            TextColumn::make('name')
 6                ->searchable(),
 7            TextColumn::make('email'),
 8            IconColumn::make('email_verified_at') 
 9                ->label('Verified') 
10                ->getStateUsing(function ($record): bool { 
11                    return (bool) $record->email_verified_at; 
12                }) 
13                ->trueColor('success') 
14                ->falseColor('warning'), 
15            TextColumn::make('created_at')
16                ->since()
17                ->sortable(),
18        ])
19    // [...]
20}

Maintenant que notre listing est davantage complet et enrichi, modifions le triage par défaut à l'aide de la méthode defaultSort :

1public static function table(Table $table): Table
2{
3    return $table
4        // [...]
5        ->defaultSort('created_at', 'desc'); 
6}

Pour finir, ajoutons la possibilité de filtrer les utilisateurs ayant validé leur adresse e-mail :

 1public static function table(Table $table): Table
 2{
 3    return $table
 4        // [...]
 5        ->filters([
 6            Filter::make('verified') 
 7                ->query(function (Builder $query): Builder { 
 8                    return $query->whereNotNull('email_verified_at'); 
 9                }) 
10        ])
11}

Comme vous venez de le voir, Filament propose une configuration de très haut niveau, très éloignée des impératifs frontaux, permettant de créer des interfaces entières en seulement quelques lignes de PHP.

Dans ce premier tutoriel, vous avez découvert le package et créé l'affichage de votre première ressource, dans un second chapitre nous aborderons la création et l'édition d'un modèle !

Source : https://github.com/laravel-fr/support-filamentphp

Mathieu De Gracia

Des fois, mon chat code à ma place 🐱