> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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/](https://getcomposer.org/))
* Laravel Installer (`composer global require laravel/installer`)

## Configuration du projet

<Steps>
  <Step title="Créer un nouveau projet">
    Exécutez la commande suivante dans le terminal.

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="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`.
  </Step>
</Steps>

## Création de commandes console

<Steps>
  <Step title="Générer une commande">
    Créez une nouvelle commande avec la commande Artisan `make:command`.

    ```bash theme={null}
    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é.
  </Step>

  <Step title="Implémenter la commande">
    Éditez le fichier généré pour implémenter la logique. Voici un exemple de commande Hello World.

    ```php theme={null}
    <?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()`.
  </Step>

  <Step title="Exécuter la commande">
    ```bash theme={null}
    php artisan hello:world
    ```

    Après l'exécution, le message est écrit dans `storage/logs/laravel.log` et affiché dans la console.
  </Step>
</Steps>

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

<Steps>
  <Step title="Vérifier le fichier de workflow">
    Le kit de démarrage inclut un fichier `.github/workflows/cron.yml` préconfiguré.

    ```yaml theme={null}
    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
    ```
  </Step>

  <Step title="Modifier la commande">
    Remplacez `php artisan inspire` par votre propre commande.

    ```yaml theme={null}
    - name: Run Command
      run: php artisan your:command
    ```

    Pour exécuter plusieurs commandes :

    ```yaml theme={null}
    - name: Run Commands
      run: |
        php artisan first:command
        php artisan second:command
    ```
  </Step>

  <Step title="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       |
  </Step>

  <Step title="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.

    ```yaml theme={null}
    - name: Run Command with Secrets
      run: php artisan your:command
      env:
        API_KEY: ${{ secrets.API_KEY }}
        DB_PASSWORD: ${{ secrets.DATABASE_PASSWORD }}
    ```
  </Step>
</Steps>

## Fonctionnalités de notification

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

<Steps>
  <Step title="Créer une classe de notification">
    ```bash theme={null}
    php artisan make:notification TaskCompleted
    ```

    `app/Notifications/TaskCompleted.php` est généré.
  </Step>

  <Step title="Configurer le canal de notification">
    Publiez les fichiers de configuration si nécessaire.

    ```bash theme={null}
    php artisan config:publish mail
    php artisan config:publish services
    ```
  </Step>

  <Step title="Envoyer une notification depuis une commande">
    ```php theme={null}
    <?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', 'admin@example.com')
                ->notify(new TaskCompleted('Le traitement des données s\'est terminé avec succès'));

            return Command::SUCCESS;
        }
    }
    ```
  </Step>
</Steps>

<Info>
  Pour plus de détails, consultez la [documentation Laravel sur les notifications](https://laravel.com/docs/notifications).
</Info>

## 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é.

<Steps>
  <Step title="Installer le canal de notification Slack">
    ```bash theme={null}
    composer require laravel/slack-notification-channel
    ```
  </Step>

  <Step title="Créer la commande et la notification">
    ```bash theme={null}
    php artisan make:command MonitorWebsites --command=monitor:websites
    php artisan make:notification WebsiteDown
    ```
  </Step>

  <Step title="Configurer Slack">
    ```bash theme={null}
    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`.

    ```php theme={null}
    'slack' => [
        'webhook_url' => env('SLACK_WEBHOOK_URL'),
    ],
    ```
  </Step>

  <Step title="Implémenter la notification">
    Éditez `app/Notifications/WebsiteDown.php`.

    ```php theme={null}
    <?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());
                });
        }
    }
    ```
  </Step>

  <Step title="Implémenter la commande">
    Éditez `app/Console/Commands/MonitorWebsites.php`.

    ```php theme={null}
    <?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;
        }
    }
    ```
  </Step>

  <Step title="Configurer la planification via GitHub Actions">
    Mettez à jour `.github/workflows/cron.yml`.

    ```yaml theme={null}
    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 }}
    ```
  </Step>
</Steps>

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

<Steps>
  <Step title="Installer le canal de notification Discord">
    ```bash theme={null}
    composer require revolution/laravel-notification-discord-webhook
    ```
  </Step>

  <Step title="Créer la commande et la notification">
    ```bash theme={null}
    php artisan make:command UpdateCryptoPortfolio --command=crypto:portfolio
    php artisan make:notification CryptoPortfolioUpdate
    ```
  </Step>

  <Step title="Configurer Discord">
    Ajoutez l'URL du webhook Discord dans `.env`.

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

    Mettez à jour `config/services.php`.

    ```php theme={null}
    'discord' => [
        'webhook' => env('DISCORD_WEBHOOK'),
    ],
    ```
  </Step>

  <Step title="Implémenter et exécuter la commande">
    Pour l'implémentation détaillée, consultez [le tutoriel dans le dépôt GitHub](https://github.com/invokable/laravel-console-starter/blob/main/docs/tutorial_ja.md).

    ```bash theme={null}
    php artisan crypto:portfolio
    ```
  </Step>
</Steps>

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

<Steps>
  <Step title="Créer la commande et la notification">
    ```bash theme={null}
    php artisan make:command WebScraper --command=scrape:website
    php artisan make:notification ScrapingCompleted
    ```
  </Step>

  <Step title="Configurer l'e-mail">
    ```bash theme={null}
    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=your-app@example.com
    MAIL_FROM_NAME="${APP_NAME}"
    ```
  </Step>

  <Step title="Implémenter et exécuter la commande">
    ```php theme={null}
    protected $signature = 'scrape:website {--url=https://example.com} {--email=admin@example.com}';

    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;
    }
    ```

    ```bash theme={null}
    php artisan scrape:website --email=admin@example.com
    ```
  </Step>
</Steps>

## É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](https://laravel.com/docs) 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](https://laravel-news.com/) et le blog officiel pour rester au fait des bonnes pratiques


## Related topics

- [Laravel Console Starter](/fr/packages/laravel-console-starter/index.md)
- [Tests de console](/fr/console-tests.md)
- [Tutoriel bot - Laravel Bluesky](/fr/packages/laravel-bluesky/bot-tutorial.md)
- [Créer un starter kit Laravel](/fr/advanced/starter-kit-creation.md)
- [Structure des répertoires](/fr/directory-structure.md)