Comment créer un Helper Laravel ?

() translation by (you can also view the original English article)

Pour démarrer, je reprendrais la définition des helpers proposée par le site officiel de Laravel.

Laravel contient une grande variété de fonctions PHP relative aux "helpers". La plupart d'entre elles sont sollicitées par le framework lui-même. Mais il est aussi possible de les exploiter dans vos propres applications si vous estimez qu'elles sont pratiques.

Par conséquent, les helpers de Laravel sont des fonctions prêtes à l'emploi pouvant être appelés n'importe où au sein de votre application. S'ils n'avaient pas été placés au cœur du framework, vous seriez obligé de développer vos propres classes helper.

Même si son cœur en propose autant, il y a toujours la possibilité que vous devriez créer le votre et pour éviter de répéter le même code ici et là, vous devez le développer vous-même, afin de renforcer une meilleur maintenabilité. Vous apprendrez ici comment créer votre propre helper dans Laravel.

Les Helpers de Laravel

Comme nous venons de le voir, il y a quantité de helpers disponibles au sein du framework Laravel. Ils sont tous groupés selon la fonctionnalité requise. Voici la liste de ces groupes.

Les tableaux (Arrays)

Les helpers de ce groupe proposent des solutions pour manipuler les éléments d'un tableau. Bien souvent, vous vous trouvez dans cette situation où vous devez effectuer des opérations sur les éléments d'un tableau. Vous trouverez ici d'un seul coup d'œil s'il y a une solution adaptée.

Paths

A mon avis, il s'agit des helpers les plus utiles. Ils retournent le chemin absolu des différents répertoires comme app, config et tous les autres. Je parie que vous utilisez déjà la plupart d'entre eux dans votre application Laravel.

Les chaînes de caractères (Strings)

La manipulation de chaînes de caractères est une chose incontournable dans le développement quotidien de votre application. Pourtant, il existe tout un tas de fonctions déjà disponibles par PHP lui-même, mais quelques unes d'entre elles les plus remarquables sont aussi présentes dans cette section.

URLs

Vous en trouverez assez peu ici, mais elles sont employées à travers l'application elle-même. On y recours pour générer des routes, des assets ou des actions de formulaires par URLs.

Divers (Miscellaneous)

Cette catégorie comprend tous les helpers qui fournissent diverses fontionnalités, allant du logging au ddebugging. Et davantage encore...

Pour un panorama complet des helpers Laravel, il n'y a pas meilleur endroit que la documentation officielle.

Créez votre premier Helper

A présent, vous venez d'acquérir ici premières notions sur les helpers de Laravel et leur emploi. Ici, j'irai plus loin pour vous apprendre comment développer votre propre helper, afin qu'il soit disponible n'importe où au sein de votre application Laravel.

Afin de conserver les choses simples et accessibles, ce sera un petit helper rudimentaire qui prendra l'id utilisateur pour renvoyer sous forme de réponse, son nom. Bien sûr, c'est pas très sexy mais je pense que c'est suffisant pour démonter le mécanisme, et vous pourrez à tout moment l'étendre pour remplir vos exigences les plus folles.

Je présume que vous avez déjà une table utilisateurs dans votre base de données, contenant au moins deux champs : userid et username.

La colonne vertébrale d'un helper Laravel

Avant d'aller plus loin et d'en créer la structure, jetons un bref coup d'œil aux fichiers que nous allons créer pour l'ensemble de cet article.

app/Helpers/Envato/User.php : il s'agit du fichier qui contiendra toute la logique de votre helper.
app/Providers/EnvatoServiceProvider.php : là, il est question d'un service provider personnalisé qui chargera votre fichier helper.
config/app.php : Nous déclarerons dans ce ficher notre service provider, et nous permettra aussi de définir un alias pour notre helper, afin de ne pas rédiger chaque fois la totalité du namespace de notre classe.
routes/web.php : Un petit fichier standard de Laravel pour définir les routes afin de tester notre helper.

Création des fichiers Helper

Même s'il est possible de créer les fichiers helper n'importe où dans votre application, la façon la plus intuitive et standardisée rappelle que tout devrait se trouver dans le répertoire app.

Donc, allons-y et créons le répertoire Helpers/Envato dans app. Créons aussi un fichier User.php avec le contenu suivant. Bien sûr, il est possible de le placer directement dans les répertoires app ou app/Helpers, mais en y ajoutant ce niveau d'exigence supplémentaire, nous nous obligeons à organiser nos helpers selon de bonnes pratiques, surtout s'ils seront nombreux.

<?php
//app/Helpers/Envato/User.php
namespace App\Helpers\Envato;

use Illuminate\Support\Facades\DB;

class User {
    /**
     * @param int $user_id User-id
     * 
     * @return string
     */
    public static function get_username($user_id) {
        $user = DB::table('users')->where('userid', $user_id)->first();
        
        return (isset($user->username) ? $user->username : '');
    }
}

Le fichier commence avec la déclaration du namespace standard.

1	namespace App\Helpers\Envato;

Le but de notre helper spécifique est de retrouver un nom d'utilisateur basé sur son userid. Aussi, nous allons requérir la base de données et nous oblige à inclure une façade dédiée.

1	use Illuminate\Support\Facades\DB;

Pour ceux qui n'ont pas de connaissances particulières sur les Façades de Laravel, il s'agit juste d'une manière commode d'accéder aux objets à travers des service containers. Sinon, il est possible aussi d'employer l'injection de dépendance.

Continuons et passons en revue la construction de notre helper. Comme vous pouvez le constater, il y a une méthode statique qui organise la logique de la restitution du nom d'utilisateur basée sur le userid.

1	$user = DB::table('users')->where('userid', $user_id)->first();

L'objet $user contient l'enregistrement de la base de données selon le userid correspondant. Ainsi, la méthode renvoie le nom d'utilisateur comme une réponse à cette requête.

1	return (isset($user->username) ? $user->username : '');

C'est tout ce que peut faire ce helper à ce stade.

Puisque nous venons de créer notre fichier helper, posons-nous la question sur la façon de le mettre en œuvre ? Deux solutions immédiates me viennent à l'esprit :

Vous pouvez introduire le nom de fichier du helper dans le composer.json, et il sera chargé automatiquement. Dès lors, vous pourrez déclarer la méthode statique de votre classe dans la foulée.
Ou alors créez un service provider de Laravel qui vous permettra de déclarer votre fichier helper de façon à ce que le framework charge ce dernier avec l'ensemble de ses dépendances. Déclarez-le dans la configuration de Laravel et nommez un alias pour facilement l'appeler partout.

Evidemment, la première solution est plus rapide et facile à implanter, et vous seriez tenté de faire de la sorte, mais je vous suggère tout de même la dernière puisqu'elle est adaptée au framework et pourra être maintenue.

Basculez sur votre terminal et lancez la commande suivante à la racine de votre application pour créer un nouveau service provider.

1	$php artisan make:provider EnvatoServiceProvider
2	Provider created successfully.

Vous devriez apercevoir le message qui confirme qu'il a été créé avec succès dans le répertoire app/Providers.

Ouvrez ce fichier et deux méthodes s'y trouvent. La plus importante, concernant notre affaire ici, est la méthode register. Oui, elle est actuellement vide, et nous allons la définir pour la rendre efficace.

1	public function register()
2	{
3	require_once app_path() . '/Helpers/Envato/User.php';
4	}

La méthode register est conçue pour déclarer vos dépendances et nous venons justement de le faire. Nous y avons ajouté notre fichier helper.

Voici à quoi devrait ressembler le fichier app/Providers/EnvatoServiceProvider.php.

<?php
// app/Providers/EnvatoServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;

class EnvatoServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap the application services.
     *
     * @return void
     */
    public function boot()
    {
        //
    }

    /**
     * Register the application services.
     *
     * @return void
     */
    public function register()
    {
        require_once app_path() . '/Helpers/Envato/User.php';
    }
}

Jusqu'ici, tout va bien. Nous avons notre helper et son service provider disponibles sur la table.

Ensuite, nous avons besoin d'informer Laravel de l'existence de ce service provider afin qu'il soit charger lors de l'autoamorçage. Ouvrons config/app.php et ajoutons le terme suivant en fin du tableau providers.

1	App\Providers\EnvatoServiceProvider::class,

Afin d'appeler notre helper de façon aisée, nous pourrions aussi créer un alias. Allons-y en ajoutant cet autre terme en fin du tableau aliases, situé dans le même fichier.

1	'EnvatoUser' => App\Helpers\Envato\User::class,

Grâce à cette ligne, nous pourrons désormais exécuter notre helper avec la déclaration EnvatoUser. Drôlement pratique, non ? Pour référence, voici le fichier complet config/app.php.

<?php
// config/app.php
return [

    /*
    |--------------------------------------------------------------------------
    | Application Name
    |--------------------------------------------------------------------------
    |
    | This value is the name of your application. This value is used when the
    | framework needs to place the application's name in a notification or
    | any other location as required by the application or its packages.
    */

    'name' => 'Laravel',

    /*
    |--------------------------------------------------------------------------
    | Application Environment
    |--------------------------------------------------------------------------
    |
    | This value determines the "environment" your application is currently
    | running in. This may determine how you prefer to configure various
    | services your application utilizes. Set this in your ".env" file.
    |
    */

    'env' => env('APP_ENV', 'production'),

    /*
    |--------------------------------------------------------------------------
    | Application Debug Mode
    |--------------------------------------------------------------------------
    |
    | When your application is in debug mode, detailed error messages with
    | stack traces will be shown on every error that occurs within your
    | application. If disabled, a simple generic error page is shown.
    |
    */

    'debug' => env('APP_DEBUG', false),

    /*
    |--------------------------------------------------------------------------
    | Application URL
    |--------------------------------------------------------------------------
    |
    | This URL is used by the console to properly generate URLs when using
    | the Artisan command line tool. You should set this to the root of
    | your application so that it is used when running Artisan tasks.
    |
    */

    'url' => env('APP_URL', 'https://localhost'),

    /*
    |--------------------------------------------------------------------------
    | Application Timezone
    |--------------------------------------------------------------------------
    |
    | Here you may specify the default timezone for your application, which
    | will be used by the PHP date and date-time functions. We have gone
    | ahead and set this to a sensible default for you out of the box.
    |
    */

    'timezone' => 'UTC',

    /*
    |--------------------------------------------------------------------------
    | Application Locale Configuration
    |--------------------------------------------------------------------------
    |
    | The application locale determines the default locale that will be used
    | by the translation service provider. You are free to set this value
    | to any of the locales which will be supported by the application.
    |
    */

    'locale' => 'en',

    /*
    |--------------------------------------------------------------------------
    | Application Fallback Locale
    |--------------------------------------------------------------------------
    |
    | The fallback locale determines the locale to use when the current one
    | is not available. You may change the value to correspond to any of
    | the language folders that are provided through your application.
    |
    */

    'fallback_locale' => 'en',

    /*
    |--------------------------------------------------------------------------
    | Encryption Key
    |--------------------------------------------------------------------------
    |
    | This key is used by the Illuminate encrypter service and should be set
    | to a random, 32 character string, otherwise these encrypted strings
    | will not be safe. Please do this before deploying an application!
    |
    */

    'key' => env('APP_KEY'),

    'cipher' => 'AES-256-CBC',

    /*
    |--------------------------------------------------------------------------
    | Logging Configuration
    |--------------------------------------------------------------------------
    |
    | Here you may configure the log settings for your application. Out of
    | the box, Laravel uses the Monolog PHP logging library. This gives
    | you a variety of powerful log handlers / formatters to utilize.
    |
    | Available Settings: "single", "daily", "syslog", "errorlog"
    |
    */

    'log' => env('APP_LOG', 'single'),

    'log_level' => env('APP_LOG_LEVEL', 'debug'),

    /*
    |--------------------------------------------------------------------------
    | Autoloaded Service Providers
    |--------------------------------------------------------------------------
    |
    | The service providers listed here will be automatically loaded on the
    | request to your application. Feel free to add your own services to
    | this array to grant expanded functionality to your applications.
    |
    */

    'providers' => [

        /*
         * Laravel Framework Service Providers...
         */
        Illuminate\Auth\AuthServiceProvider::class,
        Illuminate\Broadcasting\BroadcastServiceProvider::class,
        Illuminate\Bus\BusServiceProvider::class,
        Illuminate\Cache\CacheServiceProvider::class,
        Illuminate\Foundation\Providers\ConsoleSupportServiceProvider::class,
        Illuminate\Cookie\CookieServiceProvider::class,
        Illuminate\Database\DatabaseServiceProvider::class,
        Illuminate\Encryption\EncryptionServiceProvider::class,
        Illuminate\Filesystem\FilesystemServiceProvider::class,
        Illuminate\Foundation\Providers\FoundationServiceProvider::class,
        Illuminate\Hashing\HashServiceProvider::class,
        Illuminate\Mail\MailServiceProvider::class,
        Illuminate\Notifications\NotificationServiceProvider::class,
        Illuminate\Pagination\PaginationServiceProvider::class,
        Illuminate\Pipeline\PipelineServiceProvider::class,
        Illuminate\Queue\QueueServiceProvider::class,
        Illuminate\Redis\RedisServiceProvider::class,
        Illuminate\Auth\Passwords\PasswordResetServiceProvider::class,
        Illuminate\Session\SessionServiceProvider::class,
        Illuminate\Translation\TranslationServiceProvider::class,
        Illuminate\Validation\ValidationServiceProvider::class,
        Illuminate\View\ViewServiceProvider::class,

        /*
         * Package Service Providers...
         */
        Laravel\Tinker\TinkerServiceProvider::class,

        /*
         * Application Service Providers...
         */
        App\Providers\AppServiceProvider::class,
        App\Providers\AuthServiceProvider::class,
        // App\Providers\BroadcastServiceProvider::class,
        App\Providers\EventServiceProvider::class,
        App\Providers\RouteServiceProvider::class,
        App\Providers\EnvatoServiceProvider::class,
    ],

    /*
    |--------------------------------------------------------------------------
    | Class Aliases
    |--------------------------------------------------------------------------
    |
    | This array of class aliases will be registered when this application
    | is started. However, feel free to register as many as you wish as
    | the aliases are "lazy" loaded so they don't hinder performance.
    |
    */

    'aliases' => [

        'App' => Illuminate\Support\Facades\App::class,
        'Artisan' => Illuminate\Support\Facades\Artisan::class,
        'Auth' => Illuminate\Support\Facades\Auth::class,
        'Blade' => Illuminate\Support\Facades\Blade::class,
        'Broadcast' => Illuminate\Support\Facades\Broadcast::class,
        'Bus' => Illuminate\Support\Facades\Bus::class,
        'Cache' => Illuminate\Support\Facades\Cache::class,
        'Config' => Illuminate\Support\Facades\Config::class,
        'Cookie' => Illuminate\Support\Facades\Cookie::class,
        'Crypt' => Illuminate\Support\Facades\Crypt::class,
        'DB' => Illuminate\Support\Facades\DB::class,
        'Eloquent' => Illuminate\Database\Eloquent\Model::class,
        'Event' => Illuminate\Support\Facades\Event::class,
        'File' => Illuminate\Support\Facades\File::class,
        'Gate' => Illuminate\Support\Facades\Gate::class,
        'Hash' => Illuminate\Support\Facades\Hash::class,
        'Lang' => Illuminate\Support\Facades\Lang::class,
        'Log' => Illuminate\Support\Facades\Log::class,
        'Mail' => Illuminate\Support\Facades\Mail::class,
        'Notification' => Illuminate\Support\Facades\Notification::class,
        'Password' => Illuminate\Support\Facades\Password::class,
        'Queue' => Illuminate\Support\Facades\Queue::class,
        'Redirect' => Illuminate\Support\Facades\Redirect::class,
        'Redis' => Illuminate\Support\Facades\Redis::class,
        'Request' => Illuminate\Support\Facades\Request::class,
        'Response' => Illuminate\Support\Facades\Response::class,
        'Route' => Illuminate\Support\Facades\Route::class,
        'Schema' => Illuminate\Support\Facades\Schema::class,
        'Session' => Illuminate\Support\Facades\Session::class,
        'Storage' => Illuminate\Support\Facades\Storage::class,
        'URL' => Illuminate\Support\Facades\URL::class,
        'Validator' => Illuminate\Support\Facades\Validator::class,
        'View' => Illuminate\Support\Facades\View::class,
        'EnvatoUser' => App\Helpers\Envato\User::class,
    ],

];

On n'est plus très loin ! Nous avons fait la partie la plus dure du job, nous pouvons maintenant récolter les lauriers de notre helper.

Votre premier Helper en action

Encore une fois, dans un souci de simplicité et d'efficacité, nous allons définir une route Laravel rudimentaire et appeler notre helper d'ici !

Créons un fichier routes/web.php avec le contenu suivant.

<?php
// routes/web.php
/*
|--------------------------------------------------------------------------
| Web Routes
|--------------------------------------------------------------------------
|
| Here is where you can register web routes for your application. These
| routes are loaded by the RouteServiceProvider within a group which
| contains the "web" middleware group. Now create something great!
|
*/

Route::get('/envato-user-helper-demo', function () {
    return EnvatoUser::get_username(1);
});

Avez-vous vraiment besoin d'explication ? Nous appelons notre helper avec le raccourci EnvatoUser::get_username, qui devrait nous renvoyer le nom d'utilisateur.

Evidemment, vous pouvez requérir n'import où notre helper dans l'application, que ce soit un contrôleur ou une vue.

Par conséquent, c'en est fini pour aujourd'hui.

Conclusion

Les Helpers sont de puissantes caractéristiques de Laravel, et je suis certain qu'en tant que développeur, vous serez séduit d'en étendre leurs possibilités. Et c'était le sujet du jour, en commançant notre voyage depuis les Helpers de base de Laravel et leur structure de fichiers, jusqu'à la création d'un helper complet.

Je présume que vous avez apprécié cet article et qu'il vous permettra de créer vos helpers dans le développement quotidien de votre application Laravel.

N'hésitez pas à laisser un commentaire ou des questions dans le formulaire ci-dessous. Je consulte également tout commentaire sur mon compte Twitter et j'y répond dès que possible !