Laravel Sail
- Введение
- Установка и настройка
- Установка Sail в существующее приложение
- Пересборка образов Sail
- Настройка Shell-псевдонимов
- Запуск и остановка Sail
- Выполнение команд
- Выполнение PHP команд
- Выполнение Composer команд
- Выполнение Artisan команд
- Выполнение Node/NPM команд
- Взаимодействие с базами данных
- MySQL
- Redis
- Meilisearch
- Typesense
- Файловое хранилище
- Тестирование
- 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
в корень вашего приложения и изменит файл .env
, добавив необходимые переменные окружения для подключения к Docker-сервисам::
php artisan sail:install
Наконец, вы можете запустить Sail. Чтобы продолжить изучение использования Sail, продолжайте читать оставшуюся часть этой документации:
./vendor/bin/sail up
Если вы используете Docker Desktop для Linux, выполните следующую команду, чтобы использовать контекст Docker по умолчанию:
docker context use default
.
Добавление дополнительных сервисов:
Если вы хотите добавить дополнительный сервис к вашей текущей установке Sail, выполните команду Artisan sail:add
:
php artisan sail:add
Использование Devcontainer
Если вы хотите разрабатывать с использованием Devcontainer, вы можете указать опцию --devcontainer
команде sail:install
. Эта опция создаст дефолтный конфиг .devcontainer/devcontainer.json
.
php artisan sail:install --devcontainer
Пересборка образов Sail
Иногда вам может потребоваться полностью пересобрать образы Sail, чтобы убедиться, что все пакеты и программное обеспечение образа обновлены. Вы можете сделать это с помощью команды build
:
docker compose down -v
sail build --no-cache
sail up
Настройка Shell-псевдонимов
По умолчанию команды Sail вызываются с помощью скрипта vendor/bin/sail
:
./vendor/bin/sail up
Однако вместо того, чтобы многократно вводить vendor/bin/sail
, вы можете создать псевдоним (alias) Shell:
alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'
Чтобы убедиться, что это всегда доступно, добавьте это в файл конфигурации оболочки в вашем домашнем каталоге, таком как ~/.zshrc
или ~/.bashrc
, а затем перезапустите вашу оболочку.
После настройки псевдонима Shell вы можете выполнять команды 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:
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/php83-composer:latest \
composer install --ignore-platform-reqs
При использовании образа laravelsail/phpXX-composer
вы должны использовать ту же версию PHP, которую вы планируете использовать для своего приложения (80
, 81
, 82
, или 83
).
Выполнение 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
и предназначена для локальной разработки. Вторая – это отдельная тестовая база данных с именем testing
, которая гарантирует, что ваши тесты не будут вмешиваться в данные вашей разработки.
После того как вы запустили свои контейнеры, вы можете подключиться к экземпляру MySQL в вашем приложении, установив для переменной среды DB_HOST
в файле вашего приложения .env
значение mysql
.
Чтобы подключиться к базе данных MySQL вашего приложения с вашего локального компьютера, вы можете использовать приложение для управления базой данных, такое как TablePlus. По умолчанию база данных MySQL доступна по адресу localhost:3306
, а учетные данные доступа соответствуют значениям ваших переменных окружения DB_USERNAME
и DB_PASSWORD
. Или вы можете подключиться как пользователь root
, используя значение переменной окружения DB_PASSWORD
в качестве пароля.
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
в своем браузере.
Typesense
Если вы решили установить службу Typesense при установке Sail, ваш файл docker-compose.yml
вашего приложения будет содержать запись для этого быстрого и открытого поискового движка, который интегрирован с Laravel Scout. После запуска ваших контейнеров, вы можете подключиться к экземпляру Typesense в вашем приложении, установив следующие переменные окружения:
TYPESENSE_HOST=typesense
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=xyz
Со своего локального компьютера вы можете получить доступ к API Typesense по адресу http://localhost:8108
.
Файловое хранилище
Если вы планируете использовать Amazon S3 для хранения файлов при запуске приложения в производственной среде, вы можете установить службу MinIO при установке Sail. MinIO предоставляет совместимый с S3 API, который вы можете использовать для локальной разработки с помощью драйвера хранилища файлов Laravel s3, не создавая «тестовых» сегментов хранилища в производственной среде S3. Если вы выберете установку MinIO при установке Sail, раздел конфигурации MinIO будет добавлен в файл docker-compose.yml
вашего приложения.
По умолчанию файл конфигурации приложения filesystems
уже содержит конфигурацию диска для диска s3
. Помимо использования этого диска для взаимодействия с Amazon S3, вы можете использовать его для взаимодействия с любой S3-совместимой службой хранения файлов, такой как MinIO, путем простого изменения связанных переменных среды, которые управляют его конфигурацией. Например, при использовании MinIO конфигурация переменной среды вашей файловой системы должна быть определена следующим образом:
FILESYSTEM_DISK=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
Для того чтобы интеграция Flysystem в Laravel генерировала правильные URL при использовании MinIO, необходимо определить переменную окружения AWS_URL
, чтобы она соответствовала локальному URL вашего приложения и включала имя сегмента в путь URL:
AWS_URL=http://localhost:9000/local
Вы можете создавать сегменты через консоль MinIO, которая доступна по адресу http://localhost:8900
. Имя пользователя по умолчанию для консоли MinIO – sail
, а пароль – password
.
Генерация временных URL-адресов с использованием метода
temporaryUrl
не поддерживается при использовании MinIO.
Тестирование
Laravel обеспечивает отличную поддержку тестирования прямо из коробки, и вы можете использовать команду Sail test
для запуска функциональных и модульных тестов. Любые параметры, которые принимает Pest / PHPUnit, также могут быть переданы команде test
:
sail test
sail test --group orders
Команда Sail test
эквивалентна запуску Artisan-команды test
:
sail artisan test
По умолчанию Sail создает отдельную базу данных testing
, чтобы ваши тесты не влияли на текущее состояние вашей базы данных. В стандартной установке Laravel Sail также настраивает ваш файл phpunit.xml
для использования этой базы данных при выполнении тестов:
<env name="DB_DATABASE" value="testing"/>
Laravel Dusk
Laravel Dusk предоставляет выразительный, простой в использовании API для автоматизации и тестирования браузера. Благодаря Sail вы можете запускать эти тесты, даже не устанавливая Selenium или другие инструменты на свой локальный компьютер. Для начала раскомментируйте службу Selenium в файле docker-compose.yml
вашего приложения:
selenium:
image: 'selenium/standalone-chrome'
extra_hosts:
- 'host.docker.internal:host-gateway'
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
должна использовать образ selenium/standalone-chromium
:
selenium:
image: 'selenium/standalone-chromium'
extra_hosts:
- 'host.docker.internal:host-gateway'
volumes:
- '/dev/shm:/dev/shm'
networks:
- sail
Предпросмотр писем
Файл docker-compose.yml
в Laravel Sail по умолчанию содержит контейнер Mailpit. Mailpit перехватывает электронные письма, отправленные вашим приложением во время локальной разработки, и предоставляет удобный веб-интерфейс, чтобы вы могли предварительно просмотреть свои электронные сообщения в браузере. При использовании Sail хостом Mailpit по умолчанию является mailpit
и он доступен через порт 1025:
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null
Когда Sail запущен, вы можете получить доступ к веб-интерфейсу Mailpit по адресу: http://localhost:8025
Контейнер CLI
Иногда вы можете захотеть запустить сеанс Bash в контейнере вашего приложения. Вы можете использовать команду shell
для подключения к контейнеру приложения, что позволит вам проверять его файлы и установленные службы, а также выполнять произвольные команды оболочки внутри контейнера:
sail shell
sail root-shell
Чтобы запустить новый сеанс Laravel Tinker, вы можете выполнить команду tinker
:
sail tinker
Версии PHP
В настоящее время Sail поддерживает обслуживание вашего приложения через PHP 8.3, 8.2, 8.1 или PHP 8.0. Версия PHP по умолчанию, используемая Sail, в настоящее время – PHP 8.3. Чтобы изменить версию PHP, которая используется для обслуживания вашего приложения, вы должны обновить определение build
контейнера laravel.test
в файле docker-compose.yml
вашего приложения:
# PHP 8.3
context: ./vendor/laravel/sail/runtimes/8.3
# PHP 8.2
context: ./vendor/laravel/sail/runtimes/8.2
# PHP 8.1
context: ./vendor/laravel/sail/runtimes/8.1
# PHP 8.0
context: ./vendor/laravel/sail/runtimes/8.0
Кроме того, вы можете захотеть обновить имя image
, чтобы оно отражало версию PHP, используемую приложением. Этот параметр также определен в файле docker-compose.yml
приложения:
image: sail-8.2/app
После обновления файла docker-compose.yml
вашего приложения вы должны обновить образы контейнеров:
sail build --no-cache
sail up
Версии Node
Sail по умолчанию устанавливает Node 20. Чтобы изменить версию Node, установленную при создании образов, вы можете обновить build.args
в файле docker-compose.yml
в определении сервиса laravel.test
вашего приложения:
build:
args:
WWWGROUP: '${WWWGROUP}'
NODE_VERSION: '18'
После обновления файла docker-compose.yml
вашего приложения вы должны обновить образы контейнеров:
sail build --no-cache
sail up
Предоставление доступа к сайту
Иногда может потребоваться предоставить общий доступ к своему сайту, например чтобы его посмотрели коллеги или протестировать вебхуки вашего приложения. Чтобы поделиться своим сайтом, вы можете использовать команду share
. После выполнения этой команды вам будет выдан случайный URL-адрес laravel-sail.site
, который вы можете использовать для доступа к своему приложению:
sail share
При совместном использовании сайта с помощью команды share
вам следует настроить доверенные прокси-серверы вашего приложения, используя метод посредника TrustProxies
в файле bootstrap/app.php
вашего приложения. В противном случае помощники создания URL-адресов, такие как url
и route
, не смогут определить правильный HTTP-хост, который следует использовать во время создания URL-адреса:
->withMiddleware(function (Middleware $middleware) {
$middleware->trustProxies(at: '*');
})
Если вы хотите выбрать поддомен для вашего общего сайта, вы можете указать параметр subdomain
при выполнении команды share
:
sail share --subdomain=my-sail-site
Команда
share
использует Expose, службу туннелирования с открытым исходным кодом от BeyondCode.
Отладка с Xdebug
Laravel Sail содержит поддержку Xdebug, популярного отладчика для PHP. Чтобы включить его, добавьте в .env
параметр для конфигурации Xdebug и затем запустите Sail:
SAIL_XDEBUG_MODE=develop,debug,coverage
Настройка IP хоста для Linux
Внутренняя переменная окружения XDEBUG_CONFIG
определяется как client_host=host.docker.internal
, чтобы Xdebug был правильно настроен для Mac и Windows (WSL2). Хост host.docker.internal существует только в системах под управлением Docker Desktop, т.е. Mac и Windows. Если ваша локальная машина работает под управлением Linux, убедитесь, что у вас установлен Docker Engine версии 17.06.0+ и Compose версии 1.16.0+; в противном случае вам нужно будет вручную определить эту переменную окружения, как показано ниже..
Во-первых, вы должны определить правильный 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