Laravel Valet

• 简介
• 安装
  • 升级 Valet
• 服务站点
  • "park" 命令
  • "link" 命令
  • 使用 TLS 保护站点
  • 服务默认站点
  • 每个站点的 PHP 版本
• 共享站点
  • 在本地网络上共享站点
• 站点特定的环境变量
• 代理服务
• 自定义 Valet 驱动
  • 本地驱动
• 其他 Valet 命令
• Valet 目录和文件
  • 磁盘访问

简介

NOTE

想要在 macOS 或 Windows 上更轻松地开发 Laravel 应用程序?请查看 Laravel Herd。Herd 包含了开始 Laravel 开发所需的一切,包括 Valet、PHP 和 Composer。

Laravel Valet 是为 macOS 极简主义者准备的开发环境。Laravel Valet 会在你的 Mac 启动时在后台配置你的机器始终运行 Nginx。然后,使用 DnsMasq,Valet 将所有 *.test 域的请求代理到你本地机器上安装的站点。

换句话说,Valet 是一个极快的 Laravel 开发环境,大约只使用 7MB 内存。Valet 不是 Sail 或 Homestead 的完全替代品,但如果你想要灵活的基础设置、偏好极速,或者在内存有限的机器上工作,它提供了一个很好的选择。

开箱即用,Valet 支持但不限于:

• Laravel
• Bedrock
• CakePHP 3
• ConcreteCMS
• Contao
• Craft
• Drupal
• ExpressionEngine
• Jigsaw
• Joomla
• Katana
• Kirby
• Magento
• OctoberCMS
• Sculpin
• Slim
• Statamic
• 静态 HTML
• Symfony
• WordPress
• Zend

然而,你可以使用自己的自定义驱动程序来扩展 Valet。

安装

WARNING

Valet 需要 macOS 和 Homebrew。在安装之前,你应该确保没有其他程序(如 Apache 或 Nginx)绑定到你本地机器的 80 端口。

首先,你需要确保 Homebrew 是最新的,使用 update 命令:

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 版本

NOTE

而不是修改你的全局 PHP 版本,你可以使用 isolate 命令为每个站点指定 PHP 版本。

Valet 允许你使用 valet use php@version 命令切换 PHP 版本。如果该版本未安装,Valet 将使用 Homebrew 安装该版本:

valet use php@8.2

valet use php

你还可以在项目的根目录中创建一个 .valetrc 文件。该文件应包含站点应使用的 PHP 版本:

php=php@8.2

创建该文件后,你可以简单地执行 valet use 命令,该命令将通过读取该文件来确定站点的首选 PHP 版本。

WARNING

Valet 一次只能服务一个 PHP 版本,即使你安装了多个 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 安装:

• 如果你添加了 .valetphprc 文件来自定义站点的 PHP 版本,请将每个 .valetphprc 文件重命名为 .valetrc。然后,在 .valetrc 文件的现有内容前面加上 php=。
• 更新任何自定义驱动程序,以匹配新驱动程序系统的命名空间、扩展名、类型提示和返回类型提示。你可以参考 Valet 的 SampleValetDriver 作为示例。
• 如果你使用 PHP 7.1 - 7.4 来服务你的站点,请确保你仍然使用 Homebrew 安装 8.0 或更高版本的 PHP,因为 Valet 将使用该版本,即使它不是你的主要链接版本,来运行一些脚本。

服务站点

安装 Valet 后,你就可以开始服务你的 Laravel 应用程序了。Valet 提供了两个命令来帮助你服务你的应用程序: park 和 link。

park 命令

park 命令会在你的机器上注册一个包含你的应用程序的目录。一旦该目录已经"停放"在 Valet 中,该目录中的所有目录都将在你的 web 浏览器中以 http://<directory-name>.test 的形式可访问:

cd ~/Sites

valet park

就是这样。现在,你在"停放"目录中创建的任何应用程序都将自动使用 http://<directory-name>.test 约定来服务。因此,如果你的停放目录包含一个名为 "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 服务站点。但是,如果你想使用加密的 TLS 和 HTTP/2 服务站点,你可以使用 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 php@8.0

如果你的站点名称与包含它的目录名称不匹配,你可以使用 --site 选项指定站点名称:

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

为了方便起见,你可以使用 valet php、composer 和 which-php 命令代理对适当的 PHP CLI 或工具的调用,基于站点配置的 PHP 版本:

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。

WARNING

如果你使用自定义 DNS 服务器(如 1.1.1.1),ngrok 共享可能无法正常工作。如果这是你机器上的情况,请打开 Mac 的系统设置,转到网络设置,打开高级设置,然后转到 DNS 选项卡,并将 127.0.0.1 添加为你的第一个 DNS 服务器。

通过 ngrok 共享站点

使用 ngrok 共享你的站点需要你创建一个 ngrok 帐户和设置身份验证令牌。一旦你有了身份验证令牌,你就可以使用该令牌更新你的 Valet 配置:

valet set-ngrok-token YOUR_TOKEN_HERE

NOTE

你可以将附加的 ngrok 参数传递给 share 命令,例如 valet share --region=eu。有关更多信息,请参阅 ngrok 文档。

通过 Expose 共享站点

使用 Expose 共享你的站点需要你创建一个 Expose 帐户和使用身份验证令牌对 Expose 进行身份验证。

你可以参考 Expose 文档了解有关它支持的其他命令行参数的信息。

在本地网络上共享站点

默认情况下,Valet 会将传入流量限制为内部 127.0.0.1 接口,以便你的开发机器不会从 Internet 暴露给安全风险。

如果你希望允许你本地网络上的其他设备使用你机器的 IP 地址(例如: 192.168.1.10/application.test)访问你机器上的 Valet 站点,你需要手动编辑适当的 Nginx 配置文件,删除 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 数组中,用于指定数组中的每个站点:

    <?php

    return [
        // 为 laravel.test 站点设置 $_SERVER['key'] 为 "value"...
        'laravel' => [
            'key' => 'value',
        ],

        // 为所有站点设置 $_SERVER['key'] 为 "value"...
        '*' => [
            'key' => 'value',
        ],
    ];

代理服务

有时你可能希望将 Valet 域代理到本地机器上的另一个服务。例如,你偶尔可能需要同时运行 Valet 和在 Docker 中运行的单独站点;但是,Valet 和 Docker 不能同时绑定到 80 端口。

为了解决这个问题,你可以使用 proxy 命令生成一个代理。例如,你可以将所有流量从 http://elasticsearch.test 代理到 http://127.0.0.1:9200:

# 通过 HTTP 代理...
valet proxy elasticsearch http://127.0.0.1:9200

# 通过 TLS + HTTP/2 代理...
valet proxy elasticsearch http://127.0.0.1:9200 --secure

你可以使用 unproxy 命令删除代理:

valet unproxy elasticsearch

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

valet proxies

自定义 Valet 驱动

你可以编写自己的 Valet "驱动程序"来服务不是由 Valet 本身原生支持的 PHP 应用程序,例如 Laravel 之外的框架或 CMS。安装 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 编写自定义 Valet 驱动程序,你的文件名应该是 WordPressValetDriver.php。

让我们看一下你的自定义 Valet 驱动程序应该实现的每个方法的示例实现。

serves 方法

The serves method should return true if your driver should handle the incoming request. Otherwise, the method should return false. So, within this method, you should attempt to determine if the given $sitePath contains a project of the type you are trying to serve.

For example, let's imagine we are writing a WordPressValetDriver. Our serves method might look something like this:

    /**
     * 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:

    /**
     * 确定传入请求是否针对静态文件
     *
     * @return string|false
     */
    public function isStaticFile(string $sitePath, string $siteName, string $uri)
    {
        if (file_exists($staticFilePath = $sitePath.'/public/'.$uri)) {
            return $staticFilePath;
        }

        return false;
    }

WARNING

仅当 serves 方法对传入请求返回 true 且请求 URI 不是 / 时，才会调用 isStaticFile 方法。

frontControllerPath 方法

frontControllerPath 方法应返回应用程序的“前端控制器”的完全限定路径，该路径通常是“index.php”文件或等效文件:

    /**
     * 获取应用程序前端控制器的完全解析路径
     */
    public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
    {
        return $sitePath.'/public/index.php';
    }

本地驱动程序

如果要为单个应用程序定义自定义代客驱动程序，请在应用程序的根目录中创建一个 LocalValetDriver.php 文件。您的自定义驱动程序可以扩展基 ValetDriver 类或扩展现有的应用程序特定驱动程序，例如 LaravelValetDriver:

    use Valet\Drivers\LaravelValetDriver;

    class LocalValetDriver extends LaravelValetDriver
    {
        /**
         * 确定驱动程序是否为请求提供服务
         */
        public function serves(string $sitePath, string $siteName, string $uri): bool
        {
            return true;
        }

        /**
         * 获取应用程序前端控制器的完全解析路径
         */
        public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
        {
            return $sitePath.'/public_html/index.php';
        }
    }

其他 Valet 命令

Command	Description
valet list	显示所有 Valet 命令的列表
valet diagnose	输出诊断以帮助调试 Valet
valet directory-listing	确定目录列表行为。默认值为“off”，这将为目录呈现 404 页面
valet forget	从“停放”目录运行此命令，将其从停放目录列表中删除
valet log	查看 Valet 服务写入的日志列表
valet paths	查看所有“停放”路径
valet restart	重新启动 Valet 守护程序
valet start	启动 Valet 守护程序
valet stop	停止 Valet 守护程序
valet trust	为 Brew 和 Valet 添加 sudoers 文件，以允许在不提示输入密码的情况下运行 Valet 命令
valet uninstall	Uninstall Valet:显示手动卸载的说明。传递 --force 选项以主动删除 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 开始，默认情况下限制访问某些文件和目录。这些限制包括 Desktop、Documents 和 Downloads 目录。此外，网络卷和可移动卷的访问也会受到限制。因此，Valet 建议您的站点文件夹位于这些受保护位置之外。

但是，如果您希望从其中一个位置为站点提供服务，则需要为 Nginx 提供“完全磁盘访问权限”。否则，您可能会遇到来自 Nginx 的服务器错误或其他不可预测的行为，尤其是在提供静态资产时。通常，macOS 会自动提示你授予 Nginx 对这些位置的完全访问权限。或者，您可以通过系统偏好设置>安全和隐私>隐私并选择完全磁盘访问来手动执行此操作。接下来，在主窗口窗格中启用任何 nginx 条目。