Laravel Sail
11.x
.
Почему это важно?
- Введение
- Установка и настройка
- Установка Sail в существующее приложение
- Настройка Bash-псевдонимов
- Запуск и остановка Sail
- Выполнение команд
- Выполнение PHP команд
- Выполнение Composer команд
- Выполнение Artisan команд
- Выполнение Node/NPM команд
- Взаимодействие с базами данных
- MySQL
- Redis
- MeiliSearch
- Файловое хранилище
- Тестирование
- Laravel Dusk
- Предпросмотр писем
- Контейнер CLI
- Версии PHP
- Версии Node
- Предоставление доступа к сайту
- Отладка с Xdebug
- Отладка Artisan-команд
- Отладка в браузере
- Настройка
Введение
Laravel Sail – это инструмент командной строки для взаимодействия со средой разработки Docker. Sail обеспечивает отличную отправную точку для создания приложения Laravel с использованием PHP, MySQL и Redis. Опыт работы с Docker не требуется.
По сути, Sail – это файл docker-compose.yml
, который хранится в корне вашего проекта и набор скриптов sail
, при помощи которых можно управлять docker-контейнерами, определёнными в docker-compose.yml
.
Laravel Sail поддерживается в macOS, Linux и Windows (через WSL2).
Установка и настройка
Laravel Sail автоматически устанавливается со всеми новыми приложениями Laravel, поэтому вы можете сразу же начать его использовать. Чтобы узнать, как создать новое приложение Laravel, обратитесь к документации по установке Laravel для вашей операционной системы. Во время установки вам будет предложено выбрать, с какими службами, поддерживаемыми Sail, ваше приложение будет взаимодействовать.
Установка Sail в существующее приложение
Если вы хотите использовать Sail в уже существующем приложении Laravel, вы можете просто установить Sail с помощью диспетчера пакетов Composer:
composer require laravel/sail --dev
После установки Sail вы можете запустить Artisan-команду sail: install
. Эта команда опубликует файл Sail docker-compose.yml
в корень вашего приложения:
php artisan sail:install
Наконец, вы можете запустить Sail. Чтобы продолжить изучение использования Sail, продолжайте читать оставшуюся часть этой документации:
./vendor/bin/sail up
Использование Devcontainer
Если вы хотите разрабатывать с использованием Devcontainer, вы можете указать опцию --devcontainer
команде sail:install
. Эта опция создаст дефолтный конфиг .devcontainer/devcontainer.json
.
php artisan sail:install --devcontainer
Настройка Bash-псевдонимов
По умолчанию команды Sail вызываются с помощью скрипта vendor/bin/sail
:
./vendor/bin/sail up
Однако вместо того, чтобы многократно вводить vendor/bin/sail
, вы можете создать псевдоним (alias) Bash:
alias sail='[ -f sail ] && bash sail || bash vendor/bin/sail'
После настройки псевдонима Bash вы можете выполнять команды Sail, просто набрав sail
. В остальных примерах из этой документации предполагается, что вы настроили этот псевдоним:
sail up
Запуск и остановка Sail
Файл docker-compose.yml
Laravel Sail определяет различные контейнеры Docker, которые работают вместе, чтобы помочь вам создавать приложения Laravel. Чтобы узнать, что это за контейнеры – обратитесь к записи services
вашего файла docker-compose.yml
. Контейнер laravel.test
– это основной контейнер, который будет обслуживать ваше приложение.
Перед запуском Sail убедитесь, что на вашем локальном компьютере не работают другие веб-серверы или базы данных. Чтобы запустить все контейнеры Docker, определенные в файле docker-compose.yml
вашего приложения, вы должны выполнить команду up
:
sail up
Чтобы запустить все контейнеры Docker в фоновом режиме, вы можете запустить Sail в “detached” режиме:
sail up -d
После запуска контейнеров приложения вы можете получить доступ к проекту в своем веб-браузере по адресу: http://localhost.
Чтобы остановить все контейнеры, вы можете просто нажать Control + C, чтобы остановить выполнение контейнера. Если контейнеры работают в фоновом режиме, вы можете использовать команду stop
:
sail stop
Выполнение команд
При использовании Laravel Sail ваше приложение выполняется в контейнере Docker и изолировано от вашего локального компьютера. При помощи Sail можно запускать различные команды для вашего приложения, такие как произвольные команды PHP, команды Artisan, команды Composer и Node/NPM команды.
При чтении документации Laravel вы будете часто видеть команды Composer, Artisan и Node/NPM, в которых не упоминается Sail. В этих примерах предполагается, что эти инструменты установлены на вашем компьютере. Если вы используете Sail для своей локальной среды разработки Laravel, вам следует выполнить эти команды с помощью Sail:
# Локальное выполнение команд Artisan ...
php artisan queue:work
# Выполнение команд Artisan в Laravel Sail ...
sail artisan queue:work
Выполнение PHP команд
Команды PHP могут быть выполнены с помощью команды php
. Конечно, эти команды будут выполняться с использованием версии PHP, настроенной для вашего приложения. Чтобы узнать больше о версиях PHP, доступных для Laravel Sail, обратитесь к документации версии PHP:
sail php --version
sail php script.php
Выполнение Composer команд
Команды Composer могут быть выполнены с помощью команды composer
. Контейнер приложения Laravel Sail содержит Composer 2.x:
sail composer require laravel/sanctum
Установка зависимостей Composer для существующих приложений
Если вы разрабатываете приложение в команде, возможно, вы не тот, кто создал приложение Laravel с нуля. Следовательно, ни одна из зависимостей Composer, включая Sail, не будет установлена после клонирования репозитория приложения на локальный компьютер.
Вы можете установить зависимости приложения, перейдя в каталог приложения и выполнив следующую команду. Эта команда использует небольшой контейнер Docker, содержащий PHP и Composer, для установки зависимостей приложения:
docker run --rm \
-u "$(id -u):$(id -g)" \
-v $(pwd):/var/www/html \
-w /var/www/html \
laravelsail/php81-composer:latest \
composer install --ignore-platform-reqs
При использовании образа laravelsail/phpXX-composer
вы должны использовать ту же версию PHP, которую вы планируете использовать для своего приложения (74
, 80
или 81
).
Выполнение Artisan команд
Команды Laravel Artisan могут быть выполнены с помощью команды artisan
:
sail artisan queue:work
Выполнение Node/NPM команд
Команды Node могут выполняться с помощью команды node
, а команды NPM выполняются с помощью команды npm
:
sail node --version
sail npm run prod
Если вы хотите, вы можете использовать Yarn вместо NPM:
sail yarn
Взаимодействие с базами данных
MySQL
Как вы могли заметить, в файле docker-compose.yml
есть описание контейнера MySQL. Этот контейнер использует том Docker, чтобы данные, хранящиеся в вашей базе данных, сохранялись даже при остановке и перезапуске ваших контейнеров. Вдобавок, когда контейнер MySQL запускается, он гарантирует, что существует база данных, имя которой совпадает со значением вашей переменной окружения DB_DATABASE
.
После того как вы запустили свои контейнеры, вы можете подключиться к экземпляру MySQL в вашем приложении, установив для переменной среды DB_HOST
в файле вашего приложения .env
значение mysql
.
Чтобы подключиться к базе данных MySQL вашего приложения с вашего локального компьютера, вы можете использовать приложение для управления базой данных, такое как TablePlus. По умолчанию база данных MySQL доступна по адресу localhost:3306
.
Redis
В файле docker-compose.yml
также есть описание контейнера Redis. Этот контейнер использует том Docker, чтобы данные, хранящиеся в ваших данных Redis, сохранялись даже при остановке и перезапуске ваших контейнеров. После того как вы запустили свои контейнеры, вы можете подключиться к экземпляру Redis в своем приложении, установив для переменной среды REDIS_HOST
в файле .env
вашего приложения значение redis
.
Чтобы подключиться к базе данных Redis вашего приложения с локального компьютера, вы можете использовать графическое приложение для управления базой данных, такое как TablePlus. По умолчанию база данных Redis доступна по адресу localhost:6379
.
MeiliSearch
Если вы выбрали установку службы MeiliSearch при установке Sail, файл docker-compose.yml
вашего приложения будет содержать контейнер этой мощной поисковой системы, которая совместима с помощью Laravel Scout. После того как вы запустили свои контейнеры, вы можете подключиться к экземпляру MeiliSearch в своем приложении, установив для переменной среды MEILISEARCH_HOST
значение http://meilisearch:7700
.
Со своего локального компьютера вы можете получить доступ к веб-панели администрирования MeiliSearch, перейдя по адресу http://localhost:7700
в своем браузере.
Файловое хранилище
Если вы планируете использовать Amazon S3 для хранения файлов при запуске приложения в производственной среде, вы можете установить службу MinIO при установке Sail. MinIO предоставляет совместимый с S3 API, который вы можете использовать для локальной разработки с помощью драйвера хранилища файлов Laravel s3, не создавая «тестовых» сегментов хранилища в производственной среде S3. Если вы выберете установку MinIO при установке Sail, раздел конфигурации MinIO будет добавлен в файл docker-compose.yml
вашего приложения.
По умолчанию файл конфигурации приложения filesystems
уже содержит конфигурацию диска для диска s3
. Помимо использования этого диска для взаимодействия с Amazon S3, вы можете использовать его для взаимодействия с любой S3-совместимой службой хранения файлов, такой как MinIO, путем простого изменения связанных переменных среды, которые управляют его конфигурацией. Например, при использовании MinIO конфигурация переменной среды вашей файловой системы должна быть определена следующим образом:
FILESYSTEM_DRIVER=s3
AWS_ACCESS_KEY_ID=sail
AWS_SECRET_ACCESS_KEY=password
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=local
AWS_ENDPOINT=http://minio:9000
AWS_USE_PATH_STYLE_ENDPOINT=true
Тестирование
Laravel обеспечивает отличную поддержку тестирования прямо из коробки, и вы можете использовать команду Sail test
для запуска функциональных и модульных тестов. Любые параметры, которые принимает PHPUnit, также могут быть переданы команде test
:
sail test
sail test --group orders
Команда Sail test
эквивалентна запуску Artisan-команды test
:
sail artisan test
Laravel Dusk
Laravel Dusk предоставляет выразительный, простой в использовании API для автоматизации и тестирования браузера. Благодаря Sail вы можете запускать эти тесты, даже не устанавливая Selenium или другие инструменты на свой локальный компьютер. Для начала раскомментируйте службу Selenium в файле docker-compose.yml
вашего приложения:
selenium:
image: 'selenium/standalone-chrome'
volumes:
- '/dev/shm:/dev/shm'
networks:
- sail
Затем убедитесь, что служба laravel.test
в файле docker-compose.yml
вашего приложения имеет запись depends_on
для selenium
:
depends_on:
- mysql
- redis
- selenium
Наконец, вы можете запустить свой набор тестов Dusk, запустив Sail и выполнив команду dusk
:
sail dusk
Selenium на Apple Silicon
Если ваш локальный компьютер содержит чип Apple Silicon, ваша служба selenium
должна использовать образ seleniarm/standalone-chromium
:
selenium:
image: 'seleniarm/standalone-chromium'
volumes:
- '/dev/shm:/dev/shm'
networks:
- sail
Предпросмотр писем
Файл docker-compose.yml
в Laravel Sail по умолчанию содержит контейнер MailHog. MailHog перехватывает электронные письма, отправленные вашим приложением во время локальной разработки, и предоставляет удобный веб-интерфейс, чтобы вы могли предварительно просмотреть свои электронные сообщения в браузере. При использовании Sail хостом MailHog по умолчанию является mailhog
и он доступен через порт 1025:
MAIL_HOST=mailhog
MAIL_PORT=1025
MAIL_ENCRYPTION=null
Когда Sail запущен, вы можете получить доступ к веб-интерфейсу MailHog по адресу: http://localhost:8025
Контейнер CLI
Иногда вы можете захотеть запустить сеанс Bash в контейнере вашего приложения. Вы можете использовать команду shell
для подключения к контейнеру приложения, что позволит вам проверять его файлы и установленные службы, а также выполнять произвольные команды оболочки внутри контейнера:
sail shell
sail root-shell
Чтобы запустить новый сеанс Laravel Tinker, вы можете выполнить команду tinker
:
sail tinker
Версии PHP
В настоящее время Sail поддерживает обслуживание вашего приложения через PHP 8.1, PHP 8.0 или PHP 7.4. Версия PHP по умолчанию, используемая Sail, в настоящее время – PHP 8.1. Чтобы изменить версию PHP, которая используется для обслуживания вашего приложения, вы должны обновить определение build
контейнера laravel.test
в файле docker-compose.yml
вашего приложения:
# PHP 8.1
context: ./vendor/laravel/sail/runtimes/8.1
# PHP 8.0
context: ./vendor/laravel/sail/runtimes/8.0
# PHP 7.4
context: ./vendor/laravel/sail/runtimes/7.4
Кроме того, вы можете захотеть обновить имя image
, чтобы оно отражало версию PHP, используемую приложением. Этот параметр также определен в файле docker-compose.yml
приложения:
image: sail-8.1/app
После обновления файла docker-compose.yml
вашего приложения вы должны обновить образы контейнеров:
sail build --no-cache
sail up
Версии Node
Sail по умолчанию устанавливает Node 16. Чтобы изменить версию Node, установленную при создании образов, вы можете обновить build.args
в файле docker-compose.yml
в определении сервиса laravel.test
вашего приложения:
build:
args:
WWWGROUP: '${WWWGROUP}'
NODE_VERSION: '14'
После обновления файла docker-compose.yml
вашего приложения вы должны обновить образы контейнеров:
sail build --no-cache
sail up
Предоставление доступа к сайту
Иногда может потребоваться предоставить общий доступ к своему сайту, например чтобы его посмотрели коллеги или протестировать вебхуки вашего приложения. Чтобы поделиться своим сайтом, вы можете использовать команду share
. После выполнения этой команды вам будет выдан случайный URL-адрес laravel-sail.site
, который вы можете использовать для доступа к своему приложению:
sail share
При совместном использовании сайта с помощью команды share
вы должны настроить доверенные прокси вашего приложения в посреднике (middleware) TrustProxies
. В противном случае вспомогательные средства генерации URL, такие, как url
и route
, не смогут определить правильный HTTP-хост, который следует использовать во время генерации URL:
/**
* Доверенные прокси для приложения.
*
* @var array|string|null
*/
protected $proxies = '*';
Если вы хотите выбрать поддомен для вашего общего сайта, вы можете указать параметр subdomain
при выполнении команды share
:
sail share --subdomain=my-sail-site
Команда
share
использует Expose, службу туннелирования с открытым исходным кодом от BeyondCode.
Отладка с Xdebug
Laravel Sail содержит поддержку Xdebug, популярного отладчика для PHP. Чтобы включить его, добавьте в .env
параметр для конфигурации Xdebug и затем запустите Sail:
SAIL_XDEBUG_MODE=develop,debug
Настройка IP хоста для Linux
Внутренняя переменная окружения XDEBUG_CONFIG
определяется как client_host=host.docker.internal
, чтобы Xdebug был правильно настроен для Mac и Windows (WSL2). Хост host.docker.internal существует только в системах под управлением Docker Desktop, т.е. Mac и Windows. Если ваша локальная машина работает под управлением Linux, вам нужно будет вручную определить эту переменную окружения.
Во-первых, вы должны определить правильный IP-адрес хоста для добавления в переменную окружения, выполнив следующую команду. Обычно <container-name>
должно быть именем контейнера, обслуживающего ваше приложение, как правило, это имя заканчивается на _laravel.test_1
:
docker inspect -f {{range.NetworkSettings.Networks}}{{.Gateway}}{{end}} <container-name>
После того как вы получили IP-адрес хоста, на котором развёрнут Docker, вы должны определить переменную SAIL_XDEBUG_CONFIG
в файле .env
вашего приложения:
SAIL_XDEBUG_CONFIG="client_host=<host-ip-address>"
Отладка Artisan-команд
Для запуска Artisan-команд с включённым Xdebug используйте команду sail debug
:
# Run an Artisan command without Xdebug...
sail artisan migrate
# Run an Artisan command with Xdebug...
sail debug migrate
Отладка в браузере
Чтобы запустить сессию Xdebug при запросе страницы из браузера, поставьте в браузер расширение или настройте браузер иным способом, следуя инструкциям на сайте Xdebug
Если вы используете Phpstorm, ознакомьтесь с инструкцией по настройке отладки этой IDE.
Laravel Sail полагается на
artisan serve
для обслуживания вашего приложения. Командаartisan serve
принимает только переменныеXDEBUG_CONFIG
иXDEBUG_MODE
начиная с Laravel версии 8.53.0. Более старые версии Laravel (8.52.0 и ниже) не поддерживают эти переменные и не принимают отладочные соединения.
Настройка
Поскольку Sail построен на Docker, вы можете настроить в нём почти всё. Чтобы опубликовать Docker-файлы Sail, и внести в них необходимые вам изменения, вы можете выполнить команду sail:publish
:
sail artisan sail:publish
После выполнения этой команды файлы Dockerfiles и другие файлы конфигурации, используемые Laravel Sail, будут помещены в каталог docker
в корневом каталоге вашего приложения. После настройки вашей установки Sail вы можете изменить имя образа для контейнера приложения в файле docker-compose.yml
вашего приложения. После этого пересоберите контейнеры приложения с помощью команды build
. Назначение уникального имени образу приложения особенно важно, если вы используете Sail для разработки нескольких приложений Laravel на одной машине:
sail build --no-cache