Valet

簡介 (Introduction)

[!NOTE] 想要在 macOS 或 Windows 上尋找更簡單的 Laravel 應用程式開發方式嗎？請查看 Laravel Herd。Herd 包含了開始 Laravel 開發所需的一切，包括 Valet、PHP 和 Composer。

Laravel Valet 是一個 macOS 極簡主義者的開發環境。Laravel Valet 設定你的 Mac 在開機時自動在背景執行 Nginx。然後，使用 DnsMasq，Valet 將所有 *.test 網域的請求代理到安裝在你本機上的網站。

換句話說，Valet 是一個極快的 Laravel 開發環境，僅使用約 7 MB 的 RAM。Valet 並不是 Sail 或 Homestead 的完全替代品，但如果你想要靈活的基礎、偏好極致的速度，或者在 RAM 有限的機器上工作，它提供了一個很好的選擇。

預設情況下，Valet 支援包括但不限於：

然而，你可以使用自己的 自訂驅動 來擴充 Valet。

安裝 (Installation)

[!WARNING] Valet 需要 macOS 和 Homebrew。在安裝之前，你應該確保沒有其他程式（如 Apache 或 Nginx）佔用你本機的 80 連接埠。

要開始使用，首先需要使用 update 指令確保 Homebrew 是最新的：

brew update

接下來，你應該使用 Homebrew 安裝 PHP：

brew install php

安裝 PHP 後，你就可以安裝 Composer 套件管理器。此外，你應該確保 $HOME/.composer/vendor/bin 目錄在你的系統 "PATH" 中。安裝 Composer 後，你可以將 Laravel Valet 安裝為全域 Composer 套件：

composer global require laravel/valet

最後，你可以執行 Valet 的 install 指令。這將設定並安裝 Valet 和 DnsMasq。此外，Valet 依賴的守護行程將被設定為在系統啟動時啟動：

valet install

安裝 Valet 後，嘗試在終端機使用 ping foobar.test 等指令 ping 任何 *.test 網域。如果 Valet 安裝正確，你應該會看到此網域在 127.0.0.1 上回應。

Valet 會在每次機器開機時自動啟動其所需的服務。

PHP 版本 (PHP Versions)

[!NOTE] 這裡不修改全域 PHP 版本，你可以透過 isolate 指令 指示 Valet 使用各網站 PHP 版本。

Valet 允許你使用 valet use php@version 指令切換 PHP 版本。如果尚未安裝，Valet 將透過 Homebrew 安裝指定的 PHP 版本：

valet use php@8.2

valet use php

你也可以在專案的根目錄中建立一個 .valetrc 檔案。.valetrc 檔案應包含該網站應使用的 PHP 版本：

php=php@8.2

一旦建立了此檔案，你只需執行 valet use 指令，該指令將透過讀取檔案來確定網站的首選 PHP 版本。

[!WARNING] Valet 一次只提供一個 PHP 版本服務，即使你安裝了多個 PHP 版本。

資料庫 (Database)

如果你的應用程式需要資料庫，請查看 DBngin，它提供了一個免費、多合一的資料庫管理工具，包括 MySQL、PostgreSQL 和 Redis。安裝 DBngin 後，你可以使用 root 使用者名稱和空字串密碼連接到 127.0.0.1 的資料庫。

重設你的安裝 (Resetting Your Installation)

如果你在讓 Valet 安裝正常運作時遇到問題，執行 composer global require laravel/valet 指令後接著執行 valet install 將重設你的安裝，並可能解決各種問題。在極少數情況下，可能需要執行 valet uninstall --force 後接著執行 valet install 來「硬重設」Valet。

升級 Valet (Upgrading Valet)

你可以在終端機執行 composer global require laravel/valet 指令來更新你的 Valet 安裝。升級後，最好執行 valet install 指令，以便 Valet 可以在必要時對你的設定檔進行額外的升級。

升級到 Valet 4 (Upgrading to Valet 4)

如果你要從 Valet 3 升級到 Valet 4，請採取以下步驟以正確升級你的 Valet 安裝：

提供網站服務 (Serving Sites)

安裝 Valet 後，你就可以開始提供 Laravel 應用程式服務了。Valet 提供了兩個指令來幫助你提供應用程式服務：park 和 link。

「Park」指令 (The park Command) (The "Park" Command)

park 指令會註冊一個包含你應用程式的目錄。一旦目錄被 Valet「停放 (parked)」，該目錄中的所有目錄都可以在你的網頁瀏覽器中以 http://<directory-name>.test 存取：

cd ~/Sites

valet park

就這樣。現在，你在「停放」目錄中建立的任何應用程式都將自動使用 http://<directory-name>.test 慣例提供服務。因此，如果你的停放目錄包含一個名為 "laravel" 的目錄，該應用程式將可以在 http://laravel.test 存取。此外，Valet 自動允許你使用萬用字元子網域 (http://foo.laravel.test) 存取網站。

「Link」指令 (The link Command) (The "Link" Command)

link 指令也可以用來提供 Laravel 應用程式服務。如果你想提供目錄中的單個網站而不是整個目錄，這個指令很有用：

cd ~/Sites/laravel

valet link

一旦應用程式使用 link 指令連結到 Valet，你可以使用其目錄名稱存取該應用程式。因此，上面範例中連結的網站可以在 http://laravel.test 存取。此外，Valet 自動允許你使用萬用字元子網域 (http://foo.laravel.test) 存取網站。

如果你想在不同的主機名稱提供應用程式服務，你可以將主機名稱傳遞給 link 指令。例如，你可以執行以下指令使應用程式在 http://application.test 可用：

cd ~/Sites/laravel

valet link application

當然，你也可以使用 link 指令在子網域上提供應用程式服務：

valet link api.application

你可以執行 links 指令來顯示所有已連結目錄的列表：

valet links

unlink 指令可用於銷毀網站的符號連結：

cd ~/Sites/laravel

valet unlink

使用 TLS 保護網站 (Securing Sites With TLS)

預設情況下，Valet 透過 HTTP 提供網站服務。然而，如果你想使用 HTTP/2 透過加密的 TLS 提供網站服務，你可以使用 secure 指令。例如，如果你的網站由 Valet 在 laravel.test 網域上提供服務，你應該執行以下指令來保護它：

valet secure laravel

要「取消保護」網站並恢復透過純 HTTP 提供流量服務，請使用 unsecure 指令。與 secure 指令一樣，此指令接受你希望取消保護的主機名稱：

valet unsecure laravel

提供預設網站 (Serving a Default Site)

有時，你可能希望設定 Valet 在存取未知的 test 網域時提供「預設」網站，而不是 404。要實現這一點，你可以在 ~/.config/valet/config.json 設定檔中新增一個 default 選項，其中包含應作為預設網站的網站路徑：

"default": "/Users/Sally/Sites/example-site",

各網站 PHP 版本 (Per-Site PHP Versions)

預設情況下，Valet 使用你的全域 PHP 安裝來提供網站服務。然而，如果你需要在不同網站支援多個 PHP 版本，你可以使用 isolate 指令來指定特定網站應使用的 PHP 版本。isolate 指令設定 Valet 為位於你目前工作目錄的網站使用指定的 PHP 版本：

cd ~/Sites/example-site

valet isolate php@8.0

如果你的網站名稱與包含它的目錄名稱不符，你可以使用 --site 選項指定網站名稱：

valet isolate php@8.0 --site="site-name"

為了方便起見，你可以使用 valet php、valet composer 和 valet which-php 指令，根據網站設定的 PHP 版本代理呼叫適當的 PHP CLI 或工具：

valet php
valet composer
valet which-php

你可以執行 isolated 指令來顯示所有已隔離網站及其 PHP 版本的列表：

valet isolated

要將網站恢復為 Valet 的全域安裝 PHP 版本，你可以從網站的根目錄呼叫 unisolate 指令：

valet unisolate

分享網站 (Sharing Sites)

Valet 包含一個與世界分享你的本機網站的指令，提供了一種在行動裝置上測試你的網站或與團隊成員和客戶分享的簡單方法。

預設情況下，Valet 支援透過 ngrok 或 Expose 分享你的網站。在分享網站之前，你應該使用 share-tool 指令更新你的 Valet 設定，指定 ngrok、expose 或 cloudflared：

valet share-tool ngrok

如果你選擇了一個工具但尚未透過 Homebrew (對於 ngrok 和 cloudflared) 或 Composer (對於 Expose) 安裝它，Valet 將自動提示你安裝它。當然，這兩個工具都需要你在開始分享網站之前驗證你的 ngrok 或 Expose 帳戶。

要分享網站，請在終端機導航到網站的目錄並執行 Valet 的 share 指令。一個可公開存取的 URL 將被放入你的剪貼簿，並準備好直接貼到你的瀏覽器或與你的團隊分享：

cd ~/Sites/laravel

valet share

要停止分享你的網站，你可以按 Control + C。

[!WARNING] 如果你使用自訂 DNS 伺服器（如 1.1.1.1），ngrok 分享可能無法正常運作。如果在你的機器上是這種情況，請開啟你的 Mac 系統設定，進入網路設定，開啟進階設定，然後進入 DNS 分頁並新增 127.0.0.1 作為你的第一個 DNS 伺服器。

透過 Ngrok 分享網站 (Sharing Sites via Ngrok)

使用 ngrok 分享你的網站需要你 建立一個 ngrok 帳戶 並 設定驗證權杖。一旦你有了驗證權杖，你可以使用該權杖更新你的 Valet 設定：

valet set-ngrok-token YOUR_TOKEN_HERE

[!NOTE] 你可以傳遞額外的 ngrok 參數給 share 指令，例如 valet share --region=eu。有關更多資訊，請參考 ngrok 文件。

透過 Expose 分享網站 (Sharing Sites via Expose)

使用 Expose 分享你的網站需要你 建立一個 Expose 帳戶 並 透過你的驗證權杖與 Expose 進行驗證。

你可以參考 Expose 文件 以獲取有關其支援的額外命令列參數的資訊。

在區域網路分享網站 (Sharing Sites on Your Local Network)

Valet 預設將傳入流量限制在內部 127.0.0.1 介面，以便你的開發機器不會暴露於來自網際網路的安全風險。

如果你希望允許區域網路上的其他裝置透過你的機器 IP 位址存取你機器上的 Valet 網站（例如：192.168.1.10/application.test），你需要手動編輯該網站的適當 Nginx 設定檔以移除 listen 指令的限制。你應該移除連接埠 80 和 443 的 listen 指令上的 127.0.0.1: 前綴。

如果你還沒有在專案上執行 valet secure，你可以透過編輯 /usr/local/etc/nginx/valet/valet.conf 檔案來為所有非 HTTPS 網站開啟網路存取。然而，如果你透過 HTTPS 提供專案網站服務（你已經為該網站執行了 valet secure），那麼你應該編輯 ~/.config/valet/Nginx/app-name.test 檔案。

一旦你更新了 Nginx 設定，執行 valet restart 指令以套用設定變更。

網站專屬環境變數 (Site Specific Environment Variables)

某些使用其他框架的應用程式可能依賴伺服器環境變數，但沒有提供在專案中設定這些變數的方法。Valet 允許你透過在專案根目錄中新增一個 .valet-env.php 檔案來設定網站專屬環境變數。此檔案應回傳一個網站 / 環境變數對的陣列，這些變數將被新增到陣列中指定的每個網站的全域 $_SERVER 陣列中：

<?php

return [
    // Set $_SERVER['key'] to "value" for the laravel.test site...
    'laravel' => [
        'key' => 'value',
    ],

    // Set $_SERVER['key'] to "value" for all sites...
    '*' => [
        'key' => 'value',
    ],
];

代理服務 (Proxying Services)

有時你可能希望將 Valet 網域代理到本機上的另一個服務。例如，你可能偶爾需要在執行 Valet 的同時在 Docker 中執行一個單獨的網站；然而，Valet 和 Docker 不能同時綁定到連接埠 80。

為了解決這個問題，你可以使用 proxy 指令來產生一個代理。例如，你可以將所有來自 http://elasticsearch.test 的流量代理到 http://127.0.0.1:9200：

# Proxy over HTTP...
valet proxy elasticsearch http://127.0.0.1:9200

# Proxy over TLS + HTTP/2...
valet proxy elasticsearch http://127.0.0.1:9200 --secure

你可以使用 unproxy 指令移除代理：

valet unproxy elasticsearch

你可以使用 proxies 指令列出所有已代理的網站設定：

valet proxies

自訂 Valet 驅動 (Custom Valet Drivers)

你可以編寫自己的 Valet「驅動」來提供 Valet 原生不支援的框架或 CMS 上執行的 PHP 應用程式服務。當你安裝 Valet 時，會建立一個 ~/.config/valet/Drivers 目錄，其中包含一個 SampleValetDriver.php 檔案。此檔案包含一個範例驅動實作，以示範如何編寫自訂驅動。編寫驅動只需要你實作三個方法：serves、isStaticFile 和 frontControllerPath。

這三個方法都接收 $sitePath、$siteName 和 $uri 值作為參數。$sitePath 是你機器上提供的網站的完整路徑，例如 /Users/Lisa/Sites/my-project。$siteName 是網域的「主機」/「網站名稱」部分 (my-project)。$uri 是傳入的請求 URI (/foo/bar)。

一旦你完成了自訂 Valet 驅動，請使用 FrameworkValetDriver.php 命名慣例將其放置在 ~/.config/valet/Drivers 目錄中。例如，如果你正在為 WordPress 編寫自訂 Valet 驅動，你的檔案名稱應為 WordPressValetDriver.php。

讓我們來看看你的自訂 Valet 驅動應該實作的每個方法的範例實作。

serves 方法 (The serves Method)

serves 方法如果你的驅動應該處理傳入的請求，則應回傳 true。否則，該方法應回傳 false。因此，在此方法中，你應該嘗試確定給定的 $sitePath 是否包含你嘗試提供服務的類型的專案。

例如，讓我們想像我們正在編寫一個 WordPressValetDriver。我們的 serves 方法可能看起來像這樣：

/**
 * Determine if the driver serves the request.
 */
public function serves(string $sitePath, string $siteName, string $uri): bool
{
    return is_dir($sitePath.'/wp-admin');
}

isStaticFile 方法 (The isStaticFile Method)

isStaticFile 應確定傳入的請求是否針對「靜態」檔案，例如圖片或樣式表。如果檔案是靜態的，該方法應回傳磁碟上靜態檔案的完整路徑。如果傳入的請求不是針對靜態檔案，該方法應回傳 false：

/**
 * Determine if the incoming request is for a static file.
 *
 * @return string|false
 */
public function isStaticFile(string $sitePath, string $siteName, string $uri)
{
    if (file_exists($staticFilePath = $sitePath.'/public/'.$uri)) {
        return $staticFilePath;
    }

    return false;
}

[!WARNING] > isStaticFile 方法只有在 serves 方法對傳入的請求回傳 true 且請求 URI 不是 / 時才會被呼叫。

frontControllerPath 方法 (The frontControllerPath Method)

frontControllerPath 方法應回傳應用程式「前端控制器」的完整路徑，通常是 "index.php" 檔案或同等檔案：

/**
 * Get the fully resolved path to the application's front controller.
 */
public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
{
    return $sitePath.'/public/index.php';
}

本機驅動 (Local Drivers)

如果你想為單個應用程式定義自訂 Valet 驅動，請在應用程式的根目錄中建立一個 LocalValetDriver.php 檔案。你的自訂驅動可以繼承基礎 ValetDriver 類別或繼承現有的應用程式特定驅動，例如 LaravelValetDriver：

use Valet\Drivers\LaravelValetDriver;

class LocalValetDriver extends LaravelValetDriver
{
    /**
     * Determine if the driver serves the request.
     */
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return true;
    }

    /**
     * Get the fully resolved path to the application's front controller.
     */
    public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
    {
        return $sitePath.'/public_html/index.php';
    }
}

其他 Valet 指令 (Other Valet Commands)

Valet 目錄與檔案 (Valet Directories and Files)

你可能會發現以下目錄和檔案資訊在排除 Valet 環境問題時很有幫助：

~/.config/valet

包含所有 Valet 的設定。你可能希望備份此目錄。

~/.config/valet/dnsmasq.d/

此目錄包含 DNSMasq 的設定。

~/.config/valet/Drivers/

此目錄包含 Valet 的驅動。驅動決定如何提供特定框架 / CMS 的服務。

~/.config/valet/Nginx/

此目錄包含所有 Valet 的 Nginx 網站設定。這些檔案在執行 install 和 secure 指令時會重建。

~/.config/valet/Sites/

此目錄包含你 連結專案 的所有符號連結。

~/.config/valet/config.json

此檔案是 Valet 的主要設定檔。

~/.config/valet/valet.sock

此檔案是 Valet 的 Nginx 安裝使用的 PHP-FPM socket。這只會在 PHP 正常執行時存在。

~/.config/valet/Log/fpm-php.www.log

此檔案是 PHP 錯誤的使用者日誌。

~/.config/valet/Log/nginx-error.log

此檔案是 Nginx 錯誤的使用者日誌。

/usr/local/var/log/php-fpm.log

此檔案是 PHP-FPM 錯誤的系統日誌。

/usr/local/var/log/nginx

此目錄包含 Nginx 存取和錯誤日誌。

/usr/local/etc/php/X.X/conf.d

此目錄包含各種 PHP 設定設定的 *.ini 檔案。

/usr/local/etc/php/X.X/php-fpm.d/valet-fpm.conf

此檔案是 PHP-FPM pool 設定檔。

~/.composer/vendor/laravel/valet/cli/stubs/secure.valet.conf

此檔案是用於為你的網站建立 SSL 憑證的預設 Nginx 設定。

磁碟存取 (Disk Access)

自 macOS 10.14 以來，預設情況下限制存取某些檔案和目錄。這些限制包括桌面、文件和下載目錄。此外，網路卷宗和可移除卷宗存取也受到限制。因此，Valet 建議你的網站資料夾位於這些受保護位置之外。

然而，如果你希望從這些位置之一提供網站服務，你需要給予 Nginx「完全磁碟存取權」。否則，你可能會遇到伺服器錯誤或 Nginx 的其他不可預測行為，特別是在提供靜態資產服務時。通常，macOS 會自動提示你授予 Nginx 對這些位置的完全存取權。或者，你可以透過 系統偏好設定 > 安全性與隱私權 > 隱私權 並選擇 完全磁碟存取權 來手動執行此操作。接下來，啟用主視窗窗格中的任何 nginx 項目。