laravel-verification

Laravel 驗證循環

在發送 PR 前、重大變更後以及部署前執行。

使用時機

• 在為 Laravel 專案開啟 Pull Request 之前
• 在重大重構或相依套件升級之後
• 預備部署至 staging 或 production 環境前的驗證
• 執行完整的 lint -> 測試 -> 安全 -> 部署就緒流程

運作方式

• 依序執行各階段，從環境檢查到部署就緒，每一層都建立在上一層的基礎上。
• 環境與 Composer 檢查會阻擋後續所有步驟；若失敗則立即停止。
• 在執行完整測試與覆蓋率之前，應先確保 lint/靜態分析無誤。
• 安全與遷移檢查在測試之後進行，以便在處理資料或發佈步驟前先驗證行為。
• 建置/部署就緒以及佇列/排程檢查為最終關卡；任何失敗都會阻止發佈。

階段 1：環境檢查

php -v
composer --version
php artisan --version

• 確認 .env 檔案存在且包含必要的鍵值
• 確認 production 環境中 APP_DEBUG=false
• 確認 APP_ENV 符合目標部署環境（production、staging）

若在本機使用 Laravel Sail：

./vendor/bin/sail php -v
./vendor/bin/sail artisan --version

階段 1.5：Composer 與自動載入

composer validate
composer dump-autoload -o

階段 2：程式碼風格檢查與靜態分析

vendor/bin/pint --test
vendor/bin/phpstan analyse

若專案使用 Psalm 而非 PHPStan：

vendor/bin/psalm

階段 3：測試與覆蓋率

php artisan test

覆蓋率（CI）：

XDEBUG_MODE=coverage php artisan test --coverage

CI 範例（格式檢查 -> 靜態分析 -> 測試）：

vendor/bin/pint --test
vendor/bin/phpstan analyse
XDEBUG_MODE=coverage php artisan test --coverage

階段 4：安全性與相依套件檢查

composer audit

階段 5：資料庫與遷移

php artisan migrate --pretend
php artisan migrate:status

• 仔細審查可能造成破壞的遷移
• 確保遷移檔案名稱遵循 Y_m_d_His_* 格式（例如 2025_03_14_154210_create_orders_table.php）並清楚描述變更內容
• 確保可以回滾
• 驗證 down() 方法，避免在沒有明確備份的情況下造成不可逆的資料遺失

階段 6：建置與部署就緒

php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache

• 確保在 production 設定下快取預熱成功
• 確認佇列工作者與排程器已設定
• 確認目標環境中 storage/ 與 bootstrap/cache/ 目錄可寫入

階段 7：佇列與排程檢查

php artisan schedule:list
php artisan queue:failed

若使用 Horizon：

php artisan horizon:status

若 queue:monitor 可用，使用它來檢查積壓情況而不處理任務：

php artisan queue:monitor default --max=100

主動驗證（僅限 staging）：將一個無操作的任務派發到專用佇列，並執行單一工作者來處理它（確保已設定非 sync 的佇列連線）。

php artisan tinker --execute="dispatch((new App\\Jobs\\QueueHealthcheck())->onQueue('healthcheck'))"
php artisan queue:work --once --queue=healthcheck

驗證任務產生了預期的副作用（日誌記錄、健康檢查資料表行或指標）。

僅在非 production 環境中執行此操作，確保處理測試任務是安全的。

範例

最小流程：

php -v
composer --version
php artisan --version
composer validate
vendor/bin/pint --test
vendor/bin/phpstan analyse
php artisan test
composer audit
php artisan migrate --pretend
php artisan config:cache
php artisan queue:failed

CI 風格流程：

composer validate
composer dump-autoload -o
vendor/bin/pint --test
vendor/bin/phpstan analyse
XDEBUG_MODE=coverage php artisan test --coverage
composer audit
php artisan migrate --pretend
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan schedule:list