Laravel Valet

Вступ

Шукаєте ще простіший спосіб розробляти застосунки Laravel на macOS чи Windows? Погляньте на Laravel Herd. Herd містить усе потрібне, щоб почати розробку на Laravel, - зокрема Valet, PHP і Composer.

Laravel Valet - середовище розробки для мінімалістів на macOS. Laravel Valet налаштовує ваш Mac так, щоб Nginx завжди працював у фоні від старту системи. Далі, через DnsMasq, Valet проксіює всі запити на домен *.test до сайтів, встановлених на вашій машині.

Іншими словами, Valet - це блискавично швидке середовище розробки Laravel, яке з'їдає приблизно 7 МБ RAM. Valet не є повною заміною Sail чи Homestead, але стане чудовою альтернативою, якщо вам потрібна гнучка основа, ви цінуєте граничну швидкість або працюєте на машині з обмеженою кількістю RAM.

Одразу з коробки Valet підтримує - зокрема, але не лише:

Проте ви можете розширити Valet власними драйверами.

Встановлення

Valet вимагає macOS і Homebrew. Перед встановленням переконайтеся, що жодна інша програма - як-от Apache чи Nginx - не займає порт 80 на вашій машині.

Для початку переконайтеся, що 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

Нарешті, виконайте команду Valet install. Вона налаштує й встановить 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. Valet встановить указану версію PHP через Homebrew, якщо її ще не встановлено:

valet use php@8.2

valet use php

Ви також можете створити файл .valetrc у корені свого проєкту. Файл .valetrc має містити версію PHP, яку слід використовувати для сайту:

php=php@8.2

Коли цей файл створено, ви можете просто виконати команду 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 встановлено, ви готові віддавати свої застосунки 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. Для цього додайте до конфігураційного файлу ~/.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. Перш ніж відкривати сайт, оновіть конфігурацію Valet командою share-tool, указавши ngrok, expose чи cloudflared:

valet share-tool ngrok

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

Щоб відкрити сайт, перейдіть у терміналі до його каталогу й виконайте команду Valet share. Публічно доступний URL потрапить до вашого буфера обміну - його можна одразу вставити у браузер чи надіслати команді:

cd ~/Sites/laravel

valet share

Щоб припинити відкритий доступ до сайту, натисніть Control + C.

Якщо ви користуєтеся власним DNS-сервером (як-от 1.1.1.1), відкриття через ngrok може працювати некоректно. Якщо це ваш випадок, відкрийте системні налаштування Mac, перейдіть до налаштувань мережі, відкрийте додаткові налаштування, перейдіть на вкладку DNS і додайте 127.0.0.1 як перший DNS-сервер.

Відкриття сайтів через Ngrok

Щоб відкрити сайт через ngrok, вам треба створити обліковий запис ngrok і налаштувати токен автентифікації. Коли токен у вас є, оновіть конфігурацію Valet цим токеном:

valet set-ngrok-token YOUR_TOKEN_HERE

Ви можете передати команді share додаткові параметри ngrok - наприклад, 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

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

Метод isStaticFile буде викликано лише тоді, коли метод serves повертає true для вхідного запиту, а URI запиту не дорівнює /.

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

Цей каталог містить усі конфігурації сайтів Nginx у Valet. Ці файли перезбираються під час виконання команд install і secure.

~/.config/valet/Sites/

Цей каталог містить усі символічні посилання на ваші прив'язані проєкти.

~/.config/valet/config.json

Цей файл - головний конфігураційний файл Valet.

~/.config/valet/valet.sock

Цей файл - сокет PHP-FPM, який використовує встановлений Valet Nginx. Він існуватиме, лише якщо 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 у головній панелі вікна.