Laravel Valet

• 簡介
• 安裝
  • 升級 Valet
• 服務站點
  • "Park" 命令
  • "Link" 命令
  • 使用 TLS 保護站點
  • 服務預設站點
  • 每個站點的 PHP 版本
• 共享站點
  • 在本地網路上共享站點
• 站點特定環境變數
• 代理服務
• 自訂 Valet 驅動程式
  • 本機驅動程式
• 其他 Valet 命令
• Valet 目錄和檔案
  • 磁碟存取

簡介

Laravel Valet 是 macOS 極簡主義者的開發環境。 Laravel Valet 將您的 Mac 設定為在機器啟動時始終在後台執行 Nginx。然後，使用 DnsMasq，Valet 會將 *.test 網域上的所有請求代理到指向安裝在您本地機器上的站點。

換句話說，Valet 是一個快速的 Laravel 開發環境，大約使用 7 MB 的 RAM。 Valet 並不是 Sail 或 Homestead 的完整替代品，但如果您想要彈性的基礎功能、偏好極致的速度，或是在 RAM 有限的機器上工作，它提供了很棒的替代方案。

開箱即用，Valet 支援包括但不限於

但是，您可以使用自己的 自訂驅動程式擴展 Valet。

安裝

若要開始，您首先需要使用 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 版本

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

valet use [email protected]
 
valet use php

您也可以在專案的根目錄中建立 .valetrc 檔案。 .valetrc 檔案應包含站點應使用的 PHP 版本

php=php@8.2

建立此檔案後，您只需執行 valet use 命令，該命令將透過讀取檔案來確定站點偏好的 PHP 版本。

資料庫

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

重置您的安裝

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

升級 Valet

您可以透過在您的終端機中執行 composer global require laravel/valet 命令來更新您的 Valet 安裝。升級後，最好執行 valet install 命令，以便 Valet 可以根據需要對您的組態檔進行額外的升級。

升級至 Valet 4

如果您要從 Valet 3 升級到 Valet 4，請按照下列步驟正確升級您的 Valet 安裝

服務站點

安裝 Valet 後，您就可以開始服務您的 Laravel 應用程式。 Valet 提供兩個命令來協助您服務您的應用程式：park 和 link。

park 命令

park 命令會在您的機器上註冊一個包含您應用程式的目錄。一旦目錄透過 Valet 「parked」，該目錄內的所有目錄都可以在您的網頁瀏覽器中透過 http://<directory-name>.test 存取

cd ~/Sites
 
valet park

就這麼簡單。現在，您在「parked」目錄中建立的任何應用程式都將使用 http://<directory-name>.test 慣例自動服務。因此，如果您的 parked 目錄包含一個名為「laravel」的目錄，則該目錄中的應用程式將可透過 http://laravel.test 存取。此外，Valet 會自動允許您使用萬用字元子網域 (http://foo.laravel.test) 存取該站點。

link 命令

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 保護站點

預設情況下，Valet 通過 HTTP 提供網站服務。但是，如果您想使用 HTTP/2 通過加密的 TLS 提供網站服務，您可以使用 secure 命令。例如，如果您的網站正在由 Valet 在 laravel.test 網域上提供服務，您應該執行以下命令來保護它

valet secure laravel

要「取消保護」網站並恢復通過純 HTTP 提供流量，請使用 unsecure 命令。與 secure 命令一樣，此命令接受您要取消保護的主機名稱

valet unsecure laravel

服務預設站點

有時，您可能希望配置 Valet 在訪問未知的 test 網域時，提供一個「預設」網站，而不是 404 錯誤頁面。為此，您可以在您的 ~/.config/valet/config.json 設定檔中添加一個 default 選項，其中包含應作為預設網站的站點路徑

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

每個站點的 PHP 版本

預設情況下，Valet 使用您的全域 PHP 安裝來提供網站服務。但是，如果您需要在不同的網站之間支援多個 PHP 版本，您可以使用 isolate 命令來指定特定網站應使用哪個 PHP 版本。isolate 命令會配置 Valet 為您目前工作目錄中的網站使用指定的 PHP 版本

cd ~/Sites/example-site
 
valet isolate [email protected]

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

valet isolate [email protected] --site="site-name"

為了方便起見，您可以使用 valet php、composer 和 which-php 命令，根據網站配置的 PHP 版本，將呼叫代理到適當的 PHP CLI 或工具

valet php
valet composer
valet which-php

您可以執行 isolated 命令來顯示所有隔離網站及其 PHP 版本的清單

valet isolated

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

valet unisolate

共享站點

Valet 包含一個與全世界分享您本地網站的命令，提供了一種在移動裝置上測試您的網站或與團隊成員和客戶分享它的便捷方式。

Valet 開箱即用支援通過 ngrok 或 Expose 分享您的網站。在分享網站之前，您應該使用 share-tool 命令更新您的 Valet 設定，指定 ngrok 或 expose

valet share-tool ngrok

如果您選擇了一個工具，但沒有通過 Homebrew（對於 ngrok）或 Composer（對於 Expose）安裝它，Valet 會自動提示您安裝它。當然，這兩個工具都需要您驗證您的 ngrok 或 Expose 帳戶，然後才能開始分享網站。

若要分享網站，請在您的終端機中導航到該網站的目錄，並執行 Valet 的 share 命令。一個可公開訪問的 URL 將被放置到您的剪貼簿中，並且可以立即貼到您的瀏覽器中或與您的團隊分享

cd ~/Sites/laravel
 
valet share

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

通過 Ngrok 分享網站

使用 ngrok 分享您的網站需要您建立一個 ngrok 帳戶並設定一個身份驗證令牌。一旦您擁有身份驗證令牌，您可以使用該令牌更新您的 Valet 設定

valet set-ngrok-token YOUR_TOKEN_HERE

通過 Expose 分享網站

使用 Expose 分享您的網站需要您建立一個 Expose 帳戶並通過您的身份驗證令牌驗證 Expose。

您可以參考Expose 文件，以了解它支援的其他命令列參數的相關資訊。

在本地網路上共享站點

Valet 預設限制傳入流量到內部 127.0.0.1 介面，因此您的開發機器不會暴露於來自網際網路的安全風險。

如果您希望允許本地網路上的其他裝置通過您機器的 IP 位址（例如：192.168.1.10/application.test）訪問您機器上的 Valet 網站，您將需要手動編輯該網站的相應 Nginx 設定檔，以刪除 listen 指令的限制。您應該刪除 listen 指令中用於埠 80 和 443 的 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 命令來應用設定變更。

站點特定環境變數

某些使用其他框架的應用程式可能會依賴於伺服器環境變數，但沒有提供在您的專案中配置這些變數的方法。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',
    ],
];

代理服務

有時您可能希望將 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 驅動程式

您可以編寫自己的 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 方法

如果您的驅動程式應該處理傳入的請求，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 方法

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

frontControllerPath 方法

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

本機驅動程式

如果您想為單個應用程式定義自定義 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 命令

Valet 目錄和檔案

在對您的 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 套接字。只有在 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 池設定檔。

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

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

磁碟存取

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

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