1. Пакеты
  2. Laravel Sail

Присоединяйся к нашему Telegram сообществу @webblend!

Здесь ты найдешь сниппеты по Laravel и полезные советы по веб-разработке.

Введение

Laravel Sail - это легкий интерфейс командной строки для взаимодействия с средой разработки Laravel на основе Docker. Sail предоставляет отличную отправную точку для создания приложения Laravel с использованием PHP, MySQL и Redis, не требуя опыта работы с Docker.

В основе Sail лежат файл docker-compose.yml и скрипт sail, который хранится в корне вашего проекта. Скрипт sail предоставляет интерфейс командной строки с удобными методами для взаимодействия с контейнерами Docker, определенными в файле docker-compose.yml.

Laravel Sail автоматически устанавливается с каждым новым приложением Laravel, поэтому вы можете начать использовать его немедленно. Чтобы узнать, как создать новое приложение Laravel, пожалуйста, ознакомьтесь с документацией по установке Laravel для вашей операционной системы. При установке вам будет предложено выбрать, с какими сервисами, поддерживаемыми Sail, ваше приложение будет взаимодействовать.

Установка и настройка

Laravel Sail автоматически устанавливается с каждым новым Laravel-приложением, поэтому вы можете начать использовать его немедленно. Чтобы узнать, как создать новое Laravel-приложение, ознакомьтесь с документацией по установке Laravel для вашей операционной системы. Во время установки вам будет предложено выбрать, с какими службами, поддерживаемыми Sail, ваше приложение будет взаимодействовать.

Установка Sail в существующие приложения

Если вас интересует использование Sail с существующим приложением Laravel, вы можете просто установить Sail, используя менеджер пакетов Composer. Конечно же, эти шаги предполагают, что ваша существующая среда локальной разработки позволяет устанавливать зависимости Composer:

composer require laravel/sail --dev

После установки Sail вы можете выполнить команду Artisan sail:install. Эта команда опубликует файл docker-compose.yml Sail в корне вашего приложения и изменит ваш файл .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

Использование Devcontainers

Если вы хотите разрабатывать в Devcontainer, вы можете предоставить параметр --devcontainer команде sail:install. Параметр --devcontainer указывает команде sail:install опубликовать файл .devcontainer/devcontainer.json по умолчанию в корне вашего приложения:

php artisan sail:install --devcontainer

Настройка псевдонима оболочки

По умолчанию Sail-команды вызываются с использованием скрипта vendor/bin/sail, включенного во все новые приложения Laravel:

./vendor/bin/sail up

Однако вместо повторного ввода vendor/bin/sail для выполнения команд Sail, вы можете настроить псевдоним оболочки, который позволяет вам более легко выполнять команды Sail:

alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'

Чтобы всегда иметь доступ к этой команде, вы можете добавить ее в файл конфигурации оболочки в вашем домашнем каталоге, такой как ~/.zshrc или ~/.bashrc, а затем перезапустить вашу оболочку.

После настройки псевдонима оболочки вы можете выполнять команды 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 в «отсоединенном» режиме:

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:

# Running Artisan commands locally...
php artisan queue:work
 
# Running Artisan commands within 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/php82-composer:latest \
composer install --ignore-platform-reqs

При использовании образа laravelsail/phpXX-composer следует использовать ту же версию PHP, которую вы планируете использовать для вашего приложения (80, 81 или 82).

Выполнение команд Artisan

Команды Artisan Laravel можно выполнить с помощью команды artisan:

sail artisan queue:work

Выполнение команд Node / NPM

Команды Node можно выполнить с помощью команды node, а команды NPM - с помощью команды npm:

sail node --version
 
sail npm run dev

Если вы хотите, вы можете использовать Yarn вместо NPM:

sail yarn

Взаимодействие с базами данных

MySQL

Как вы могли заметить, файл docker-compose.yml вашего приложения содержит запись для контейнера MySQL. Этот контейнер использует Docker volume, чтобы данные, хранящиеся в вашей базе данных, сохранялись даже при остановке и перезапуске ваших контейнеров.

Кроме того, при первом запуске контейнера 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 volume, чтобы данные, хранящиеся в вашем 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, в файл docker-compose.yml вашего приложения будет добавлен раздел конфигурации MinIO.

По умолчанию файл конфигурации 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 предоставляет потрясающую поддержку тестирования из коробки, и вы можете использовать команду test Sail для запуска ваших функциональных и модульных тестов. Любые опции командной строки, принимаемые PHPUnit, также можно передать команде test:

sail test
 
sail test --group orders

Команда test Sail эквивалентна выполнению команды test Artisan:

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 должна использовать образ seleniarm/standalone-chromium:

selenium:
image: 'seleniarm/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

Командная строка контейнера

Иногда вам может понадобиться запустить сеанс 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.2. Чтобы изменить версию 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.1/app

После обновления файла docker-compose.yml вашего приложения вы должны пересоздать образы контейнеров:

sail build --no-cache
 
sail up

Версии Node

Sail устанавливает Node 20 по умолчанию. Чтобы изменить версию Node, которая устанавливается при создании образов, вы можете обновить определение build.args сервиса laravel.test в файле docker-compose.yml вашего приложения:

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. В противном случае средства генерации URL, такие как url и route, не смогут определить правильный HTTP-хост, который должен использоваться при генерации URL:

/**
* Доверенные прокси для этого приложения.
*
* @var array|string|null
*/
protected $proxies = '*';

Если вы хотите выбрать поддомен для вашего общего сайта, вы можете предоставить параметр subdomain при выполнении команды share:

sail share --subdomain=my-sail-site

Примечание Команда share работает на основе Expose - сервиса для туннелирования с открытым исходным кодом от BeyondCode.

Отладка с Xdebug

Docker-конфигурация Laravel Sail включает поддержку Xdebug, популярного и мощного отладчика для PHP. Чтобы включить Xdebug, вам нужно добавить несколько переменных в файл .env вашего приложения, чтобы настроить Xdebug. Для включения Xdebug необходимо установить соответствующий режим(ы) перед запуском Sail:

SAIL_XDEBUG_MODE=develop,debug,coverage

Конфигурация IP-адреса хоста Linux

Внутренне переменная среды XDEBUG_CONFIG определена как client_host=host.docker.internal, чтобы Xdebug был правильно настроен для Mac и Windows (WSL2). Если ваша локальная машина работает под управлением Linux, убедитесь, что вы используете Docker Engine версии 17.06.0+ и Compose версии 1.16.0+. В противном случае вам придется вручную определить эту переменную среды, как показано ниже.

Сначала определите правильный IP-адрес хоста для добавления в переменную среды, выполнив следующую команду. Обычно <container-name> должен быть именем контейнера, который обслуживает ваше приложение и часто заканчивается на _laravel.test_1:

docker inspect -f modify_10x/sail.range.NetworkSettings.Networks{{.Gateway}}modify_10x/sail.end <container-name>

После получения правильного IP-адреса хоста вы должны определить переменную SAIL_XDEBUG_CONFIG в файле .env вашего приложения:

SAIL_XDEBUG_CONFIG="client_host=<host-ip-address>"

Использование Xdebug в командной строке

Команду sail debug можно использовать для запуска сеанса отладки при выполнении команды Artisan:

# Run an Artisan command without Xdebug...
sail artisan migrate
 
# Run an Artisan command with Xdebug...
sail debug migrate

Использование Xdebug в браузере

Чтобы отлаживать ваше приложение во взаимодействии с приложением через веб-браузер, следуйте инструкциям, предоставленным Xdebug по инициированию сеанса Xdebug из веб-браузера.

Если вы используете PhpStorm, пожалуйста, ознакомьтесь с документацией JetBrain по отладке без конфигурации.

Внимание Laravel Sail полагается на artisan serve для обслуживания вашего приложения. Команда artisan serve принимает только переменные XDEBUG_CONFIG и XDEBUG_MODE начиная с версии Laravel 8.53.0. Более старые версии Laravel (8.52.0 и ниже) не поддерживают эти переменные и не будут принимать соединения для отладки.

Настройка

Поскольку Sail - это просто Docker, вы свободны в настройке практически всего. Чтобы опубликовать Dockerfiles Sail, вы можете выполнить команду sail:publish:

sail artisan sail:publish

После выполнения этой команды Dockerfiles и другие файлы конфигурации, используемые Laravel Sail, будут размещены в каталоге docker в корне вашего приложения. После настройки вашей установки Sail вы можете захотеть изменить имя образа для контейнера приложения в файле docker-compose.yml вашего приложения. После этого перестройте контейнеры вашего приложения с помощью команды build. Присвоение уникального имени образу приложения особенно важно, если вы используете Sail для разработки нескольких приложений Laravel на одной машине:

sail build --no-cache