Laravel Homestead

• Введение
• Установка и настройка
  • Первые шаги
  • Настройка Homestead
  • Настройка сайтов Nginx
  • Настройка сервисов
  • Запуск Vagrant Box
  • Установка на проект
  • Установка дополнительных функций
  • Псевдонимы
• Обновление Homestead
• Ежедневное использование
  • Подключение по SSH
  • Добавление дополнительных сайтов
  • Переменные окружения
  • Порты
  • Версии PHP
  • Подключение к базам данных
  • Резервное копирование баз данных
  • Настройка расписания Cron
  • Настройка Mailpit
  • Настройка Minio
  • Laravel Dusk
  • Общий доступ к окружению
• Отладка и профилирование
  • Отладка веб-запросов с Xdebug
  • Отладка CLI-приложений
  • Профилирование приложений с Blackfire
• Сетевые интерфейсы
• Расширение Homestead
• Настройки для конкретных провайдеров
  • VirtualBox

#Введение

Laravel стремится сделать весь процесс разработки на PHP приятным, включая локальное окружение для разработки. Laravel Homestead — это официальный, готовый к использованию Vagrant box, который предоставляет отличное окружение для разработки без необходимости устанавливать PHP, веб-сервер или другое серверное ПО на вашу локальную машину.

Vagrant предлагает простой и элегантный способ управления и настройки виртуальных машин. Vagrant box можно полностью удалить и создать заново. Если что-то пойдет не так, вы сможете уничтожить и восстановить box за считанные минуты!

Homestead работает на Windows, macOS и Linux и включает Nginx, PHP, MySQL, PostgreSQL, Redis, Memcached, Node и все необходимое программное обеспечение для разработки отличных Laravel-приложений.

#Включенное программное обеспечение

#Дополнительное программное обеспечение

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

#Первые шаги

Перед запуском окружения Homestead необходимо установить Vagrant и один из поддерживаемых провайдеров:

• VirtualBox 6.1.x
• Parallels

Все эти программы имеют удобные визуальные установщики для популярных операционных систем.

Для использования провайдера Parallels необходимо установить Parallels Vagrant plug-in. Он бесплатен.

#Установка Homestead

Вы можете установить Homestead, склонировав репозиторий Homestead на вашу хост-машину. Рекомендуется клонировать репозиторий в папку Homestead в вашем домашнем каталоге, так как виртуальная машина Homestead будет хостить все ваши Laravel-приложения. В этой документации мы будем называть эту папку «директорией Homestead»:

git clone https://github.com/laravel/homestead.git ~/Homestead

После клонирования репозитория Laravel Homestead следует переключиться на ветку release. Эта ветка всегда содержит последнюю стабильную версию Homestead:

cd ~/Homestead

git checkout release

Далее выполните команду bash init.sh из директории Homestead, чтобы создать файл конфигурации Homestead.yaml. Файл Homestead.yaml — это место, где вы настроите все параметры вашей установки Homestead. Этот файл будет размещён в директории Homestead:

# macOS / Linux...
bash init.sh

# Windows...
init.bat

#Настройка Homestead

#Выбор провайдера

Ключ provider в файле Homestead.yaml указывает, какой Vagrant провайдер использовать: virtualbox или parallels:

provider: virtualbox

#Настройка общих папок

Свойство folders в файле Homestead.yaml содержит список папок, которые вы хотите расшарить с окружением Homestead. При изменении файлов в этих папках они будут синхронизироваться между вашей локальной машиной и виртуальной машиной Homestead. Вы можете настроить любое количество общих папок:

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1

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

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1
    - map: ~/code/project2
      to: /home/vagrant/project2

Для включения NFS можно добавить опцию type в настройку папки:

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1
      type: "nfs"

Вы также можете передавать любые опции, поддерживаемые Vagrant для синхронизируемых папок, перечисляя их под ключом options:

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1
      type: "rsync"
      options:
          rsync__args: ["--verbose", "--archive", "--delete", "-zz"]
          rsync__exclude: ["node_modules"]

#Настройка сайтов Nginx

Если вы не знакомы с Nginx, не беспокойтесь. Свойство sites в файле Homestead.yaml позволяет легко сопоставить «домен» с папкой в окружении Homestead. В файле Homestead.yaml уже есть пример конфигурации сайта. Вы можете добавить любое количество сайтов в Homestead. Homestead удобно использовать как виртуализированное окружение для всех ваших Laravel-приложений:

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public

Если вы измените свойство sites после настройки виртуальной машины Homestead, выполните команду vagrant reload --provision в терминале, чтобы обновить конфигурацию Nginx на виртуальной машине.

#Разрешение имён хостов

Homestead публикует имена хостов с помощью mDNS для автоматического разрешения. Если в файле Homestead.yaml указано hostname: homestead, хост будет доступен по адресу homestead.local. macOS, iOS и большинство Linux-дистрибутивов поддерживают mDNS по умолчанию. Для Windows необходимо установить Bonjour Print Services for Windows.

Автоматические имена хостов лучше всего подходят для установок на проект Homestead. Если вы размещаете несколько сайтов на одном экземпляре Homestead, вы можете добавить домены ваших веб‑сайтов в файл hosts на вашей машине. Файл hosts будет перенаправлять запросы к вашим сайтам Homestead в виртуальную машину Homestead. В macOS и Linux этот файл находится по пути /etc/hosts. В Windows он находится по пути C:\Windows\System32\drivers\etc\hosts. Строки, которые вы добавите в этот файл, будут выглядеть следующим образом:

192.168.56.56  homestead.test

Убедитесь, что IP-адрес совпадает с тем, что указан в вашем файле Homestead.yaml. После добавления домена в файл hosts и запуска Vagrant box вы сможете получить доступ к сайту через браузер:

http://homestead.test

#Настройка сервисов

По умолчанию Homestead запускает несколько сервисов, но вы можете настроить, какие сервисы включать или отключать при настройке. Например, можно включить PostgreSQL и отключить MySQL, изменив опцию services в файле Homestead.yaml:

services:
    - enabled:
        - "postgresql"
    - disabled:
        - "mysql"

Указанные сервисы будут запускаться или останавливаться в соответствии с порядком в директивах enabled и disabled.

#Запуск Vagrant Box

После редактирования файла Homestead.yaml запустите команду vagrant up из директории Homestead. Vagrant загрузит виртуальную машину и автоматически настроит общие папки и сайты Nginx.

Для удаления машины используйте команду vagrant destroy.

#Установка на проект

Вместо глобальной установки Homestead и использования одной виртуальной машины для всех проектов, вы можете настроить отдельный экземпляр Homestead для каждого проекта. Такой подход удобен, если вы хотите включить Vagrantfile в репозиторий проекта, чтобы другие разработчики могли сразу запустить vagrant up после клонирования.

Установите Homestead в проект с помощью менеджера пакетов Composer:

composer require laravel/homestead --dev

После установки Homestead выполните команду make, чтобы сгенерировать Vagrantfile и файл Homestead.yaml для вашего проекта. Эти файлы будут размещены в корне проекта. Команда make автоматически настроит директивы sites и folders в файле Homestead.yaml:

# macOS / Linux...
php vendor/bin/homestead make

# Windows...
vendor\\bin\\homestead make

Далее запустите команду vagrant up в терминале и откройте проект в браузере по адресу http://homestead.test. Не забудьте добавить запись в файл /etc/hosts для homestead.test или другого домена, если не используете автоматическое разрешение имён.

#Установка дополнительных функций

Дополнительное программное обеспечение устанавливается через опцию features в файле Homestead.yaml. Большинство функций можно включить или отключить булевым значением, некоторые поддерживают дополнительные параметры настройки:

features:
    - blackfire:
        server_id: "server_id"
        server_token: "server_value"
        client_id: "client_id"
        client_token: "client_value"
    - cassandra: true
    - chronograf: true
    - couchdb: true
    - crystal: true
    - dragonflydb: true
    - elasticsearch:
        version: 7.9.0
    - eventstore: true
        version: 21.2.0
    - flyway: true
    - gearman: true
    - golang: true
    - grafana: true
    - influxdb: true
    - logstash: true
    - mariadb: true
    - meilisearch: true
    - minio: true
    - mongodb: true
    - neo4j: true
    - ohmyzsh: true
    - openresty: true
    - pm2: true
    - python: true
    - r-base: true
    - rabbitmq: true
    - rustc: true
    - rvm: true
    - solr: true
    - timescaledb: true
    - trader: true
    - webdriver: true

#Elasticsearch

Вы можете указать поддерживаемую версию Elasticsearch, которая должна быть точным номером версии (major.minor.patch). По умолчанию создается кластер с именем 'homestead'. Никогда не выделяйте Elasticsearch больше половины памяти ОС, поэтому убедитесь, что у виртуальной машины Homestead минимум вдвое больше памяти, чем выделено Elasticsearch.

#MariaDB

Включение MariaDB удалит MySQL и установит MariaDB. MariaDB обычно служит заменой MySQL, поэтому в конфигурации базы данных вашего приложения следует продолжать использовать драйвер mysql.

#MongoDB

По умолчанию при установке MongoDB имя пользователя базы данных будет homestead, а пароль — secret.

#Neo4j

По умолчанию при установке Neo4j имя пользователя базы данных будет homestead, а пароль — secret. Для доступа к браузеру Neo4j откройте http://homestead.test:7474 в браузере. Порты 7687 (Bolt), 7474 (HTTP) и 7473 (HTTPS) готовы принимать запросы от клиента Neo4j.

#Псевдонимы

Вы можете добавить Bash-псевдонимы в виртуальную машину Homestead, изменив файл aliases в директории Homestead:

alias c='clear'
alias ..='cd ..'

После обновления файла aliases выполните повторное применение конфигурации виртуальной машины командой vagrant reload --provision. Это обеспечит доступность новых псевдонимов на машине.

#Обновление Homestead

Перед обновлением Homestead убедитесь, что текущая виртуальная машина удалена, выполнив следующую команду в директории Homestead:

vagrant destroy

Далее обновите исходный код Homestead. Если вы клонировали репозиторий, выполните следующие команды в каталоге с клоном:

git fetch

git pull origin release

Эти команды загрузят последний код Homestead с GitHub, получат последние теги и переключатся на последнюю стабильную версию. Последнюю стабильную версию можно найти на странице релизов Homestead на GitHub.

Если вы установили Homestead через файл composer.json вашего проекта, убедитесь, что в вашем composer.json указано "laravel/homestead": "^12" и обновите зависимости:

composer update

Далее обновите Vagrant box командой vagrant box update:

vagrant box update

После обновления Vagrant box выполните команду bash init.sh из директории Homestead для обновления дополнительных конфигурационных файлов Homestead. Вас спросят, хотите ли вы перезаписать существующие файлы Homestead.yaml, after.sh и aliases:

# macOS / Linux...
bash init.sh

# Windows...
init.bat

Наконец, необходимо пересоздать виртуальную машину Homestead, чтобы использовать последнюю версию Vagrant:

vagrant up

#Ежедневное использование

#Подключение по SSH

Вы можете подключиться к виртуальной машине по SSH, выполнив команду vagrant ssh из директории Homestead.

#Добавление дополнительных сайтов

После настройки и запуска окружения Homestead вы можете добавить дополнительные сайты Nginx для других Laravel-проектов. Вы можете запускать сколько угодно проектов на одном Homestead. Чтобы добавить сайт, внесите его в файл Homestead.yaml.

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
    - map: another.test
      to: /home/vagrant/project2/public

Если Vagrant не управляет автоматически файлом «hosts», возможно, потребуется добавить новый сайт в этот файл вручную. В macOS и Linux файл находится по пути /etc/hosts. В Windows — C:\Windows\System32\drivers\etc\hosts:

192.168.56.56  homestead.test
192.168.56.56  another.test

После добавления сайта выполните команду vagrant reload --provision из директории Homestead.

#Типы сайтов

Homestead поддерживает несколько «типов» сайтов, что позволяет легко запускать проекты, не основанные на Laravel. Например, можно добавить приложение Statamic, используя тип сайта statamic:

sites:
    - map: statamic.test
      to: /home/vagrant/my-symfony-project/web
      type: "statamic"

Доступные типы сайтов: apache, apache-proxy, apigility, expressive, laravel (по умолчанию), proxy (для nginx), silverstripe, statamic, symfony2, symfony4 и zf.

#Параметры сайта

Вы можете добавить дополнительные значения fastcgi_param для Nginx через директиву params в настройках сайта:

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
      params:
          - key: FOO
            value: BAR

#Переменные окружения

Вы можете определить глобальные переменные окружения, добавив их в файл Homestead.yaml:

variables:
    - key: APP_ENV
      value: local
    - key: FOO
      value: bar

После обновления файла Homestead.yaml обязательно выполните повторное применение конфигурации командой vagrant reload --provision. Это обновит конфигурацию PHP-FPM для всех установленных версий PHP и переменные окружения для пользователя vagrant.

#Порты

По умолчанию следующие порты проброшены в ваше окружение Homestead:

#Проброс дополнительных портов

Если хотите, вы можете пробросить дополнительные порты на Vagrant-бокс, добавив запись конфигурации ports в файле Homestead.yaml. После обновления Homestead.yaml обязательно повторно пропровизируйте машину, выполнив команду vagrant reload --provision:

ports:
    - send: 50000
      to: 5000
    - send: 7777
      to: 777
      protocol: udp

Ниже приведён список дополнительных портов сервисов Homestead, которые вы можете пробросить с хоста на Vagrant box:

#Версии PHP

Homestead поддерживает одновременную работу нескольких версий PHP на одной виртуальной машине. Вы можете указать, какую версию PHP использовать для конкретного сайта в файле Homestead.yaml. Доступные версии PHP: "5.6", "7.0", "7.1", "7.2", "7.3", "7.4", "8.0", "8.1", "8.2" и "8.3" (по умолчанию):

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
      php: "7.1"

Внутри вашей виртуальной машины Homestead вы можете использовать любую из поддерживаемых версий PHP через CLI:

php5.6 artisan list
php7.0 artisan list
php7.1 artisan list
php7.2 artisan list
php7.3 artisan list
php7.4 artisan list
php8.0 artisan list
php8.1 artisan list
php8.2 artisan list
php8.3 artisan list

Вы можете изменить версию PHP по умолчанию для CLI, выполнив следующие команды внутри виртуальной машины Homestead:

php56
php70
php71
php72
php73
php74
php80
php81
php82
php83

#Подключение к базам данных

По умолчанию для MySQL и PostgreSQL настроена база данных homestead. Для подключения к MySQL или PostgreSQL с вашей хост-машины используйте адрес 127.0.0.1 и порт 33060 (MySQL) или 54320 (PostgreSQL). Имя пользователя и пароль для обеих баз — homestead / secret.

#Резервное копирование баз данных

Homestead может автоматически создавать резервные копии баз данных при уничтожении виртуальной машины. Для этого требуется Vagrant версии 2.1.0 или выше. Если у вас более старая версия, установите плагин vagrant-triggers. Чтобы включить автоматическое резервное копирование, добавьте в файл Homestead.yaml следующую строку:

backup: true

После настройки Homestead будет экспортировать базы данных в директории .backup/mysql_backup и .backup/postgres_backup при выполнении команды vagrant destroy. Эти директории находятся в папке установки Homestead или в корне проекта при использовании установки на проект.

#Настройка расписания Cron

Laravel предоставляет удобный способ планирования задач cron через запуск одной команды Artisan schedule:run каждую минуту. Команда schedule:run проверяет расписание задач, определённое в классе App\Console\Kernel, и запускает необходимые задачи.

Если вы хотите, чтобы команда schedule:run запускалась для сайта Homestead, установите опцию schedule в true при определении сайта:

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
      schedule: true

Задача cron для сайта будет создана в директории /etc/cron.d виртуальной машины Homestead.

#Настройка Mailpit

Mailpit позволяет перехватывать исходящую почту и просматривать её без отправки получателям. Для начала обновите файл .env вашего приложения, указав следующие настройки почты:

MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

После настройки Mailpit вы можете открыть панель управления по адресу http://localhost:8025.

#Настройка Minio

Minio — это сервер объектного хранения с API, совместимым с Amazon S3. Чтобы установить Minio, добавьте в файл Homestead.yaml следующую опцию в разделе features:

minio: true

По умолчанию Minio доступен на порту 9600. Панель управления Minio доступна по адресу http://localhost:9600. Ключ доступа по умолчанию — homestead, секретный ключ — secretkey. При работе с Minio всегда используйте регион us-east-1.

Для использования Minio необходимо изменить конфигурацию диска S3 в файле config/filesystems.php вашего приложения. Нужно добавить опцию use_path_style_endpoint и заменить ключ url на endpoint:

's3' => [
    'driver' => 's3',
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION'),
    'bucket' => env('AWS_BUCKET'),
    'endpoint' => env('AWS_URL'),
    'use_path_style_endpoint' => true,
]

Наконец, убедитесь, что в вашем файле .env указаны следующие параметры:

AWS_ACCESS_KEY_ID=homestead
AWS_SECRET_ACCESS_KEY=secretkey
AWS_DEFAULT_REGION=us-east-1
AWS_URL=http://localhost:9600

Для настройки бакетов Minio с поддержкой «S3» добавьте директиву buckets в файл Homestead.yaml. После определения бакетов выполните команду vagrant reload --provision в терминале:

buckets:
    - name: your-bucket
      policy: public
    - name: your-private-bucket
      policy: none

Поддерживаемые значения policy: none, download, upload и public.

#Laravel Dusk

Для запуска тестов Laravel Dusk в Homestead необходимо включить функцию webdriver в конфигурации Homestead:

features:
    - webdriver: true

После включения функции webdriver выполните команду vagrant reload --provision в терминале.

#Общий доступ к окружению

Иногда нужно поделиться текущей работой с коллегами или клиентом. Vagrant поддерживает это через команду vagrant share, но она не работает, если в файле Homestead.yaml настроено несколько сайтов.

Для решения этой проблемы Homestead включает собственную команду share. Чтобы начать, подключитесь по SSH к виртуальной машине Homestead через vagrant ssh и выполните команду share homestead.test. Эта команда поделится сайтом homestead.test из вашей конфигурации Homestead.yaml. Вы можете заменить homestead.test на любой другой настроенный сайт:

share homestead.test

После запуска команды появится окно Ngrok с журналом активности и публичными URL для общего доступа к сайту. Если хотите указать регион, поддомен или другие параметры Ngrok, добавьте их к команде share:

share homestead.test -region=eu -subdomain=laravel

Если нужно делиться контентом по HTTPS, используйте команду sshare вместо share.

#Отладка и профилирование

#Отладка веб-запросов с Xdebug

Homestead поддерживает пошаговую отладку с помощью Xdebug. Например, вы можете открыть страницу в браузере, и PHP подключится к вашей IDE для инспекции и изменения выполняемого кода.

По умолчанию Xdebug уже запущен и готов принимать подключения. Если нужно включить Xdebug для CLI, выполните команду sudo phpenmod xdebug внутри виртуальной машины Homestead. Затем следуйте инструкциям вашей IDE для включения отладки. Наконец, настройте браузер для запуска Xdebug с помощью расширения или bookmarklet.

#Автоматический запуск Xdebug

При отладке функциональных тестов, которые делают запросы к веб-серверу, удобнее автоматически запускать отладку, чем изменять тесты для передачи специального заголовка или cookie. Чтобы заставить Xdebug запускаться автоматически, измените файл /etc/php/7.x/fpm/conf.d/20-xdebug.ini внутри виртуальной машины Homestead, добавив следующую конфигурацию:

; If Homestead.yaml contains a different subnet for the IP address, this address may be different...
xdebug.client_host = 192.168.10.1
xdebug.mode = debug
xdebug.start_with_request = yes

#Отладка CLI-приложений

Для отладки PHP CLI-приложения используйте shell-псевдоним xphp внутри виртуальной машины Homestead:

xphp /path/to/script

#Профилирование приложений с Blackfire

Blackfire — сервис для профилирования веб-запросов и CLI-приложений. Он предоставляет интерактивный интерфейс с графами вызовов и временными диаграммами. Подходит для разработки, тестирования и продакшена без нагрузки на конечных пользователей. Кроме того, Blackfire проверяет производительность, качество и безопасность кода и настроек php.ini.

Blackfire Player — это open-source приложение для веб-краулинга, тестирования и скрапинга, которое работает совместно с Blackfire для создания сценариев профилирования.

Для включения Blackfire используйте настройку "features" в конфигурационном файле Homestead:

features:
    - blackfire:
        server_id: "server_id"
        server_token: "server_value"
        client_id: "client_id"
        client_token: "client_value"

Учётные данные сервера и клиента Blackfire требуют аккаунта Blackfire. Blackfire предлагает разные способы профилирования, включая CLI-инструмент и расширение для браузера. Подробнее смотрите в документации Blackfire.

#Сетевые интерфейсы

Свойство networks в файле Homestead.yaml настраивает сетевые интерфейсы виртуальной машины Homestead. Вы можете настроить любое количество интерфейсов:

networks:
    - type: "private_network"
      ip: "192.168.10.20"

Чтобы включить bridged интерфейс, задайте параметр bridge для сети и измените тип сети на public_network:

networks:
    - type: "public_network"
      ip: "192.168.10.20"
      bridge: "en1: Wi-Fi (AirPort)"

Чтобы включить DHCP, просто удалите опцию ip из конфигурации:

networks:
    - type: "public_network"
      bridge: "en1: Wi-Fi (AirPort)"

Чтобы изменить устройство, используемое сетью, можно добавить опцию dev в конфигурацию сети. Значение dev по умолчанию — eth0:

networks:
    - type: "public_network"
      ip: "192.168.10.20"
      bridge: "en1: Wi-Fi (AirPort)"
      dev: "enp2s0"

#Расширение Homestead

Вы можете расширять Homestead с помощью скрипта after.sh в корне директории Homestead. В этом файле можно добавить любые shell-команды для настройки и кастомизации виртуальной машины.

При кастомизации Homestead Ubuntu может спросить, хотите ли вы сохранить оригинальную конфигурацию пакета или заменить её новой. Чтобы избежать этого, используйте следующую команду при установке пакетов, чтобы не перезаписывать ранее настроенные Homestead конфигурации:

sudo apt-get -y \
    -o Dpkg::Options::="--force-confdef" \
    -o Dpkg::Options::="--force-confold" \
    install package-name

#Пользовательские настройки

При работе с Homestead в команде вы можете захотеть подстроить Homestead под свой стиль разработки. Для этого создайте файл user-customizations.sh в корне каталога Homestead (в том же каталоге, где находится файл Homestead.yaml). В этом файле можно внести любые настройки; однако файл user-customizations.sh не должен отслеживаться системой контроля версий.

#Настройки для конкретных провайдеров

#VirtualBox

#natdnshostresolver

По умолчанию Homestead включает настройку natdnshostresolver в on. Это позволяет Homestead использовать DNS-настройки вашей хостовой ОС. Если хотите изменить это поведение, добавьте в файл Homestead.yaml следующие параметры:

provider: virtualbox
natdnshostresolver: 'off'