教學 - Laravel Console Starter - Knowledge of Laravel

前言

本教學將透過 revolution/laravel-console-starter 建置具備自訂 artisan 指令的 Laravel 應用程式。使用此 starter kit 的好處：

快速上手 — 無需複雜設定即可立即開始 console 應用開發
Laravel 生態系 — 可運用任務排程、資料庫、通知等 Laravel 豐富功能
Artisan 指令 — 透過 Laravel 強大的 Artisan 系統輕鬆建立與管理自訂指令
易於測試 — 可用 Laravel 的測試框架撰寫指令測試

前置條件

請先安裝以下軟體。

PHP ^8.3
Composer（https://getcomposer.org/）
Laravel Installer（composer global require laravel/installer）

專案設定

建立新專案

在終端機執行以下指令。

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

會建立 my-app 目錄，並設定 console 應用的基本結構。安裝時會自動執行：

從 .env.example 產生 .env 檔
透過 php artisan key:generate 設定應用程式金鑰

主要目錄結構：

my-app/
├── app/Console/Commands/   # 放置自訂指令
├── .github/workflows/
│   └── cron.yml            # GitHub Actions 排程範例
├── config/                 # 應用程式設定
└── routes/console.php      # 指令註冊

確認環境設定

預設情況下，郵件寄送設定為輸出至 log（MAIL_MAILER=log）。若需要實際寄送郵件，請在 .env 檔中設定 Mailgun、Postmark、SES 等服務。

建立 Console 指令

產生指令

使用 make:command Artisan 指令建立新指令。

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

YourCommandName — 要建立的指令類別名稱（例：SendDailyReport）
your:command — 指令呼叫名稱（例：report:send-daily）

會產生 app/Console/Commands/YourCommandName.php。

實作指令

編輯所產生的檔案實作邏輯。以下是 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 定義指令的呼叫名稱，並在 handle() 方法中撰寫邏輯。

執行指令

php artisan hello:world

執行後會在 storage/logs/laravel.log 與 console 輸出訊息。

透過 GitHub Actions 進行任務排程

使用 GitHub Actions 可以無需伺服器 cron job 就定期執行指令。

確認 workflow 檔案

Starter kit 已預先包含 .github/workflows/cron.yml。

name: cron

on:
  schedule:
    - cron: '0 0 * * *'  # 每天 UTC 上午 0 點

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

替換指令

將 php artisan inspire 替換為自己的指令。

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

若要執行多個指令：

- name: Run Commands
  run: |
    php artisan first:command
    php artisan second:command

調整排程

變更 cron 表達式來設定執行頻率。

cron 表達式	執行時機
`0 0 * * *`	每天 UTC 上午 0 點
`0 /6 * *`	每 6 小時
`0 0 * * 1`	每週一上午 0 點

以 secret 管理機密資訊

API 金鑰或密碼等機密資訊請使用 GitHub 儲存庫 secret。在 GitHub 儲存庫的 Settings > Secrets and variables > Actions 新增 secret，並於 workflow 中引用。

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

通知功能

可透過 Email、Slack 等通知指令的執行結果或錯誤。

建立通知類別

php artisan make:notification TaskCompleted

會產生 app/Notifications/TaskCompleted.php。

設定通知頻道

視需要公開設定檔。

php artisan config:publish mail
php artisan config:publish services

從指令發送通知

<?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 = '處理資料，並於完成時發送通知';

    public function handle()
    {
        $this->info('資料處理中...');

        // 處理邏輯...

        Notification::route('mail', '[email protected]')
            ->notify(new TaskCompleted('資料處理已順利完成'));

        return Command::SUCCESS;
    }
}

詳情請參考 Laravel 通知文件。

實務應用範例

範例 1：網站存活監控與 Slack 警示

檢查網站是否上線，並於偵測到問題時向 Slack 發送警示的指令。

安裝 Slack 通知頻道

composer require laravel/slack-notification-channel

建立指令與通知

php artisan make:command MonitorWebsites --command=monitor:websites
php artisan make:notification WebsiteDown

設定 Slack

php artisan config:publish services

於 .env 新增 Slack webhook URL。

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

更新 config/services.php。

'slack' => [
    'webhook_url' => env('SLACK_WEBHOOK_URL'),
],

實作通知

編輯 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('網站當機警示！')
            ->attachment(function ($attachment) {
                $attachment->title($this->website)
                           ->content("錯誤：{$this->error}")
                           ->timestamp(now());
            });
    }
}

實作指令

編輯 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 = '網站存活確認並於當機時發送 Slack 警示';

    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}：上線 ✓");
                } else {
                    $error = "HTTP 狀態：" . $response->status();
                    $this->error("{$website}：當機（{$error}）");
                    Notification::route('slack', $webhookUrl)
                        ->notify(new WebsiteDown($website, $error));
                    $hasErrors = true;
                }
            } catch (\Exception $e) {
                $this->error("{$website}：錯誤（{$e->getMessage()}）");
                Log::error("{$website} 檢查失敗", ['error' => $e->getMessage()]);
                Notification::route('slack', $webhookUrl)
                    ->notify(new WebsiteDown($website, $e->getMessage()));
                $hasErrors = true;
            }
        }

        return $hasErrors ? Command::FAILURE : Command::SUCCESS;
    }
}

於 GitHub Actions 排程

更新 .github/workflows/cron.yml。

name: Website Monitoring

on:
  schedule:
    - cron: '*/15 * * * *'  # 每 15 分鐘執行

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

範例 2：加密貨幣投資組合更新與 Discord 通知

從 CoinGecko API 取得加密貨幣價格，並透過 Discord webhook 發送更新的指令。

安裝 Discord 通知頻道

composer require revolution/laravel-notification-discord-webhook

建立指令與通知

php artisan make:command UpdateCryptoPortfolio --command=crypto:portfolio
php artisan make:notification CryptoPortfolioUpdate

設定 Discord

於 .env 新增 Discord webhook URL。

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

更新 config/services.php。

'discord' => [
    'webhook' => env('DISCORD_WEBHOOK'),
],

實作並執行指令

詳細實作請參考 GitHub 儲存庫的教學。

php artisan crypto:portfolio

範例 3：網站內容抓取與郵件通知

從網站抓取內容並以 Email 傳送結果的指令。

建立指令與通知

php artisan make:command WebScraper --command=scrape:website
php artisan make:notification ScrapingCompleted

設定郵件

php artisan config:publish mail

於 .env 檔中加入郵件設定。

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
[email protected]
MAIL_FROM_NAME="${APP_NAME}"

實作並執行指令

protected $signature = 'scrape:website {--url=https://example.com} {[email protected]}';

public function handle(): int
{
    $url = $this->option('url');
    $email = $this->option('email');

    $response = Http::timeout(30)->get($url);

    // 處理內容並發送通知...
    Notification::route('mail', $email)
        ->notify(new ScrapingCompleted(true, $url, $title, $content));

    return Command::SUCCESS;
}

php artisan scrape:website [email protected]

下一步

你已經了解使用 revolution/laravel-console-starter 建置 Laravel console 應用程式的基礎。若要進一步深入學習：

探索 Laravel 文件 — 於 Laravel 官方文件了解可強化 console 應用的功能
實作測試 — 以 Laravel 測試框架建立指令的測試，確保可靠度
考慮套件開發 — 若在多個專案中會使用類似指令，可考慮發佈為可重複使用的 Laravel 套件
掌握最新資訊 — 追蹤 Laravel News 或官方部落格，隨時掌握最佳實踐

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

教學 - Laravel Console Starter

前言

前置條件

專案設定

建立 Console 指令

透過 GitHub Actions 進行任務排程

通知功能

實務應用範例

範例 1：網站存活監控與 Slack 警示

範例 2：加密貨幣投資組合更新與 Discord 通知

範例 3：網站內容抓取與郵件通知

下一步

​前言

​前置條件

​專案設定

​建立 Console 指令

​透過 GitHub Actions 進行任務排程

​通知功能

​實務應用範例

​範例 1：網站存活監控與 Slack 警示

​範例 2：加密貨幣投資組合更新與 Discord 通知

​範例 3：網站內容抓取與郵件通知

​下一步

前言

前置條件

專案設定

建立 Console 指令

透過 GitHub Actions 進行任務排程

通知功能

實務應用範例

範例 1：網站存活監控與 Slack 警示

範例 2：加密貨幣投資組合更新與 Discord 通知

範例 3：網站內容抓取與郵件通知

下一步