Laravel 8.x Sail 文件

• 介紹
• 安裝 & 設定
  • 安裝 Sail 到當前應用中
  • 配置 Bash 別名
• 啟動 & 停止 Sail
• 執行命令
  • 執行 PHP 命令
  • 執行 Composer 命令
  • 執行 Artisan 命令
  • 執行 Node / NPM 命令
• 與資料庫互動
  • MySQL
  • Redis
• 執行測試
  • Laravel Dusk
• 預覽電子郵件
• 容器 CLI
• PHP 版本
• 共享您的網站
• 定製化

介紹

Laravel Sail 是一個輕量級的命令列介面, 用於與 Laravel 的預設 Docker 開發環境進行互動. Sail 為使用 PHP, MySQL 和 Redis 構建 Laravel 應用程式提供了一個很好的起點, 而無需事先具有 Docker 經驗.

Sail 的核心是 docker-compose.yml 檔案和儲存在專案根目錄的 sail 指令碼. sail 指令碼為 CLI 提供了便捷的方法, 可用於與 docker-compose.yml 檔案定義的 Docker 容器進行互動.

Laravel Sail 支援 macOS、Linux 和 Windows (透過 WSL2)。

安裝 & 設定

Laravel Sail 會隨著所有全新的 Laravel 應用程式一起自動安裝, 因此你可以立即的開始使用它. 要了解如何建立一個新的 Laravel 應用程式, 請查閱適合您目前作業系統的 安裝文件.

補充: 此處是指一開始使用 Laravel 8.x 建立應用, 若您還在使用先前的版本, 或是由先前的版本升級至 8.x, 請參照下述步奏安裝 Sail 到您當前的應用.

安裝 Sail 到當前應用中

假如您對使用 Sail 在您現有的 Laravel 應用感到興趣, 您可以透過 Composer 套件管理簡單的安裝 Sail. 當然, 這些步驟是假設您現有的本地開發環境允許你安裝 Copmoser 依賴:

composer require laravel/sail --dev

在 Sail 完成安裝後, 您可以執行 sail:install Artisan 命令. 這個命令將會發布 Sail 的 docker-compose.yml 檔案到您應用程式的根目錄:

php artisan sail:install

最後, 您可以開始 Sail. 要繼續學習如何使用 Sail, 請接著閱讀本文擋的其餘部份:

./vendor/bin/sail up

配置 Bash 別名

預設情況下, Sail 命令使用 vendor/bin/sail 指令碼呼叫, 該指令碼已包含在所有新建的 Laravel 應用程式中:

./vendor/bin/sail up

但與其重複的輸入 vendor/bin/sail 來執行 Sail 命令, 您可能會希望配置一個 Bash 別名方便你更容易的執行 Sail 命令:

alias sail='bash vendor/bin/sail'

補充: 透過 vim ~/.bashrc 加入別名, 可以讓別名常駐

一旦配置了 Bash 別名, 您可以透過簡單的鍵入 sail 來執行 Sail 命令. 本文接下來的示例都假定您已經配置了此別名:

sail up

啟動 & 停止 Sail

Laravel Sail 的 docker-compose.yml 檔案中定義了各種 Docker 容器, 這些容器可以一起工作幫助您建構 Laravel 應用程式. 每一個容器都定義在 docker-compose.yml 檔案中的 services 配置內. laravel.test 容器是為應用程式提供服務的主要應用程式容器.

在開始 Sail 之前, 您應該確認沒有其他的網站伺服器或資料庫正執行在您的本地計算機上. 要開始啟用 docker-compose.yml 檔案中定義的所有 Docker 容器, 請執行 up 命令:

sail up

要在後臺啟動所有 Docker 容器, 您可以在 “分離” 模式下啟動 Sail:

sail up -d

啟動應用程式的容器後, 您可以在 Web 瀏覽器中訪問專案: http://localhost.

要停止所有容器, 只需按 Control + C 即可停止容器的執行. 如果容器在後臺執行, 您可以使用 down 命令:

sail down

執行命令

使用 Laravel Sail 時, 應用程式在 Docker 容器中執行, 並且與本地計算機隔離. 不過 Sail 提供了一種針對應用程式執行各種命令的便捷方法, 例如任意的 PHP 命令, Artisan 命令, Composer 命令和 Node / NPM 命令.

當您閱讀 Laravel 文件時, 您可能經常看到在未使用 Sail 的狀況下執行 Composer, Artisan 或是 Node / NPM 命令. 以下示例假設您已經在本地計算機上安裝上述工具. 如果您打算使用 Sail 建構您的本地開發環境 , 您需要改用 Sail 執行這些命令:

# 在本地執行 Artisan 命令...
php artisan queue:work

# 在 Laravel Sail 中執行 Artisan 命令...
sail artisan queue:work

執行 PHP 命令

PHP 命令可以使用 php 命令執行. 當然, 這些命令將使用為您的應用程式配置的 PHP 版本執行. 要了解更多關於 PHP 版本可用的 Laravel Sail 資訊, 請查閱 PHP 版本文件:

sail php --version

sail php script.php

執行 Composer 命令

Composer 命令可以使用 composer 命令執行. Laravel Sail 的應用程式容器中已經安裝 Composer 2.x:

sail composer require laravel/sanctum

在已執行的應用中安裝 Composer 依賴

假如您與團隊一起開發應用程式, 您也許不是最初建立 Laravel 應用程式的人. 因此, 當您克隆應用程式的倉庫到本地計算機後, 將缺少安裝 Composer 依賴也包含了 Sail.

您可以導航到應用程式目錄下並執行以下命令來安裝應用所需的依賴, 這個命令使用一個包含 PHP 與 Composer 的小型 Docker 容器進行應用程式依賴的安裝:

docker run --rm
    -v $(pwd):/opt
    -w /opt
    laravelsail/php80-composer:latest
    composer install

執行 Artisan 命令

Artisan 命令可以使用 artisan 命令執行:

sail artisan queue:work

執行 Node / NPM 命令

Node 命令可以使用 node 命令執行, 而 NPM 命令可以使用 npm 命令執行:

sail node --version

sail npm run prod

與資料庫互動

MySQL

您可能已經注意到, 應用程式的 docker-compose.yml 檔案包含一個 MySQL 容器的條目. 該容器使用了 Docker volume, 以便即使在停止和重新啟動容器時依然可以持久儲存資料庫中儲存的資料. 另外, 當 MySQL 容器啟動時, 它將確儲存在名稱與您的 DB_DATABASE 環境變數的值匹配的資料庫.

啟動容器後, 您可以透過將應用程式 .env 檔案中的 DB_HOST 環境變數設定為 mysql 來連線到應用程式中的 MySQL 例項.

要從本地計算機連線到應用程式的 MySQL 資料庫, 您可以使用圖形資料庫管理應用程式, 例如 TablePlus. 預設情況下，可以從 localhost 的 3306 埠訪問 MySQL 資料庫.

Redis

應用程式的 docker-compose.yml 檔案也包含 Redis 容器. 該容器使用 Docker volume, 以便即使在停止和重新啟動容器後, Redis 資料中儲存的資料也可以持久儲存. 啟動容器後, 可以透過將應用程式 .env 檔案中的環境變數 REDIS_HOST 設定為 redis 來連線到應用程式中的 Redis 例項.

要從本地計算機連線到應用程式的 Redis 資料庫, 可以使用圖形資料庫管理應用程式, 例如 TablePlus. 預設情況下, 可以從 localhost 的 6379 埠訪問 Redis 資料庫.

執行測試

Laravel 提供了出色的開箱即用測試, 您可以使用 Sail 的 test 命令執行應用程式的 功能和單元測試. 任何 PHPUnit 可接受的 CLI 選項都可以透過 test 命令傳遞:

sail test

sail test --group orders

Sail test 命令相當於執行 Artisan test 命令:

sail artisan test

Laravel Dusk

Laravel Dusk 提供了非常優雅的, 易於使用的瀏覽器自動化測試 API. 有了 Sail, 進行瀏覽器測試更加方便了, 甚至不用在你的本地電腦上安裝 Selenium 或者任何其他工具. 要開啟這項功能, 請在 docker-compose.yml 檔案中取消 Selenium 服務註釋:

selenium:
    image: 'selenium/standalone-chrome'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

下一步, 請確認 docker-compose.yml 檔案中的 laravel.test 服務配置 depends_on 是否包含了 selenium 條目:

depends_on:
    - mysql
    - redis
    - selenium

最後, 您可以透過啟動 Sail 並執行 dusk 命令來進行 Dusk 測試:

sail dusk

預覽電子郵件

Sail 預設的 docker-compose.yml 檔案中包含了一個服務條目 MailHog. MailHog 會在你本地開發的過程中攔截應用程式傳送的電子郵件, 並提供一個便捷的 Web 介面, 方便您透過瀏覽器預覽電子郵件. 使用 Sail 時, MailHog 預設的主機名稱是 mailhog 並使用 1025 埠:

MAIL_HOST=mailhog
MAIL_PORT=1025

當 Sail 執行時, 您可以透過 http://localhost:8025 訪問 MailHog 的 Web 介面.

容器 CLI

有時候, 你可能想要在應用容器中開啟一個 Bash 會話。 這時可以執行 shell 命令，然後你就可以訪問容器中的檔案和已安裝的服務了, 同時還可以執行其他任意指令:

sail shell

想開啟一個新的 Laravel Tinker 會話, 你可以執行 tinker 命令:

sail tinker

PHP 版本

Sail 目前支援透過 PHP 8.0 或 PHP 7.4 為您的應用程式提供服務. 想更改應用程式使用的 PHP 版本, 請在 docker-compose.yml 檔案定義的容器 laravel.test 中調整 build 定義:

# PHP 8.0
context: ./vendor/laravel/sail/runtimes/8.0

# PHP 7.4
context: ./vendor/laravel/sail/runtimes/7.4

此外, 你如果想更新你的映象名稱來反映當前使用的 PHP 版本, 您可以在 docker-compose.yml 檔案中調整 image 欄位:

image: sail-8.0/app

在修改過 docker-compose.yml 檔案之後, 您應該要重建容器映象然後重啟 Sail:

sail build --no-cache

sail up

共享您的網站

有時後您可能需要公開您的網站分享給同事或是測試應用與網路掛鉤的整合. 想共享您的網站時, 可以使用 share 命令. 當您執行此命令後, 將會獲取一個隨機的網址, 例如 laravel-sail.site 用來訪問您的應用程式:

sail share

假如您想自定子域名, 您可以在執行 share 命令時加上 subdomain 引數:

sail share --subdomain=my-sail-site

share 命令由 Expose 提供， 一個開源的網路隧道服務 BeyondCode.

定製化

因為 Sail 就是 Docker, 所以你可以自由的定製任何內容, 使用 sail:publish 命令可以釋出 Sail 自己的 Dockerfile 方便您定製:

php artisan sail:publish

執行這個命令後, 在你的專案根目錄下會生成一個 docker 目錄, 裡面包含有關你應用的 Dockerfile 和其他配置檔案. 當您自行定製 Sail 配置之後, 您必須使用 build 命令來重新構建容器:

sail build --no-cache

本作品採用《CC 協議》，轉載必須註明作者和本文連結