Версия фреймворка: 8.x 5.4 4.2
Это скорректированный автоматический перевод, сделанный при помощи google translate.

Laravel Sail

Введение

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

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

Laravel Sail поддерживается в macOS, Linux и Windows (через WSL2).

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

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

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

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

composer require laravel/sail --dev

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

php artisan sail:install

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

./vendor/bin/sail up

Настройка Bash псевдонимов

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

./vendor/bin/sail up

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

alias 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, чтобы остановить выполнение контейнера. Или, если контейнеры работают в фоновом режиме, вы можете использовать команду down:

sail down

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

При использовании 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):/opt \
    -w /opt \
    laravelsail/php80-composer:latest \
    composer install --ignore-platform-reqs

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

Команды Laravel Artisan могут быть выполнены с помощью команды artisan:

sail artisan queue:work

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

Команды Node могут выполняться с помощью команды node, а команды NPM выполняются с помощью команды npm:

sail node --version

sail npm run prod

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

MySQL

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

После того как вы запустили свои контейнеры, вы можете подключиться к экземпляру MySQL в вашем приложении, установив для переменной среды DB_HOST в файле вашего приложения .env значение mysql.

Чтобы подключиться к базе данных MySQL вашего приложения с вашего локального компьютера, вы можете использовать графическое приложение для управления базой данных, такое как TablePlus. По умолчанию база данных MySQL доступна через порт 3306 localhost.

Redis

Файл docker-compose.yml вашего приложения также содержит запись для контейнера Redis. Этот контейнер использует том Docker, чтобы данные, хранящиеся в ваших данных Redis, сохранялись даже при остановке и перезапуске ваших контейнеров. После того как вы запустили свои контейнеры, вы можете подключиться к экземпляру Redis в своем приложении, установив для переменной среды REDIS_HOST в файле .env вашего приложения значение redis.

Чтобы подключиться к базе данных Redis вашего приложения с локального компьютера, вы можете использовать графическое приложение для управления базой данных, такое как TablePlus. По умолчанию база данных Redis доступна на порту 6379 localhost.

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

Предпросмотр писем

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

MAIL_HOST=mailhog
MAIL_PORT=1025

Когда Sail запущен, вы можете получить доступ к веб-интерфейсу MailHog по адресу: http://localhost: 8025

Контейнер CLI

Иногда вы можете захотеть запустить сеанс Bash в контейнере вашего приложения. Вы можете использовать команду shell для подключения к контейнеру приложения, что позволит вам проверять его файлы и установленные службы, а также выполнять произвольные команды оболочки внутри контейнера:

sail shell

sail root-shell

Чтобы запустить новый сеанс Laravel Tinker, вы можете выполнить команду tinker:

sail tinker

Версии PHP

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

# 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.0/app

После обновления файла 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.

Настройка

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

sail artisan sail:publish

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

sail build --no-cache