Laravel документація українською

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, тому ви можете почати використовувати його негайно.

Встановлення Sail у існуючі застосунки

Якщо ви зацікавлені у використанні Sail з існуючим Laravel застосунком, ви можете просто встановити Sail за допомогою менеджера пакетів Компонувальник. Звісно, ці кроки передбачають, що ваше існуюче локальне середовище розробки дозволяє вам встановлювати залежності Компонувальника:

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 контекст default, виконавши наступну команду: 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

Іноді ви можете захотіти повністю перебудувати ваші образи Sail, щоб переконатися, що всі пакети та програмне забезпечення образу оновлені. Ви можете зробити це за допомогою команди build:

docker compose down -v
 
sail build --no-cache
 
sail up

Налаштування Псевдоніма Shell

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

./vendor/bin/sail up

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

alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

Щоб переконатися, що це завжди доступно, ви можете додати це до вашого файлу конфігурації shell у вашій домашній директорії, наприклад, ~/.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 у "від'єднаному" режимі:

sail up -d

Як тільки контейнери застосунку будуть запущені, ви можете отримати доступ до проекту у вашому веб-браузері за адресою: http://localhost.

Щоб зупинити всі контейнери, ви можете просто натиснути Control + C, щоб зупинити виконання контейнера. Або, якщо контейнери працюють у фоновому режимі, ви можете скористатися командою stop:

sail stop

Виконання команд

When using Laravel Sail, your застосунок is executing within a Docker container and is isolated from your local computer. However, Sail provides a convenient way to run various commands against your застосунок such as arbitrary PHP commands, Artisan commands, компонувальник commands, and Node / NPM commands.

Коли ви читаєте документацію Laravel, ви часто побачите посилання на команди компонувальника, 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. Контейнер застосунку Laravel Sail включає встановлення компонувальника:

sail composer require laravel/sanctum

Виконання Artisan команд

Команди Laravel Artisan можуть виконуватися за допомогою команди 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, щоб дані, збережені у вашій базі даних, зберігалися навіть при зупинці та перезапуску ваших контейнерів.

Крім того, при першому запуску контейнера MySQL, він створить для вас дві бази даних. Перша база даних називається, використовуючи значення вашої змінної середовища DB_DATABASE, і призначена для вашої локальної розробки. Друга - це спеціальна тестова база даних з назвою testing, яка забезпечить, що ваші тести не заважатимуть даним розробки.

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

Щоб підключитися до MySQL бази даних вашого застосунку з локальної машини, ви можете використовувати графічний застосунок для управління базами даних, такий як TablePlus. За замовчуванням, MySQL база даних доступна на localhost порт 3306, а облікові дані для доступу відповідають значенням ваших змінних середовища DB_USERNAME і DB_PASSWORD. Або ви можете підключитися як користувач root, який також використовує значення вашої змінної середовища DB_PASSWORD як свій пароль.

MongoDB

Якщо ви обрали встановити сервіс MongoDB під час встановлення Sail, файл docker-compose.yml вашого застосунку містить запис для контейнера MongoDB Atlas Local, який надає документну базу даних MongoDB з функціями Atlas, такими як Пошукові Індекси. Цей контейнер використовує том Docker, щоб дані, збережені у вашій базі даних, зберігалися навіть при зупинці та перезапуску ваших контейнерів.

Після того як ви запустили ваші контейнери, ви можете підключитися до екземпляра MongoDB у вашому застосунку, встановивши змінну середовища MONGODB_URI у файлі .env вашого застосунку на mongodb://mongodb:27017. Аутентифікація за замовчуванням вимкнена, але ви можете встановити змінні середовища MONGODB_USERNAME та MONGODB_PASSWORD для увімкнення аутентифікації перед запуском контейнера mongodb. Потім додайте облікові дані до рядка підключення:

MONGODB_USERNAME=user
MONGODB_PASSWORD=laravel
MONGODB_URI=mongodb://${MONGODB_USERNAME}:${MONGODB_PASSWORD}@mongodb:27017

Для безшовної інтеграції MongoDB з вашим застосунком, ви можете встановити офіційний пакет, підтримуваний MongoDB.

Щоб підключитися до бази даних MongoDB вашого застосунку з вашої локальної машини, ви можете використовувати графічний інтерфейс, такий як Compass. За замовчуванням, база даних MongoDB доступна за адресою localhost порт 27017.

Redis

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

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

Valkey

Якщо ви обираєте встановити сервіс Valkey під час встановлення Sail, файл docker-compose.yml вашого застосунку міститиме запис для Valkey. Цей контейнер використовує том Docker, щоб дані, збережені у вашому екземплярі Valkey, зберігалися навіть при зупинці та перезапуску ваших контейнерів. Ви можете підключитися до цього контейнера у вашому застосунку, встановивши змінну середовища REDIS_HOST у файлі .env вашого застосунку на valkey.

Щоб підключитися до бази даних Valkey вашого застосунку з вашої локальної машини, ви можете використовувати графічний застосунок для управління базами даних, такий як TablePlus. За замовчуванням, база даних Valkey доступна на 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's 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 для запуску функціональних та юніт-тестів вашого застосунку. Будь-які параметри CLI, які приймаються 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, щоб підключитися до контейнера вашого застосунку, що дозволить вам перевірити його файли та встановлені сервіси, а також виконувати довільні shell-команди в контейнері:

sail shell
 
sail root-shell

Щоб розпочати нову сесію Laravel Tinker, ви можете виконати команду tinker:

sail tinker

Версії PHP

Sail наразі підтримує обслуговування вашого застосунку за допомогою PHP 8.4, 8.3, 8.2, 8.1 або PHP 8.0. За замовчуванням версія PHP, що використовується Sail, це PHP 8.4. Щоб змінити версію PHP, яка використовується для обслуговування вашого застосунку, вам слід оновити визначення build контейнера laravel.test у файлі docker-compose.yml вашого застосунку:

# PHP 8.4
context: ./vendor/laravel/sail/runtimes/8.4
 
# 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 22. Щоб змінити версію 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, ви повинні налаштувати довірені проксі вашого застосунку, використовуючи метод middleware 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

Конфігурація Docker у Laravel Sail включає підтримку Xdebug, популярного та потужного налагоджувача для PHP. Щоб увімкнути Xdebug, переконайтеся, що ви опублікували вашу конфігурацію Sail. Потім додайте наступні змінні до вашого .env файлу застосунку для налаштування Xdebug:

SAIL_XDEBUG_MODE=develop,debug,coverage

Далі, переконайтеся, що ваш опублікований файл php.ini містить наступну конфігурацію, щоб Xdebug був активований у вказаних режимах:

[xdebug]
xdebug.mode=${XDEBUG_MODE}

Після зміни файлу php.ini не забудьте перебудувати ваші Docker-образи, щоб ваші зміни у файлі php.ini набули чинності:

sail build --no-cache

Конфігурація IP на хості Linux

Внутрішньо змінна середовища XDEBUG_CONFIG визначена як client_host=host.docker.internal, щоб Xdebug був належним чином налаштований для Mac та Windows (WSL2). Якщо ваша локальна машина працює на Linux і ви використовуєте Docker 20.10+, host.docker.internal доступний, і ручна конфігурація не потрібна.

Для версій Docker старіших за 20.10, host.docker.internal не підтримується на Linux, і вам потрібно буде вручну визначити IP хосту. Щоб це зробити, налаштуйте статичний IP для вашого контейнера, визначивши користувацьку мережу у вашому файлі docker-compose.yml:

networks:
  custom_network:
    ipam:
      config:
        - subnet: 172.20.0.0/16
 
services:
  laravel.test:
    networks:
      custom_network:
        ipv4_address: 172.20.0.2

Після того як ви встановили статичну IP-адресу, визначте змінну SAIL_XDEBUG_CONFIG у файлі .env вашого застосунку:

SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"

Використання Xdebug CLI

Команда sail debug може бути використана для початку сеансу налагодження під час виконання команди Artisan:

# Запустити Artisan-команду без Xdebug...
sail artisan migrate
 
# Запустити Artisan-команду з Xdebug...
sail debug migrate

Використання Xdebug у браузері

Щоб налагодити ваш застосунок під час взаємодії з ним через веб-браузер, дотримуйтесь інструкцій, наданих Xdebug для ініціації сесії Xdebug з веб-браузера.

Якщо ви використовуєте PhpStorm, будь ласка, перегляньте документацію JetBrains щодо налагодження без конфігурації.

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
Хостинг для Laravel – Ukraine