Laravel Valet

Введение

Ищете еще более простой способ разработки приложений Laravel на macOS? Посмотрите Laravel Herd. Herd включает все необходимое для начала разработки на Laravel, включая Valet, PHP и Composer.

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

Другими словами, Valet – это быстрая среда разработки для Laravel, которая использует примерно 7 МБ оперативной памяти. Valet не является полной заменой Sail или Homestead, но предоставляет отличную альтернативу, если вы предпочитаете гибкость основ или скорость работы, или работаете на компьютере с ограниченным количеством оперативной памяти.

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

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

Установка

Для использования 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

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

valet install

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

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

Версии PHP

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

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

valet use php@8.1

valet use php

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

php=php@8.1

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

Valet обслуживает только одну версию PHP за раз, даже если у вас установлено несколько версий PHP.

База данных

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

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

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

Обновление Valet

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

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

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

• Если вы добавили файлы .valetphprc для настройки версии PHP вашего сайта, переименуйте каждый файл .valetphprc в .valetrc. Затем добавьте в начало содержимого файла .valetrc строку php=.
• Обновите любые пользовательские драйверы, чтобы они соответствовали пространству имён, расширению, типам данных и типам возвращаемых значений новой системы драйверов. Вы можете воспользоваться образцом драйвера Valet в качестве примера.
• Если вы используете PHP версий 7.1 – 7.4 для обслуживания своих сайтов, убедитесь, что вы по-прежнему используете Homebrew для установки версии PHP 8.0 или выше, так как Valet будет использовать эту версию, даже если она не является вашей основной выбранной версией, для выполнения некоторых своих скриптов.

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

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

Команда park

Команда park регистрирует каталог на вашем компьютере, который содержит ваши приложения. После того как каталог был “припаркован” к Valet, все каталоги внутри этого каталога будут доступны в вашем веб-браузере по адресу 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. Например, если ваш сайт обслуживается Valet по домену 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 автоматически предложит вам установить его. Конечно, оба инструмента требуют аутентификации вашей учетной записи ngrok или Expose, прежде чем вы сможете предоставить доступ к сайту к сайтам.

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

cd ~/Sites/laravel

valet share

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

Если вы используете пользовательский DNS-сервер (например, 1.1.1.1), возможно, ngrok sharing не будет работать корректно. Если это так, откройте настройки системы вашего Mac, перейдите в настройки сети, откройте расширенные настройки, затем перейдите на вкладку DNS и добавьте 127.0.0.1 в качестве вашего первого DNS-сервера.

Предоставление доступа к сайтам через Ngrok

Чтобы предоставить доступ к вашему сайту с использованием ngrok, вам необходимо создать учетную запись ngrok и настроить токен аутентификации. После получения токена аутентификации вы можете обновить вашу конфигурацию Valet с использованием этого токена:

valet set-ngrok-token YOUR_TOKEN_HERE

Вы можете передавать дополнительные параметры ngrok команде share, такие как valet share --region=eu. Для получения дополнительной информации ознакомьтесь с документацией ngrok.

Предоставление доступа к сайтам через Expose

Чтобы предоставить доступ к вашему сайту с использованием 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 [
    // 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 для обслуживания 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).

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

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

Метод 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 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;
}

Метод isStaticFile будет вызван только в том случае, если метод serves вернет true для входящего запроса и URI запроса не равен /.

Метод frontControllerPath

Метод frontControllerPath должен вернуть полный путь к “front controller” вашего приложения, который обычно является файлом “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:

~/.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, доступ к некоторым файлам и каталогам по умолчанию ограничен. К этим ограничениям относятся каталоги Рабочего стола, Документов и Загрузок. Кроме того, доступ к сетевым и съемным томам ограничен. Поэтому Valet рекомендует размещать каталоги сайтов за пределами этих защищенных мест.

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