Документация Laravel 10.x
Здесь ты найдешь сниппеты по 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 с существующим приложением 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
Если вы хотите разрабатывать в 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
Файл 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 в Laravel Sail, ознакомьтесь с документацией по версиям PHP:
sail php --version sail php script.php
Команды Composer можно выполнить с помощью команды composer
. В контейнере приложения Laravel Sail установлена версия Composer 2.x:
sail composer require laravel/sanctum
Если вы разрабатываете приложение в команде, вы можете быть не тем, кто изначально создает приложение 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 Laravel можно выполнить с помощью команды artisan
:
sail artisan queue:work
Команды Node можно выполнить с помощью команды node
, а команды NPM - с помощью команды npm
:
sail node --version sail npm run dev
Если вы хотите, вы можете использовать Yarn вместо NPM:
sail yarn
Как вы могли заметить, файл 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
в качестве пароля.
Файл docker-compose.yml
вашего приложения также содержит запись для контейнера Redis. Этот контейнер использует Docker volume, чтобы данные, хранящиеся в вашем Redis, сохранялись даже при остановке и перезапуске ваших контейнеров. После запуска ваших контейнеров вы можете подключиться к экземпляру Redis внутри вашего приложения, установив переменную окружения REDIS_HOST
в вашем файле .env
вашего приложения в значение redis
.
Для подключения к базе данных Redis вашего приложения с локальной машины вы можете использовать графическое приложение для управления базой данных, такое как TablePlus. По умолчанию база данных Redis доступна по адресу localhost
порт 6379.
Если вы решили установить сервис 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=s3AWS_ACCESS_KEY_ID=sailAWS_SECRET_ACCESS_KEY=passwordAWS_DEFAULT_REGION=us-east-1AWS_BUCKET=localAWS_ENDPOINT=http://minio:9000AWS_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 предоставляет выразительный и простой в использовании 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
Если ваша локальная машина содержит чип 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=mailpitMAIL_PORT=1025MAIL_ENCRYPTION=null
Когда Sail работает, вы можете получить доступ к веб-интерфейсу Mailpit по адресу: http://localhost:8025
Иногда вам может понадобиться запустить сеанс Bash в контейнере вашего приложения. Вы можете использовать команду shell
для подключения к контейнеру вашего приложения, что позволит вам проверять его файлы и установленные службы, а также выполнять произвольные команды оболочки в контейнере:
sail shell sail root-shell
Чтобы начать новый сеанс Laravel Tinker, вы можете выполнить команду tinker
:
sail tinker
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.3context: ./vendor/laravel/sail/runtimes/8.3 # PHP 8.2context: ./vendor/laravel/sail/runtimes/8.2 # PHP 8.1context: ./vendor/laravel/sail/runtimes/8.1 # PHP 8.0context: ./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
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.
Docker-конфигурация Laravel Sail включает поддержку Xdebug, популярного и мощного отладчика для PHP. Чтобы включить Xdebug, вам нужно добавить несколько переменных в файл .env
вашего приложения, чтобы настроить Xdebug. Для включения Xdebug необходимо установить соответствующий режим(ы) перед запуском Sail:
SAIL_XDEBUG_MODE=develop,debug,coverage
Внутренне переменная среды 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>"
Команду sail debug
можно использовать для запуска сеанса отладки при выполнении команды Artisan:
# Run an Artisan command without Xdebug...sail artisan migrate # Run an Artisan command with Xdebug...sail debug migrate
Чтобы отлаживать ваше приложение во взаимодействии с приложением через веб-браузер, следуйте инструкциям, предоставленным 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