Gestion de paquets à Laravel

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

Dans cet article, nous allons explorer la fonctionnalité de gestion des paquets dans le framework Laravel. Au cours de cet article, nous allons passer en revue un exemple concret pour illustrer le but de cet article.

La gestion des paquets dans Laravel est une fonctionnalité importante qui vous permet de regrouper une fonctionnalité afin de pouvoir la distribuer facilement. De plus, vous pouvez toujours publier votre paquet dans des référentiels tels que Packagist et GitHub, ce qui permettra aux autres développeurs de tirer parti de votre paquet

Pour illustrer ce concept, nous allons créer un exemple de page dans Laravel qui télécharge une image sur le cloud Amazon S3. Plutôt que de suivre le flux habituel, nous le développerons comme un paquet groupé pouvant être distribué et maintenu facilement.

Avant de poursuivre, je suppose que vous connaissez déjà le framework Laravel car je n’entrerai pas dans les détails des concepts de base de Laravel.

En outre, vous devez disposer d'un compte AWS valide et des informations d'identification pour accéder à l'API Amazon afin de suivre l'exemple de cet article. Alors, assurez-vous de configurer cela en premier.

Avec tout sous la main, nous sommes prêts à plonger dans le développement actuel.

Configuration des fichiers de package

Examinons rapidement la liste des fichiers que nous allons implémenter tout au long de ce didacticiel.

composer.json: Nous devons ajouter le mappage de classes de notre paquet dans le fichier composer.json existant, à la racine du paquet.
config/app.php: Il s'agit du fichier existant que nous utiliserons pour ajouter une entrée de notre fournisseur de services personnalisé afin que nous puissions charger des vues et des itinéraires à l'aide de ce fichier.
composer.json: Il s'agit du fichier composer.json spécifique au paquet si vous souhaitez le distribuer avec d'autres
packages/envato/aws/src/Providers/AwsServiceProvider.php: fichier de fournisseur de services Laravel habituel qui sera utilisé pour charger d'autres composants du package.
packages/envato/aws/src/routes/web.php: Il charge les routes personnalisées de notre paquet.
packages/envato/aws/src/Controllers/AwsController.php: Il s'agit du fichier de contrôleur qui gère la logique d'application de notre package.
packages/envato/aws/src/views/upload.blade.php: fichier de vue qui gère la logique de rendu.

Ne vous inquiétez pas si cela n'a pas encore beaucoup de sens, car nous discuterons de tout en détail au fur et à mesure.

Configuration des prérequis

Comme nous l'avons vu précédemment, notre package implémente le cas d'utilisation du téléchargement de fichier vers le cloud Amazon S3. Dans cette section, nous allons passer en revue les conditions préalables à configurer pour pouvoir exécuter notre package avec succès.

En tant que développeur Laravel, vous devez être familiarisé avec Flysystem, qui fournit une couche d'abstraction agréable pour interagir avec le système de fichiers. Il fournit des pilotes faciles à utiliser pour vous permettre d'interagir facilement, quel que soit le type de système de fichiers utilisé: système de fichiers local ou système de cloud AWS S3.

Pour activer la prise en charge du système de fichiers cloud Amazon S3 avec Flysystem, vous devez installer le package d'adaptateur Composer correspondant.

Lancez la commande composer suivante à partir de la racine de votre projet pour installer le package flysystem-aws-s3-v3.

1	$composer require league/flysystem-aws-s3-v3

Une fois cette commande exécutée avec succès, vous pouvez désormais utiliser Laravel Flysystem pour interagir avec le système de fichiers cloud Amazon S3 de la même manière que vous l’auriez utilisée pour le système de fichiers local.

Maintenant, enregistrons rapidement le fichier config/filesystems.php pour voir les paramètres fournis pour le système de fichiers Amazon S3.

...
...
'disks' => [
    'local' => [
        'driver' => 'local',
        'root' => storage_path('app'),
    ],

    'public' => [
        'driver' => 'local',
        'root' => storage_path('app/public'),
        'url' => env('APP_URL').'/storage',
        'visibility' => 'public',
    ],

    's3' => [
        'driver' => 's3',
        'key' => env('AWS_KEY'),
        'secret' => env('AWS_SECRET'),
        'region' => env('AWS_REGION'),
        'bucket' => env('AWS_BUCKET'),
    ],
],
...
...

Comme vous pouvez le constater, la configuration est déjà en place pour Amazon S3. nous devons simplement définir les variables ENV appropriées dans le fichier .env.

Allez-y et ajoutez les variables suivantes dans votre fichier .env.

AWS_KEY={AWS_KEY_VALUE}
AWS_SECRET={AWS_SECRET_VALUE}
AWS_REGION={AWS_REGION_VALUE}
AWS_BUCKET={AWS_BUCKET_VALUE}
AWS_CDN_URL={AWS_CDN_URL_VALUE}

Bien sûr, vous devez remplacer les espaces réservés par leurs valeurs réelles. Vous êtes maintenant prêt à utiliser l'adaptateur Flysystem AWS S3 dans votre application Laravel.

Parcourir les fichiers de package

Pour créer votre propre package Laravel, la première chose à faire est de créer une structure de répertoires appropriée qui reflète les conventions du système Laravel. Je suppose que vous utilisez déjà une application de base Laravel; En fait, l'application de blog par défaut fera aussi bien.

Allez-y et créez le répertoire packages à la racine de votre application. Étant donné que vous allez distribuer votre paquet avec d’autres, la structure préférée de votre paquet doit être {vendor_name}/{package_name}.

Suivant cette convention, allons de l'avant et créons un répertoire envato/aws sous le répertoire packages. Comme vous l'avez peut-être deviné, envato est le nom du fournisseur et aws désigne le nom du paquet lui-même. Enfin, créons un répertoire packages/envato/aws/src qui contient les fichiers source de notre paquet.

Nous devons maintenant informer Laravel de notre nouveau paquet. Allez-y et ouvrez le fichier composer.json à la racine de votre application Laravel et ajoutez l'entrée "Envato\\Aws\\":"packages/envato/aws/src" dans la section de chargement automatique comme indiqué ci-dessous.

...
...
"autoload": {
    "classmap": [
        "database"
    ],
    "psr-4": {
        "App\\": "app/",
        "Envato\\Aws\\": "packages/envato/aws/src"
    }
},
...
...

Comme vous pouvez le constater, l’espace de nom Envato\Aws\est mappé sur le répertoire packages/envato/aws/src. Maintenant, il suffit d’exécuter la commande dump-autoload pour régénérer les mappages du compositeur.

1	$composer dump-autoload

Maintenant, vous pouvez utiliser Envato\Aws\ namespace dans votre application et il va chercher les fichiers à l'emplacement correct!

Fichier de composition du package

A présent, ajoutons un fichier composer.json spécifique au paquet afin de pouvoir le distribuer dans le référentiel packagist.

Accédez au répertoire packages/envato/aws et exécutez la commande suivante pour générer un fichier composer.json pour votre package.

1	$composer init

Les questions habituelles vous seront posées, alors parcourez-les et vous créerez un fichier composer.json.

À tout le moins, cela devrait ressembler à ceci.

{
    "name": "envato/aws",
    "description": "Example of File Upload to AWS S3 Cloud",
    "minimum-stability": "dev",
    "require": {}
}

Route

Dans notre package, nous allons créer une page simple qui affiche le statut du fichier téléchargé. Nous devons donc créer un itinéraire associé à cette page.

Créons un fichier de route dans packages/envato/aws/src/routes/web.php.

1	<?php
2	Route::get('aws/s3/upload', 'Envato\Aws\Controllers\AwsController@upload');

Cela nécessite-t-il une explication? La prochaine étape évidente consiste à créer le fichier de contrôleur associé.

Manette

Créons un fichier contrôleur dans packages/envato/aws/src/Controllers/AwsController.php avec le contenu suivant.

<?php
namespace Envato\Aws\Controllers;

use App\Http\Controllers\Controller;

class AwsController extends Controller
{
  public function upload(\Illuminate\Contracts\Filesystem\Factory $storage)
  {
    // load s3 storage
    $awsS3Storage = $storage->disk('s3');
    
    // load local storage
    $localStorage = $storage->disk('local');

    // default path of local storage "storage/app"
    $sourceFileContents = $localStorage->get('test.jpg');
    
    // destination filepath in S3 cloud
    $destFilePath = 'test_new.jpg';
    
    // init vars
    $imageUrl = '';
    $errorMsg = '';

    // upload file to AWS S3
    if ($awsS3Storage->put($destFilePath, $sourceFileContents, 'public'))
    {
      $imageUrl = env('AWS_CDN_URL') . env('AWS_BUCKET') . '/' . $destFilePath;
    }
    else
    {
      $errorMsg = 'Oops! Something went wrong :(';
    }

    // call view
    return view('aws::upload', ['imageUrl' => $imageUrl, 'errorMsg' => $errorMsg]);
  }
}

Passons en revue le fichier pour comprendre à quoi sert chaque morceau de code.

Nous démarrons les choses en définissant un espace de noms de notre contrôleur sur Envato\Aws\Controllers. Rappelez-vous que nous avons ajouté le mappage Envato\Aws à packages/envato/aws/src dans le fichier racine composer.json afin qu'il puisse trouver nos fichiers de package.

Nous avons ensuite défini la méthode upload qui nécessite la synchronisation des fichiers locaux vers le cloud Amazon S3. Il importe de noter ici le premier argument de la méthode de téléchargement qui demande la dépendance \Illuminate\Contracts\Filesystem\Factory. Pendant l'exécution, le contrat Laravel approprié sera injecté.

Nous pourrions maintenant utiliser l'instance de la fabrique de système de fichiers pour créer des instances de disque selon les besoins. L'instance de disque dans Laravel est le pilote qui vous permet d'accéder facilement aux systèmes de fichiers sous-jacents tels que le disque local, le cloud Amazon S3, etc.

// load s3 storage
$awsS3Storage = $storage->disk('s3');
    
// load local storage
$localStorage = $storage->disk('local');

Par souci de simplicité, nous transférons le fichier image statique déjà disponible sous le stockage local par défaut de Laravel. Le chemin d'accès est storage/app/test.jpg.

Dans un premier temps, saisissons le contenu du fichier source.

1	// default path of local storage "storage/app"
2	$sourceFileContents = $localStorage->get('test.jpg');

Avec tout configuré comme indiqué, vous devriez pouvoir synchroniser un fichier avec Amazon S3 à l'aide de la méthode put.

// upload file to AWS S3
if ($awsS3Storage->put($destFilePath, $sourceFileContents, 'public'))
{
  $imageUrl = env('AWS_CDN_URL') . env('AWS_BUCKET') . '/' . $destFilePath;
}
else
{
  $errorMsg = 'Oops! Something went wrong :(';
}

Assurez-vous que vous avez défini les variables d'environnement AWS correctement, juste au cas où quelque chose ne fonctionnerait pas comme prévu.

Et la dernière chose à faire est d'appeler un fichier de vue qui affiche l'image synchronisée et un message approprié.

1	// call view
2	return view('aws::upload', ['imageUrl' => $imageUrl, 'errorMsg' => $errorMsg]);

Bien sûr, nous n’avons pas encore créé de fichier de vue, et c’est exactement le sujet de la section suivante.

Vue

Créons un fichier de vue dans packages/envato/aws/src/views/upload.blade.php avec le contenu suivant.

<!DOCTYPE html>
<html lang="{{ config('app.locale') }}">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <title>Laravel</title>

        <!-- Fonts -->
        <link href="https://fonts.googleapis.com/css?family=Raleway:100,600" rel="stylesheet" type="text/css">

        <!-- Styles -->
        <style>
            html, body {
                background-color: #fff;
                color: #636b6f;
                font-family: 'Raleway', sans-serif;
                font-weight: 100;
                height: 100vh;
                margin: 0;
            }

            .full-height {
                height: 100vh;
            }

            .flex-center {
                align-items: center;
                display: flex;
                justify-content: center;
            }

            .position-ref {
                position: relative;
            }

            .top-right {
                position: absolute;
                right: 10px;
                top: 18px;
            }

            .content {
                text-align: center;
            }

            .title {
                font-size: 84px;
            }

            .links > a {
                color: #636b6f;
                padding: 0 25px;
                font-size: 12px;
                font-weight: 600;
                letter-spacing: .1rem;
                text-decoration: none;
                text-transform: uppercase;
            }

            .m-b-md {
                margin-bottom: 30px;
            }
        </style>
    </head>
    <body>
        <div class="flex-center position-ref full-height">
            @if (Route::has('login'))
                <div class="top-right links">
                    @if (Auth::check())
                        <a href="{{ url('/home') }}">Home</a>
                    @else
                        <a href="{{ url('/login') }}">Login</a>
                        <a href="{{ url('/register') }}">Register</a>
                    @endif
                </div>
            @endif

            <div class="content">
                <div class="title m-b-md">
                    File upload to S3 Cloud
                </div>

                <div>
                  @if ($imageUrl)
                      <img src="{{ $imageUrl }}" width="100"/>
                  @else
                      <span class="error">{{ $errorMsg }}</span>
                  @endif
                </div>
            </div>
        </div>
    </body>
</html>

C'est un fichier de vue assez standard qui affiche l'image téléchargée après le téléchargement réussi, ou sinon un message d'erreur approprié.

Fournisseur de services

Nous avons presque fini avec notre paquet car nous avons créé les fichiers nécessaires. L'étape suivante consiste à créer un fournisseur de services afin que nous puissions enregistrer les itinéraires et les vues de notre package.

Créons un fichier de fournisseur de services dans packages/envato/aws/src/Providers/AwsServiceProvider.php avec le contenu suivant.

<?php

namespace Envato\Aws\Providers;

use Illuminate\Support\ServiceProvider;

class AwsServiceProvider extends ServiceProvider
{
  /**
   * Bootstrap the application services.
   *
   * @return void
   */
  public function boot()
  {
      // load routes
      $this->loadRoutesFrom(__DIR__.'/../routes/web.php');

      // load view files
      $this->loadViewsFrom(__DIR__.'/../views', 'aws');
      
      // publish files
      $this->publishes([
      __DIR__.'/../views' => resource_path('views/vendor/aws'),
    ]);
  }

  /**
   * Register the application services.
   *
   * @return void
   */
  public function register()
  {
  }
}

De toute évidence, vous auriez pu créer le fichier de fournisseur de services en utilisant également la commande artisan. Mais il aurait fallu une étape supplémentaire pour déplacer le fichier d’app/Providers vers notre package.

Quoi qu'il en soit, examinons le fichier du fournisseur de services qui vient d'être créé.

Premièrement, nous chargeons les routes et les vues associées à notre package.

// load routes
$this->loadRoutesFrom(__DIR__.'/../routes/web.php');

// load view files
$this->loadViewsFrom(__DIR__.'/../views', 'aws');

Ensuite, nous fournissons le support de la publication des vues de nos packages afin que les développeurs qui souhaitent remplacer les vues puissent le faire. Lors de la prochaine utilisation de la commande php artisan vendor: publish, Laravel copie les vues depuis packages/envato/aws/src/views/ vers resources/views/vendor/aws.

Désormais, ils peuvent modifier les vues dans le répertoire resources/views/vendor/aws. Laravel le récupérera automatiquement au lieu des vues sous packages/envato/aws/src/views/. En fait, c'est le moyen approprié de modifier les vues de paquetages tiers, au lieu de modifier directement les vues de paquetage.

Voilà pour le prestataire de services. Comme vous vous en doutez, nous devons ajouter l'entrée du fournisseur de service dans config /app.php Ajoutez l'entrée suivante dans le tableau providers.

...
...
/*
 * Application Service Providers...
 */
App\Providers\AppServiceProvider::class,
App\Providers\AuthServiceProvider::class,
App\Providers\BroadcastServiceProvider::class,
App\Providers\EventServiceProvider::class,
App\Providers\RouteServiceProvider::class,
Envato\Aws\Providers\AwsServiceProvider::class, // Our package service provider
...
...

Et voilà: tout est en ordre maintenant, pour que nous puissions tester notre package.

Lancez l'URL http://your-laravel-application/aws/s3/upload dans votre navigateur. Si tout se passe bien, vous devriez voir l'image sur votre page chargée à partir du cloud Amazon S3. Faites-le moi savoir si vous rencontrez des problèmes, et je serais plus qu'heureux de répondre à ceux-ci.

Nous sommes donc sur la dernière note de cet article et j'espère que vous l'avez apprécié!

Conclusion

Aujourd’hui, nous avons abordé l’une des caractéristiques importantes du framework Laravel: la gestion des paquets. Lors de la configuration de notre package personnalisé Laravel, nous avons utilisé un exemple concret qui montre comment télécharger une image sur le cloud Amazon S3.

C'est une fonctionnalité vraiment intéressante si vous souhaitez regrouper et distribuer un ensemble de fonctionnalités. En fait, vous pourriez envisager cela comme une option pour aborder le développement de modules personnalisés à Laravel.

Pour ceux d'entre vous qui débutent avec Laravel ou qui souhaitent développer leurs connaissances, leur site ou leur application avec des extensions, nous pouvons étudier de nombreuses choses sur le marché Envato.

Comme toujours, vous pouvez laisser vos précieux commentaires dans le flux ci-dessous!