Laravel Valet

• 簡介
• 安裝
  • 升級 Valet
• 服務站點
  • "Park" 命令
  • "Link" 命令
  • 使用 TLS 加密站點
  • 設定預設站點
  • 各站點自定義 PHP 版本
• 共享站點
  • 在本地網路共享站點
• 站點特定的環境變數
• 代理服務
• 自定義 Valet 驅動
  • 本地驅動
• 其他 Valet 命令
• Valet 目錄與檔案
  • 磁碟訪問

簡介

Laravel Valet 是一個專為 macOS 極簡主義者打造的開發環境。Laravel Valet 會將你的 Mac 配置為在系統啟動時始終在後臺執行 Nginx。然後，利用 DnsMasq，Valet 將所有 *.test 域名的請求代理指向本地機器上安裝的站點。

換句話說，Valet 是一個佔用約 7 MB 記憶體、執行速度極快的 Laravel 開發環境。Valet 並不是要完全取代 Sail 或 Homestead，但如果你想要靈活的基礎設施、追求極致速度，或者在記憶體有限的機器上工作，它是一個絕佳的選擇。

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

當然，你也可以透過自定義驅動來擴充套件 Valet。

安裝

首先，你需要確保 Homebrew 使用 update 命令保持最新狀態：

1brew update

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

1brew install php

安裝完 PHP 後，你就可以準備安裝 Composer 包管理器了。此外，你應該確保 $HOME/.composer/vendor/bin 目錄在系統的 "PATH" 中。Composer 安裝完成後，你可以將 Laravel Valet 作為全域性 Composer 包進行安裝：

1composer global require laravel/valet

最後，執行 Valet 的 install 命令。這將配置並安裝 Valet 和 DnsMasq。此外，Valet 所依賴的守護程序也將被配置為在系統啟動時自動執行。

1valet install

Valet 安裝完成後，嘗試在終端中使用如 ping foobar.test 的命令 ping 任何 *.test 域名。如果安裝正確，你應該會看到該域名響應 127.0.0.1。

Valet 會在每次電腦開機時自動啟動所需服務。

PHP 版本

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

1valet use [email protected]
2 
3valet use php

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

1php=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 訪問。

1cd ~/Sites
2 
3valet park

就是這麼簡單。現在，你在 "parked" 目錄下建立的任何應用程式都將自動透過 http://<directory-name>.test 約定進行服務。例如，如果你的 parked 目錄下有一個名為 "laravel" 的目錄，那麼該目錄下的應用程式將可以透過 http://laravel.test 訪問。此外，Valet 還允許你使用萬用字元子域名（http://foo.laravel.test）訪問站點。

link 命令

link 命令也可以用於服務 Laravel 應用。如果你只想服務目錄中的單個站點，而不是整個目錄，這個命令非常有用。

1cd ~/Sites/laravel
2 
3valet link

一旦應用程式使用 link 命令連結到 Valet，你就可以使用其目錄名稱訪問該應用程式。因此，上述示例中連結的站點可以透過 http://laravel.test 訪問。此外，Valet 還會自動允許你使用萬用字元子域名（http://foo.laravel.test）訪問該站點。

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

1cd ~/Sites/laravel
2 
3valet link application

當然，你也可以使用 link 命令在子域名上服務應用程式。

1valet link api.application

你可以執行 links 命令檢視所有已連結目錄的列表。

1valet links

unlink 命令可用於銷燬站點的符號連結。

1cd ~/Sites/laravel
2 
3valet unlink

使用 TLS 加密站點

預設情況下，Valet 透過 HTTP 服務站點。但是，如果你想透過 HTTPS/TLS 使用 HTTP/2 服務站點，可以使用 secure 命令。例如，如果你的站點由 Valet 在 laravel.test 域名上服務，則應執行以下命令來保護它：

1valet secure laravel

要“取消保護”（unsecure）站點並恢復到透過純 HTTP 服務，請使用 unsecure 命令。與 secure 命令一樣，該命令接受你想要取消保護的主機名。

1valet unsecure laravel

設定預設站點

有時，你可能希望配置 Valet 在訪問未知的 test 域名時提供“預設”站點，而不是顯示 404。為此，你可以在 ~/.config/valet/config.json 配置檔案中新增一個 default 選項，包含應作為預設站點的路徑。

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

各站點自定義 PHP 版本

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

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

如果站點名稱與包含它的目錄名稱不匹配，你可以使用 --site 選項指定站點名稱。

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

為方便起見，你可以使用 valet php、composer 和 which-php 命令，根據站點配置的 PHP 版本代理呼叫相應的 PHP CLI 或工具。

1valet php
2valet composer
3valet which-php

你可以執行 isolated 命令來檢視所有已隔離的站點及其 PHP 版本列表。

1valet isolated

要將站點恢復到 Valet 全域性安裝的 PHP 版本，可以在該站點的根目錄下呼叫 unisolate 命令。

1valet unisolate

共享站點

Valet 包含一個命令來向公眾共享你的本地站點，這是在移動裝置上測試站點或與團隊成員和客戶共享站點的簡便方法。

Valet 開箱即支援透過 ngrok 或 Expose 共享站點。在共享站點之前，你應該使用 share-tool 命令更新 Valet 配置，指定 ngrok、expose 或 cloudflared。

1valet share-tool ngrok

如果你選擇了一個工具但未透過 Homebrew（對於 ngrok 和 cloudflared）或 Composer（對於 Expose）安裝它，Valet 會自動提示你安裝。當然，這兩個工具都需要你在開始共享站點之前驗證你的 ngrok 或 Expose 賬戶。

要共享站點，請在終端中導航到該站點目錄並執行 Valet 的 share 命令。一個可公開訪問的 URL 將被放入你的剪貼簿，可以直接貼上到瀏覽器中或與團隊分享。

1cd ~/Sites/laravel
2 
3valet share

要停止共享站點，可以按 Control + C。

透過 Ngrok 共享站點

使用 ngrok 共享站點需要你建立一個 ngrok 賬戶並設定一個身份驗證令牌。擁有令牌後，你可以用該令牌更新 Valet 配置：

1valet set-ngrok-token YOUR_TOKEN_HERE

透過 Expose 共享站點

使用 Expose 共享站點需要你建立一個 Expose 賬戶並透過身份驗證令牌進行驗證。

你可以查閱 Expose 文件以獲取有關其支援的其他命令列引數的資訊。

在本地網路共享站點

預設情況下，Valet 限制傳入流量僅能透過內部 127.0.0.1 介面，以確保你的開發機器不會暴露於來自網際網路的安全風險中。

如果你希望允許本地網路上的其他裝置透過機器的 IP 地址（例如：192.168.1.10/application.test）訪問機器上的 Valet 站點，則需要手動編輯該站點的相應 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 命令以應用配置更改。

站點特定的環境變數

一些使用其他框架的應用可能依賴於伺服器環境變數，但沒有提供在專案內配置這些變數的方法。Valet 允許你透過在專案根目錄下新增 .valet-env.php 檔案來配置站點特定的環境變數。該檔案應返回一個包含站點/環境變數對的陣列，這些變數將新增到陣列中指定的每個站點的全域性 $_SERVER 陣列中。

 1<?php
 2 
 3return [
 4    // Set $_SERVER['key'] to "value" for the laravel.test site...
 5    'laravel' => [
 6        'key' => 'value',
 7    ],
 8 
 9    // Set $_SERVER['key'] to "value" for all sites...
10    '*' => [
11        'key' => 'value',
12    ],
13];

代理服務

有時，你可能希望將 Valet 域名代理到本地機器上的另一個服務。例如，你可能偶爾需要在執行 Docker 中獨立站點時使用 Valet；但是，Valet 和 Docker 不能同時繫結到 80 埠。

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

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

你可以使用 unproxy 命令移除代理。

1valet unproxy elasticsearch

你可以使用 proxies 命令列出所有已代理的站點配置。

1valet 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 驅動後，請將其放在 ~/.config/valet/Drivers 目錄中，並遵循 FrameworkValetDriver.php 命名約定。例如，如果你正在為 WordPress 編寫自定義驅動，檔名應該是 WordPressValetDriver.php。

讓我們看看自定義 Valet 驅動中每個應實現的方法的示例。

serves 方法

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

例如，假設我們正在編寫一個 WordPressValetDriver。我們的 serves 方法可能如下所示：

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

isStaticFile 方法

isStaticFile 應確定傳入請求是否針對“靜態”檔案，例如影像或樣式表。如果檔案是靜態的，該方法應返回磁碟上靜態檔案的完全限定路徑。如果傳入請求不是針對靜態檔案，則該方法應返回 false。

 1/**
 2 * Determine if the incoming request is for a static file.
 3 *
 4 * @return string|false
 5 */
 6public function isStaticFile(string $sitePath, string $siteName, string $uri)
 7{
 8    if (file_exists($staticFilePath = $sitePath.'/public/'.$uri)) {
 9        return $staticFilePath;
10    }
11 
12    return false;
13}

frontControllerPath 方法

frontControllerPath 方法應返回應用程式“前端控制器”的完全限定路徑，通常是“index.php”檔案或等效檔案。

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

本地驅動

如果你想為單個應用程式定義自定義 Valet 驅動，請在該應用程式的根目錄下建立一個 LocalValetDriver.php 檔案。你的自定義驅動可以擴充套件基礎 ValetDriver 類，或擴充套件現有的特定應用驅動（如 LaravelValetDriver）。

 1use Valet\Drivers\LaravelValetDriver;
 2 
 3class LocalValetDriver extends LaravelValetDriver
 4{
 5    /**
 6     * Determine if the driver serves the request.
 7     */
 8    public function serves(string $sitePath, string $siteName, string $uri): bool
 9    {
10        return true;
11    }
12 
13    /**
14     * Get the fully resolved path to the application's front controller.
15     */
16    public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
17    {
18        return $sitePath.'/public_html/index.php';
19    }
20}

其他 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

此檔案是用於為站點構建 SSL 證書的預設 Nginx 配置檔案。

磁碟訪問

自 macOS 10.14 起，對某些檔案和目錄的訪問預設受到限制。這些限制包括桌面、文件和下載目錄。此外，對網路卷和可移動卷的訪問也受到限制。因此，Valet 建議你的站點資料夾位於這些受保護位置之外。

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