Laravel Valet

• Введение
• Установка
  • Обновление Valet
• Обслуживание сайтов
  • Команда "Park"
  • Команда "Link"
  • Защита сайтов с помощью TLS
  • Обслуживание сайта по умолчанию
  • Версии PHP для каждого сайта
• Общий доступ к сайтам
  • Общий доступ к сайтам в локальной сети
• Переменные окружения для конкретных сайтов
• Проксирование сервисов
• Пользовательские драйверы Valet
  • Локальные драйверы
• Другие команды Valet
• Каталоги и файлы Valet
  • Доступ к диску

#Введение

Laravel Valet — это среда разработки для минималистов на macOS. Laravel Valet настраивает ваш Mac так, чтобы при запуске системы всегда работал Nginx в фоновом режиме. Затем, используя DnsMasq, Valet проксирует все запросы к доменам *.test на сайты, установленные на вашем локальном компьютере.

Иными словами, Valet — это сверхбыстрая среда разработки Laravel, которая использует примерно 7 МБ оперативной памяти. Valet не является полноценной заменой Sail или Homestead, но представляет собой отличную альтернативу, если вам нужны гибкие базовые возможности, вы предпочитаете максимальную скорость или работаете на машине с ограниченным объёмом оперативной памяти.

Из коробки Valet поддерживает, но не ограничивается следующими платформами:

Однако вы можете расширить Valet, создав собственные пользовательские драйверы.

#Установка

Для начала убедитесь, что Homebrew обновлён, выполнив команду update:

brew update

Далее установите PHP с помощью Homebrew:

brew install php

После установки PHP можно установить Composer. Также убедитесь, что каталог $HOME/.composer/vendor/bin добавлен в системную переменную "PATH". После установки Composer вы можете установить Laravel Valet как глобальный пакет Composer:

composer global require laravel/valet

Наконец, выполните команду install Valet. Она настроит и установит Valet и DnsMasq. Кроме того, необходимые демоны будут настроены на автоматический запуск при старте системы:

valet install

После установки Valet попробуйте выполнить ping любого домена *.test в терминале, например, ping foobar.test. Если Valet установлен правильно, вы увидите ответ от 127.0.0.1.

Valet автоматически запускает необходимые сервисы при каждой загрузке системы.

#Версии PHP

Valet позволяет переключать версии PHP с помощью команды valet use php@version. Если указанная версия PHP не установлена, Valet установит её через Homebrew:

valet use php@8.1

valet use php

Вы также можете создать файл .valetrc в корне вашего проекта. Файл .valetrc должен содержать версию PHP, которую должен использовать сайт:

php=php@8.1

После создания файла достаточно выполнить команду valet use, которая определит предпочтительную версию PHP для сайта, прочитав содержимое файла.

#База данных

Если вашему приложению нужна база данных, обратите внимание на DBngin — бесплатный универсальный инструмент управления базами данных, включающий MySQL, PostgreSQL и Redis. После установки DBngin вы можете подключаться к базе по адресу 127.0.0.1 с пользователем root и пустым паролем.

#Сброс установки

Если у вас возникают проблемы с работой Valet, выполнение команды composer global require laravel/valet с последующим valet install сбросит установку и может решить многие проблемы. В редких случаях может потребоваться "жёсткий сброс" с помощью valet uninstall --force и повторной установки valet install.

#Обновление Valet

Вы можете обновить Valet, выполнив команду composer global require laravel/valet в терминале. После обновления рекомендуется запустить valet install для внесения необходимых изменений в конфигурационные файлы.

#Обновление до Valet 4

Если вы обновляетесь с Valet 3 до Valet 4, выполните следующие шаги для корректного обновления:

#Обслуживание сайтов

После установки Valet вы готовы начать обслуживать ваши Laravel-приложения. Valet предоставляет две команды для этого: park и link.

#Команда park

Команда park регистрирует каталог на вашем компьютере, содержащий приложения. После "парковки" каталога все вложенные в него каталоги будут доступны в браузере по адресу 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

После связывания приложения с Valet через команду link вы можете получить к нему доступ по имени каталога. Например, сайт, связанный в примере выше, будет доступен по адресу 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. Например, чтобы защитить сайт на домене laravel.test, выполните:

valet secure laravel

Чтобы перевести сайт в небезопасный режим и вернуть обслуживание его трафика по обычному HTTP, используйте команду unsecure. Как и команда secure, эта команда принимает имя хоста, который вы хотите перевести в небезопасный режим:

valet unsecure laravel

#Обслуживание сайта по умолчанию

Иногда вы можете захотеть настроить Valet так, чтобы он обслуживал «сайт по умолчанию» вместо 404, когда вы заходите на неизвестный домен test. Для этого можно добавить опцию default в файл конфигурации ~/.config/valet/config.json, содержащую путь к сайту, который должен служить сайтом по умолчанию:

"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

Чтобы вернуть сайт к использованию глобальной версии PHP Valet, выполните команду unisolate из корня сайта:

valet unisolate

#Общий доступ к сайтам

Valet включает команду для предоставления общего доступа к вашим локальным сайтам, что упрощает тестирование на мобильных устройствах или обмен с командой и клиентами.

Из коробки Valet поддерживает общий доступ через ngrok или Expose. Перед тем как делиться сайтом, обновите конфигурацию Valet с помощью команды share-tool, указав ngrok или expose:

valet share-tool ngrok

Если выбранный инструмент не установлен через Homebrew (для ngrok) или Composer (для Expose), Valet предложит установить его автоматически. Оба инструмента требуют аутентификации в вашем аккаунте перед началом общего доступа.

Чтобы поделиться сайтом, перейдите в каталог сайта в терминале и выполните команду share Valet. Публичный URL будет скопирован в буфер обмена и готов к вставке в браузер или передачи команде:

cd ~/Sites/laravel

valet share

Чтобы прекратить общий доступ, нажмите Control + C.

#Общий доступ через Ngrok

Для использования ngrok необходимо создать аккаунт ngrok и получить токен аутентификации. После получения токена обновите конфигурацию Valet:

valet set-ngrok-token YOUR_TOKEN_HERE

#Общий доступ через Expose

Для использования Expose необходимо создать аккаунт Expose и аутентифицироваться с помощью токена.

Дополнительную информацию о поддерживаемых параметрах командной строки смотрите в документации Expose.

#Общий доступ к сайтам в локальной сети

По умолчанию Valet ограничивает входящий трафик интерфейсом 127.0.0.1, чтобы защитить вашу машину от внешних угроз.

Если вы хотите разрешить другим устройствам в вашей локальной сети обращаться к сайтам Valet на этой машине по её IP-адресу (например: 192.168.1.10/application.test), вам нужно вручную отредактировать соответствующий конфигурационный файл Nginx для этого сайта, чтобы убрать ограничение в директиве listen. Удалите префикс 127.0.0.1: у директивы listen для портов 80 и 443.

Если вы не запускали valet secure для проекта, откройте доступ в сети для всех сайтов без HTTPS, отредактировав файл /usr/local/etc/nginx/valet/valet.conf. Если же сайт обслуживается по HTTPS (вы запускали valet secure), редактируйте файл ~/.config/valet/Nginx/app-name.test.

После изменения конфигурации Nginx выполните команду valet restart для применения изменений.

#Переменные окружения для конкретных сайтов

Некоторые приложения на других фреймворках зависят от переменных окружения сервера, но не предоставляют способ их настройки в проекте. Valet позволяет задавать переменные окружения для конкретных сайтов, добавляя файл .valet-env.php в корень проекта. Этот файл должен возвращать массив пар сайт / переменная окружения, которые будут добавлены в глобальный массив $_SERVER для каждого указанного сайта:

<?php

return [
    // Установить $_SERVER['key'] в "value" для сайта laravel.test...
    '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 для обслуживания PHP-приложений на фреймворках или CMS, которые не поддерживаются Valet по умолчанию. При установке 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).

После создания пользовательского драйвера поместите его в каталог ~/.config/valet/Drivers с именем по шаблону FrameworkValetDriver.php. Например, для WordPress имя файла должно быть WordPressValetDriver.php.

Рассмотрим пример реализации каждого метода, который должен содержать ваш пользовательский драйвер Valet.

#Метод serves

Метод serves должен возвращать true, если драйвер должен обрабатывать входящий запрос. В противном случае — false. В этом методе нужно определить, содержит ли $sitePath проект нужного типа.

Например, если мы пишем WordPressValetDriver, метод serves может выглядеть так:

/**
 * Определяет, обслуживает ли драйвер запрос.
 */
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;
}

#Метод frontControllerPath

Метод frontControllerPath должен возвращать полный путь к «фронт-контроллеру» вашего приложения, который обычно представляет собой файл "index.php" или его эквивалент:

/**
 * Получить полный путь к фронт-контроллеру приложения.
 */
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
{
    /**
     * Определяет, обслуживает ли драйвер запрос.
     */
    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

#Каталоги и файлы Valet

Следующая информация о каталогах и файлах может быть полезна при устранении проблем с вашей средой Valet:

#~/.config/valet

Содержит всю конфигурацию Valet. Рекомендуется делать резервную копию этого каталога.

#~/.config/valet/dnsmasq.d/

Каталог с конфигурацией DNSMasq.

#~/.config/valet/Drivers/

Каталог с драйверами Valet. Драйверы определяют, как обслуживается конкретный фреймворк или CMS.

#~/.config/valet/Nginx/

Каталог с конфигурациями сайтов Nginx для Valet. Эти файлы пересоздаются при выполнении команд install и secure.

#~/.config/valet/Sites/

Каталог с символическими ссылками для ваших связанных проектов.

#~/.config/valet/config.json

Главный конфигурационный файл Valet.

#~/.config/valet/valet.sock

PHP-FPM сокет, используемый установкой Nginx Valet. Существует только если 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

Каталог с файлами *.ini для различных настроек PHP.

#/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, доступ к некоторым файлам и каталогам ограничен по умолчанию. Эти ограничения касаются каталогов Desktop, Documents и Downloads. Также ограничен доступ к сетевым и съемным томам. Поэтому Valet рекомендует размещать папки сайтов вне этих защищённых локаций.

Однако, если вы хотите обслуживать сайты из одного из этих мест, вам нужно будет дать Nginx "Full Disk Access". В противном случае вы можете столкнуться с ошибками сервера или другим непредсказуемым поведением со стороны Nginx, особенно при обслуживании статических ресурсов. Обычно macOS автоматически предложит предоставить Nginx полный доступ к этим местам. Либо вы можете сделать это вручную через System Preferences > Security & Privacy > Privacy и выбрать Full Disk Access. Затем включите любые записи nginx в основной области окна.