Tutoriel - Laravel Console Starter

Étapes pour construire une application console avec Laravel Console Starter. Apprenez la création de commandes, la planification GitHub Actions, l’envoi de notifications et des exemples pratiques.

​

Introduction

Dans ce tutoriel, vous allez construire une application Laravel avec des commandes artisan personnalisées en utilisant revolution/laravel-console-starter.

Avantages d’utiliser ce kit de démarrage :

• Mise en place rapide — Vous pouvez commencer immédiatement le développement d’applications console sans configuration complexe
• Écosystème Laravel — Vous pouvez utiliser les fonctionnalités riches de Laravel comme la planification de tâches, la base de données et les notifications
• Commandes Artisan — Vous pouvez facilement créer et gérer vos propres commandes grâce au puissant système Artisan de Laravel
• Facilité de test — Vous pouvez écrire des tests pour vos commandes avec le framework de test de Laravel

​

Prérequis

Installez les logiciels suivants.

• PHP ^8.3
• Composer (https://getcomposer.org/)
• Laravel Installer (composer global require laravel/installer)

​

Configuration du projet

1. Créer un nouveau projet

   Exécutez la commande suivante dans le terminal.

   laravel new my-app --using=revolution/laravel-console-starter --no-interaction
   

   Le répertoire my-app est créé et la structure de base de l’application console est mise en place.

   Lors de l’installation, les actions suivantes sont exécutées automatiquement :

   • Génération du fichier .env depuis .env.example
   • Configuration de la clé applicative avec php artisan key:generate

   Structure principale des répertoires :

   my-app/
   ├── app/Console/Commands/   # Emplacement des commandes personnalisées
   ├── .github/workflows/
   │   └── cron.yml            # Exemple de planification GitHub Actions
   ├── config/                 # Configuration de l'application
   └── routes/console.php      # Enregistrement des commandes
   
2. Vérifier la configuration de l'environnement

   Par défaut, l’envoi d’e-mails est configuré vers la sortie log (MAIL_MAILER=log).

   Si un envoi réel d’e-mails est nécessaire, configurez un service comme Mailgun, Postmark ou SES dans le fichier .env.

​

Création de commandes console

1. Générer une commande

   Créez une nouvelle commande avec la commande Artisan make:command.

   php artisan make:command YourCommandName --command=your:command
   

   • YourCommandName — Nom de la classe de la commande à créer (ex : SendDailyReport)
   • your:command — Nom d’invocation de la commande (ex : report:send-daily)

   app/Console/Commands/YourCommandName.php est généré.

2. Implémenter la commande

   Éditez le fichier généré pour implémenter la logique. Voici un exemple de commande Hello World.

   <?php
   
   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   use Illuminate\Support\Facades\Log;
   
   class HelloWorldCommand extends Command
   {
       protected $signature = 'hello:world';
       protected $description = 'Displays a hello world message in the log';
   
       public function handle(): int
       {
           Log::info('Hello, World from Artisan Command!');
           $this->info('Hello, World message has been logged.');
           return Command::SUCCESS;
       }
   }
   

   $signature définit le nom d’invocation de la commande, et la logique est écrite dans la méthode handle().

3. Exécuter la commande

   php artisan hello:world
   

   Après l’exécution, le message est écrit dans storage/logs/laravel.log et affiché dans la console.

​

Planification de tâches avec GitHub Actions

En utilisant GitHub Actions, vous pouvez exécuter des commandes de manière périodique sans cron sur le serveur.

1. Vérifier le fichier de workflow

   Le kit de démarrage inclut un fichier .github/workflows/cron.yml préconfiguré.

   name: cron
   
   on:
     schedule:
       - cron: '0 0 * * *'  # Tous les jours à 0h UTC
   
   jobs:
     cron:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v6
         - uses: shivammathur/setup-php@v2
           with:
             php-version: 8.5
             coverage: none
         - run: composer install --no-dev -q
         - run: cp .env.example .env
         - run: php artisan key:generate
         - run: php artisan inspire
   
2. Modifier la commande

   Remplacez php artisan inspire par votre propre commande.

   - name: Run Command
     run: php artisan your:command
   

   Pour exécuter plusieurs commandes :

   - name: Run Commands
     run: |
       php artisan first:command
       php artisan second:command
   
3. Ajuster la planification

   Modifiez l’expression cron pour définir la fréquence d’exécution.

   Expression cron	Moment d’exécution
   0 0 * * *	Tous les jours à 0h UTC
   0 */6 * * *	Toutes les 6 heures
   0 0 * * 1	Chaque lundi à 0h

4. Gérer les informations sensibles avec des secrets

   Utilisez les secrets du dépôt GitHub pour les informations sensibles comme les clés API et les mots de passe.

   Ajoutez un secret dans Settings > Secrets and variables > Actions du dépôt GitHub et référencez-le dans le workflow.

   - name: Run Command with Secrets
     run: php artisan your:command
     env:
       API_KEY: ${{ secrets.API_KEY }}
       DB_PASSWORD: ${{ secrets.DATABASE_PASSWORD }}
   

​

Fonctionnalités de notification

Vous pouvez notifier les résultats d’exécution ou les erreurs de commande par e-mail, Slack, etc.

1. Créer une classe de notification

   php artisan make:notification TaskCompleted
   

   app/Notifications/TaskCompleted.php est généré.

2. Configurer le canal de notification

   Publiez les fichiers de configuration si nécessaire.

   php artisan config:publish mail
   php artisan config:publish services
   
3. Envoyer une notification depuis une commande

   <?php
   
   namespace App\Console\Commands;
   
   use App\Notifications\TaskCompleted;
   use Illuminate\Console\Command;
   use Illuminate\Support\Facades\Notification;
   
   class ProcessDataCommand extends Command
   {
       protected $signature = 'data:process';
       protected $description = 'Traite les données et envoie une notification à la fin';
   
       public function handle()
       {
           $this->info('Traitement des données en cours...');
   
           // Logique de traitement...
   
           Notification::route('mail', '[e-mail]')
               ->notify(new TaskCompleted('Le traitement des données s\'est terminé avec succès'));
   
           return Command::SUCCESS;
       }
   }
   

Pour plus de détails, consultez la documentation Laravel sur les notifications.

​

Exemples d’applications concrètes

​

Exemple 1 : Surveillance de disponibilité de sites web et alertes Slack

Une commande qui vérifie si des sites web sont en ligne et envoie une alerte à Slack en cas de problème détecté.

1. Installer le canal de notification Slack

   composer require laravel/slack-notification-channel
   
2. Créer la commande et la notification

   php artisan make:command MonitorWebsites --command=monitor:websites
   php artisan make:notification WebsiteDown
   
3. Configurer Slack

   php artisan config:publish services
   

   Ajoutez l’URL du webhook Slack dans .env.

   SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
   

   Mettez à jour config/services.php.

   'slack' => [
       'webhook_url' => env('SLACK_WEBHOOK_URL'),
   ],
   
4. Implémenter la notification

   Éditez app/Notifications/WebsiteDown.php.

   <?php
   
   namespace App\Notifications;
   
   use Illuminate\Notifications\Messages\SlackMessage;
   use Illuminate\Notifications\Notification;
   
   class WebsiteDown extends Notification
   {
       public function __construct(
           protected string $website,
           protected string $error,
       ) {}
   
       public function via($notifiable): array
       {
           return ['slack'];
       }
   
       public function toSlack($notifiable): SlackMessage
       {
           return (new SlackMessage)
               ->error()
               ->content('Alerte site web indisponible !')
               ->attachment(function ($attachment) {
                   $attachment->title($this->website)
                              ->content("Erreur : {$this->error}")
                              ->timestamp(now());
               });
       }
   }
   
5. Implémenter la commande

   Éditez app/Console/Commands/MonitorWebsites.php.

   <?php
   
   namespace App\Console\Commands;
   
   use App\Notifications\WebsiteDown;
   use Illuminate\Console\Command;
   use Illuminate\Support\Facades\Http;
   use Illuminate\Support\Facades\Log;
   use Illuminate\Support\Facades\Notification;
   
   class MonitorWebsites extends Command
   {
       protected $signature = 'monitor:websites {--timeout=10}';
       protected $description = 'Vérifie la disponibilité des sites web et envoie une alerte Slack en cas d\'indisponibilité';
   
       protected array $websites = [
           'https://example.com',
           'https://yourwebsite.com',
       ];
   
       public function handle(): int
       {
           $timeout = (int) $this->option('timeout');
           $webhookUrl = config('services.slack.webhook_url');
           $hasErrors = false;
   
           foreach ($this->websites as $website) {
               try {
                   $response = Http::timeout($timeout)->get($website);
                   if ($response->successful()) {
                       $this->info("{$website} : en ligne ✓");
                   } else {
                       $error = "Statut HTTP : " . $response->status();
                       $this->error("{$website} : indisponible ({$error})");
                       Notification::route('slack', $webhookUrl)
                           ->notify(new WebsiteDown($website, $error));
                       $hasErrors = true;
                   }
               } catch (\Exception $e) {
                   $this->error("{$website} : erreur ({$e->getMessage()})");
                   Log::error("Échec de la vérification de {$website}", ['error' => $e->getMessage()]);
                   Notification::route('slack', $webhookUrl)
                       ->notify(new WebsiteDown($website, $e->getMessage()));
                   $hasErrors = true;
               }
           }
   
           return $hasErrors ? Command::FAILURE : Command::SUCCESS;
       }
   }
   
6. Configurer la planification via GitHub Actions

   Mettez à jour .github/workflows/cron.yml.

   name: Website Monitoring
   
   on:
     schedule:
       - cron: '*/15 * * * *'  # Exécuter toutes les 15 minutes
   
   jobs:
     monitor:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v6
         - uses: shivammathur/setup-php@v2
           with:
             php-version: 8.5
         - run: composer install --no-dev -q
         - run: cp .env.example .env
         - run: php artisan key:generate
         - name: Monitor Websites
           run: php artisan monitor:websites
           env:
             SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
   

​

Exemple 2 : Mise à jour du portefeuille crypto et notification Discord

Une commande qui récupère les prix des crypto-actifs depuis l’API CoinGecko et envoie les mises à jour via un webhook Discord.

1. Installer le canal de notification Discord

   composer require revolution/laravel-notification-discord-webhook
   
2. Créer la commande et la notification

   php artisan make:command UpdateCryptoPortfolio --command=crypto:portfolio
   php artisan make:notification CryptoPortfolioUpdate
   
3. Configurer Discord

   Ajoutez l’URL du webhook Discord dans .env.

   DISCORD_WEBHOOK=https://discord.com/api/webhooks/YOUR/WEBHOOK
   

   Mettez à jour config/services.php.

   'discord' => [
       'webhook' => env('DISCORD_WEBHOOK'),
   ],
   
4. Implémenter et exécuter la commande

   Pour l’implémentation détaillée, consultez le tutoriel dans le dépôt GitHub.

   php artisan crypto:portfolio
   

​

Exemple 3 : Scraping de contenu web et notification par e-mail

Une commande qui scrappe le contenu d’un site web et envoie le résultat par e-mail.

1. Créer la commande et la notification

   php artisan make:command WebScraper --command=scrape:website
   php artisan make:notification ScrapingCompleted
   
2. Configurer l'e-mail

   php artisan config:publish mail
   

   Ajoutez la configuration e-mail dans le fichier .env.

   MAIL_MAILER=smtp
   MAIL_HOST=smtp.mailtrap.io
   MAIL_PORT=2525
   MAIL_USERNAME=your_username
   MAIL_PASSWORD=your_password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS=[e-mail]
   MAIL_FROM_NAME="${APP_NAME}"
   
3. Implémenter et exécuter la commande

   protected $signature = 'scrape:website {--url=https://example.com} {--email=[e-mail]}';
   
   public function handle(): int
   {
       $url = $this->option('url');
       $email = $this->option('email');
   
       $response = Http::timeout(30)->get($url);
   
       // Traiter le contenu et envoyer la notification...
       Notification::route('mail', $email)
           ->notify(new ScrapingCompleted(true, $url, $title, $content));
   
       return Command::SUCCESS;
   }
   

   php artisan scrape:website --email=[e-mail]
   

​

Étapes suivantes

Vous avez maintenant appris les bases de la construction d’une application console Laravel avec revolution/laravel-console-starter.

Pour aller plus loin :

• Explorer la documentation Laravel — Consultez la documentation officielle Laravel pour découvrir des fonctionnalités qui enrichiront votre application console
• Implémenter des tests — Créez des tests pour vos commandes avec le framework de test de Laravel afin d’assurer leur fiabilité
• Envisager le développement de packages — Si vous créez des commandes similaires dans plusieurs projets, envisagez de les publier comme package Laravel réutilisable
• Se tenir à jour — Suivez Laravel News et le blog officiel pour rester au fait des bonnes pratiques