{{TOC}}

{{DOCVER 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11}}

== Введение ==
Laravel стремится преобразить процесс разработки на PHP, это относится и к локальной среде разработки. ((https://www.vagrantup.com Vagrant)) обеспечивает простой, элегантный способ настройки и управления виртуальными машинами.

Laravel Homestead - официальная предустановленная Vagrant-"коробка", которая предоставляет вам замечательную среду разработки без необходимости установки PHP, веб-сервера и любого другого серверного программного обеспечения на ваш компьютер. Можно больше не беспокоиться о том, что ваша операционная система засоряется! Vagrant-коробки очень удобны. Если что-то пошло не так, вы можете уничтожить и пересоздать коробку в считанные минуты!

Homestead запускается на ОС Windows, Mac и Linux, и включает в себя веб-сервер Nginx, PHP 7.1, MySQL, Postgres, Redis, Memcached, Node и все другие полезные штуки, которые вам понадобятся для разработки удивительных Laravel-приложений.

.(alert)
Если вы используете Windows, возможно, вам необходимо включить аппаратную виртуализацию (VT-x). Она обычно включается через BIOS. Если вы используете Hyper-V на UEFI-системе, вам может понадобиться отключить Hyper-V, для доступа к VT-x.

=== Включённое ПО ===
  - Ubuntu 16.04
  - Git (в 5.1+)
  - PHP 7.1
  - HHVM (только в 5.2 и ранее)
  - Nginx
  - MySQL
  - MariaDB (в 5.1+)
  - Sqlite3 (в 5.1+)
  - Postgres
  - Composer (в 5.1+)
  - Node (с Yarn (в 5.3+), PM2, Bower, Grunt и Gulp)
  - Redis
  - Memcached
  - Beanstalkd
  - ((/docs/v5/envoy Laravel Envoy)) (в 5.0)
  - ((#профайлер Профайлер Blackfire)) (в 5.0)

== Установка и настройка ==
=== Первые шаги ===
Прежде чем запустить Homestead-среду, вы должны установить ((https://www.virtualbox.org/wiki/Downloads VirtualBox 5.1)),
((https://www.vmware.com/ VMWare)) или ((http://www.parallels.com/products/desktop/ Parallels)) (с версии Laravel 5.3), а также ((https://www.vagrantup.com/downloads.html Vagrant)). Эти программные пакеты предоставляют простые в использовании визуальные инсталляторы для всех популярных операционных систем.

Для использования VMWare вам необходимо приобрести и VMware Fusion/Workstation, и ((https://www.vagrantup.com/vmware плагин VMware Vagrant)). Хотя он и платный, зато VMware изначально обеспечивает большую скорость работы общих папок.

Для использования провайдера Parallels вам необходимо установить ((https://github.com/Parallels/vagrant-parallels плагин Parallels Vagrant)). Он бесплатный.

**Установка Vagrant-коробки Homestead**
После установки VirtualBox/VMware и Vagrant вы должны добавить коробку %%(t)laravel/homestead%% в установленный пакет Vagrant, используя следующую команду в вашем терминале. Скачивание коробки может занять несколько минут:
%%(sh)
vagrant box add laravel/homestead
%%

Если выполнение команды завершится неудачно, проверьте, что у вас установлена свежая версия Vagrant.

**Установка Homestead**

Вы можете установить Homestead, просто клонировав репозиторий. Клонируйте репозиторий в папку %%(t)Homestead%% в тот каталог, где вы храните все свои проекты Laravel, потому что коробка Homestead станет хостом всех ваших Laravel-проектов:
%%(sh)
cd ~

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

После клонирования репозитория Homestead выполните в этой папке команду %%(sh)bash init.sh%%, чтобы создать конфигурационный файл %%(t)Homestead.yaml%%. Этот файл будет помещён в скрытый каталог %%(t)~/.homestead%%:
%%(sh)
// Mac / Linux...
bash init.sh

// Windows...
init.bat
%%

=== Настройка Homestead ===
**Настройка провайдера**

Параметр %%(t)provider%% в файле %%(t)~/.homestead/Homestead.yaml%% указывает на то, какой провайдер должен использоваться: %%(t)virtualbox%%, %%(t)vmware_fusion%% (Mac OS X) или %%(t)vmware_workstation%% (Windows) или %%(t)parallels%%. Вы можете задать тот, который предпочитаете:
%%(conf)
provider: virtualbox
%%

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

В параметре %%(t)folders%% в файле %%(t)Homestead.yaml%% перечислены все папки, которые вы хотите расшарить для вашей среды Homestead. Поскольку файлы в этих папках будут меняться, они будут синхронизироваться с вашей локальной машиной и средой Homestead. Вы можете настроить столько папок, сколько вам необходимо:
%%(conf)
folders:
  - map: ~/Code
    to: /home/vagrant/Code
%%

Для включения ((https://www.vagrantup.com/docs/synced-folders/nfs.html NFS)) просто добавьте простой ключ к вашей синхронизируемой папке:
%%(conf)
folders:
  - map: ~/Code
    to: /home/vagrant/Code
    type: "nfs"
%%

Также вы можете передавать параметры, поддерживаемые ((https://www.vagrantup.com/docs/synced-folders/basic_usage.html синхронизируемыми папками)) Vagrant, указывая их под ключом %%(t)options%%:
%%(conf)
folders:
  - map: ~/Code
    to: /home/vagrant/Code
    type: "rsync"
    options:
      rsync__args: ["--verbose", "--archive", "--delete", "-zz"]
      rsync__exclude: ["node_modules"]
%%

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

Не знакомы с Nginx? Не проблема. Параметр %%(t)sites%% позволяет легко связать "домен" с папкой в среде Homestead. Типовая конфигурация сайта включена в файл %%(t)Homestead.yaml%%. И снова вы можете добавить столько сайтов к своей среде Homestead, сколько необходимо. Homestead может служить удобной виртуальной средой для каждого проекта Laravel, над которым вы работаете:
%%(conf)
sites:
  - map: homestead.app
    to: /home/vagrant/Code/Laravel/public
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
Вы можете настроить использование ((http://hhvm.com HHVM)) для любого сайта Homestead, установив параметр %%(t)hhvm%% в значение %%(t)true%%:
%%(conf)
sites:
  - map: homestead.app
    to: /home/vagrant/Code/Laravel/public
    hhvm: true
~%%
%%

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

**Файл Hosts**

Вы должны добавить "домены" для своих Nginx-сайтов в файл %%(t)hosts%% на вашей машине. Файл %%(t)hosts%% перенаправит запросы к вашим сайтам в вашу машину Homestead. На Mac и Linux этот файл расположен в %%(t)/etc/hosts%%. На Windows он расположен в %%(t)C:\Windows\System32\drivers\etc\hosts%%. Строки, которые вы добавляете в этот файл, будут выглядеть примерно так:
%%(conf)
192.168.10.10  homestead.app
%%

Удостоверьтесь, что IP-адрес тот же, что вы установили в своём файле %%(t)~/.homestead/Homestead.yaml%%. Когда вы добавите домен в свой файл %%(t)hosts%% и запустите Vagrant-коробку, вы можете получить доступ к сайту через свой веб-браузер:
%%(t)
http://homestead.app
%%

=== Запуск Vagrant Box ===
Когда вы отредактировали %%(t)Homestead.yaml%%, выполните команду %%(sh)vagrant up%% в папке Homestead. Vagrant загрузит виртуальную машину и настроит ваши общие папки и сайты Nginx автоматически.

Чтобы уничтожить машину, вы можете использовать команду %%(sh)vagrant destroy --force%%.

Чтобы узнать, как подключиться к своей базе данных, читайте дальше!

=== Установка для проекта ===
Вместо глобальной установки Homestead и использования одной Homestead-коробки для всех ваших проектов, вы можете настроить отдельный экземпляр Homestead для каждого проекта. Установка Homestead для проекта может быть выгоднее, когда вы хотите поставлять файл %%(t)Vagrantfile%% вместе с вашим проектом, позволяя тем, кто работает над проектом, просто выполнять %%(sh)vagrant up%%.

Чтобы установить Homestead непосредственно в ваш проект, затребуйте его с помощью Composer:
%%(sh)
composer require laravel/homestead --dev
%%

Когда Homestead установлен, используйте команду %%(sh)make%% для создания %%(t)Vagrantfile%% и файла %%(t)Homestead.yaml%% в корне вашего проекта. Команда %%(sh)make%% автоматически настроит директивы %%(t)sites%% и %%(t)folders%% в файле %%(t)Homestead.yaml%%.

Mac/Linux:
%%(sh)
php vendor/bin/homestead make
%%

Windows:
%%(sh)
vendor\\bin\\homestead make
%%

Затем выполните команду %%(sh)vagrant up%% в терминале и зайдите в свой проект %%(t)http://homestead.app%% через браузер. Не забывайте, что вам по-прежнему необходимо добавить строку для %%(t)homestead.app%% (или выбранного вами домена) в файл %%(t)/etc/hosts%%.

=== Установка MariaDB ===
Если вы решили использовать MariaDB вместо MySQL, вы можете добавить параметр %%(t)mariadb%% в ваш файл %%(t)Homestead.yaml%%. Этот параметр удалит MySQL и установит MariaDB. MariaDB является полноценной заменой для MySQL, поэтому вы должны использовать тот же драйвер БД %%(t)mysql%% в настройках базы данных приложения:
%%(conf)
box: laravel/homestead
ip: "192.168.20.20"
memory: 2048
cpus: 4
provider: virtualbox
mariadb: true
%%

== Повседневное использование ==
=== Глобальный доступ к Homestead ===
Иногда вам может понадобиться выполнить %%(sh)vagrant up%% вашей Homestead-машины из любого места вашей файловой системы. 
%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
Это можно сделать, добавив простую Bash-функцию в профиль вашего Bash. Эта функция позволит вам выполнять любые команды Vagrant из любого места вашей системы, и автоматически укажет команде на ваш установленный Homestead:
%%(conf)
function homestead() {
  ( cd ~/Homestead && vagrant $* )
}
~%%

Не забудьте исправить путь %%(t)~/Homestead%% в функции на реальное расположение вашего установленного Homestead. Когда функция установлена, вы можете выполнять такие команды, как %%(sh)homestead up%% и %%(sh)homestead ssh%% из любого места вашей системы.
%%

%%(DOCNEW 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
Это можно сделать, добавив простой Bash-псевдоним в профиль вашего Bash. Этот псевдоним позволит вам выполнять любые команды Vagrant из любого места вашей системы, и автоматически укажет команде на ваш установленный Homestead:
%%(conf)
alias homestead='function __homestead() { (cd ~/Homestead && vagrant $*); unset -f __homestead; }; __homestead'
~%%

Не забудьте исправить путь %%(t)~/Homestead%% в псевдониме на реальное расположение вашего установленного Homestead. Когда псевдоним установлен, вы можете выполнять такие команды, как %%(sh)homestead up%% и %%(sh)homestead ssh%% из любого места вашей системы.
%%

%%(DOCNEW 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
Чтобы добавить псевдонимы для Bash в вашу коробку Homestead, просто добавьте их в файл %%(t)aliases%% в корень каталога %%(t)~/.homestead%%.
%%(sh)
alias vm="ssh vagrant@127.0.0.1 -p 2222"
~%%

После создания псевдонима, вы можете просто использовать команду %%(sh)vm%% для подключения к вашей Homestead-машине по SSH из любого места вашей системы.

**Настройка SSH-ключа**

Теперь отредактируйте файл %%(t)Homestead.yaml%%. В этом файле вы можете настроить путь к своему паблик-ключу SSH, а также настроить папки, которые вы хотите расшарить между вашей основной машиной и виртуальной машиной Homestead.

У вас нет SSH-ключа? На Mac и Linux вы можете создать пару SSH-ключей, используя следующую команду:
%%(sh)
ssh-keygen -t rsa -C "you@homestead"
~%%

На Windows вы можете установить ((http://git-scm.com/ Git)) и использовать %%(t)Git Bash%%, встроенную в оболочку Git, чтобы выполнить указанную выше команду. Также вы можете использовать ((http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY)) и ((http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTYgen)).

Как только вы создали SSH-ключ, задайте путь к ключу в параметре %%(t)authorize%% в вашем файле %%(t)Homestead.yaml%%.
%%

=== Подключение через SSH ===
Для подключения к своей виртуальной машине по SSH вы можете использовать команду %%(sh)vagrant ssh%% из вашего каталога %%(t)Homestead%%.

Но поскольку вам, скорее всего, потребуется часто подключаться к вашей Homestead-машине по SSH, будет удобно создать "функцию" (для версии 5.1 и ранее "псевдоним") на вашей хост-машине для быстрого подключения, как описано выше.

=== Подключение к базам данных ===
База %%(t)homestead%% изначально настроена на использование и MySQL, и Postgres. Для ещё большего удобства файл Laravel %%(t).env%% настроен на использование этой БД по умолчанию.

Чтобы подключиться к вашей базе данных MySQL или Postgres через клиент БД с вашей хост-машины, вы должны подключиться к %%(t)127.0.0.1%% через порт %%(t)33060%% (MySQL) или %%(t)54320%% (Postgres). Имя пользователя и пароль для обеих баз данных - %%(t)homestead / secret%%.

.(alert)
Вы должны использовать эти нестандартные порты, только подключаясь к базам данных с вашей главной машины. Вы будете использовать порты 3306 и 5432 в вашем конфигурационном файле базы данных Laravel, так как Laravel запущен на виртуальной машине.

=== Добавление дополнительных сайтов ===
После настройки и запуска вашей среды Homestead вы можете захотеть добавить дополнительные Nginx-сайты для своих Laravel-приложений. Вы можете запустить в одной среде Homestead столько установок Laravel, сколько захотите. Вы можете просто добавить сайты в свой файл %%(t)~/.homestead/Homestead.yaml%% и затем выполнить %%(sh)vagrant reload --provision%% (для версии 5.2 и ранее %%(sh)vagrant provision%%)) из папки %%(t)Homestead%%.

%%(DOCNEW 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
.(alert)
Этот процесс деструктивен. При запуске команды %%(sh)provision%%, ваша существующая БД будет уничтожена и создана заново.

А ещё вы можете использовать скрипт %%(sh)serve%%, который доступен в среде Homestead. Чтобы использовать скрипт %%(sh)serve%%, подключитесь по SSH к вашей среде Homestead и запустите следующую команду:
%%(sh)
serve domain.app /home/vagrant/Code/path/to/public/directory 80
~%%

.(alert)
После выполнения команды %%(sh)serve%%, не забудьте добавить новый сайт в файл %%(t)hosts%% на вашей главной машине!
%%

=== Настройка расписания Cron ===
Laravel предоставляет удобный способ для ((/docs/v5/scheduling планирования Cron-задач)) путём планирования единственной Artisan-команды %%(sh)schedule:run%% на ежеминутное выполнение. Команда %%(sh)schedule:run%% проверит запланированные задачи, определённые в классе %%(t)App\Console\Kernel%%, и определит, какие задачи необходимо выполнить.

Если вы хотите выполнить команду %%(sh)schedule:run%% для сайта Homestead, вы можете задать значение %%(t)true%% для параметра %%(t)schedule%% при определении сайта:
%%(conf)
sites:
  - map: homestead.app
    to: /home/vagrant/Code/Laravel/public
    schedule: true
%%

Cron-задача для сайта будет определена в папке %%(t)/etc/cron.d%% на виртуальной машине.

=== Порты ===
По умолчанию следующие порты переадресованы в вашу среду Homestead:
  * **SSH:** 2222 -> переадресован в 22
  * **HTTP:** 8000 -> переадресован в 80
  * **HTTPS:** 44300 -> переадресован в 443
  * **MySQL:** 33060 -> переадресован в 3306
  * **Postgres:** 54320 -> переадресован в 5432

**Добавление дополнительных портов**

Если хотите, вы можете переадресовать дополнительные порты в Vagrant-коробку, а также указать их протокол:
%%(conf)
ports:
  - send: 93000
    to: 9300
  - send: 7777
    to: 777
    protocol: udp
%%

== Сетевые интерфейсы ==
Свойство %%(t)networks%% в файле %%(t)Homestead.yaml%% настраивает сетевые интерфейсы для вашей среды Homestead. Вы можете настроить сколько угодно интерфейсов:
%%(conf)
networks:
  - type: "private_network"
    ip: "192.168.10.20"
%%

Для включения ((https://www.vagrantup.com/docs/networking/public_network.html сетевого моста)) задайте параметр %%(t)bridge%% и измените тип сети на %%(t)public_network%%:
%%(conf)
networks:
  - type: "public_network"
    ip: "192.168.10.20"
    bridge: "en1: Wi-Fi (AirPort)"
%%

Для включения ((https://www.vagrantup.com/docs/networking/public_network.html DHCP)) просто удалите параметр %%(t)ip%% из конфигурации:
%%(conf)
networks:
  - type: "public_network"
    bridge: "en1: Wi-Fi (AirPort)"
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
== Обновление Homestead ==
Для обновления Homestead надо выполнить два простых шага. Во-первых, вам надо обновить Vagrant-коробку с помощью команды %%(sh)vagrant box update%%:
%%(sh)
vagrant box update
~%%

Затем вам надо обновить исходный код Homestead. Если вы клонировали репозиторий, то можете просто выполнить %%(sh)git pull origin master%% в то место, куда вы клонировали репозиторий изначально.

Если вы установили Homestead через файл %%(t)composer.json%% вашего проекта, вам надо убедиться, что этот файл содержит строку %%(t)"laravel/homestead": "^4"%% и обновить ваши зависимости:
%%(sh)
composer update
~%%

== Старые версии ==
Вы можете легко изменить используемую в Homestead версию коробки, добавив следующую строку в ваш файл %%(t)Homestead.yaml%%:
%%(conf)
version: 0.6.0
~%%

Пример:
%%(conf)
box: laravel/homestead
version: 0.6.0
ip: "192.168.20.20"
memory: 2048
cpus: 4
provider: virtualbox
~%%

При использовании старых версий коробки Homestead вам надо проверить версию на совместимость с исходным кодом Homestead. Ниже приведена таблица поддерживаемых версий коробки с указанием того, какую версию исходного кода необходимо использовать, и какая в коробке версия PHP:
%%(hvlraw)
  <table>
   <tr>
    <th></th>
    <th>Версия Homestead</th>
    <th>Версия коробки</th>
   </tr>
   <tr><td>PHP 7.0</td><td>3.1.0</td><td>0.6.0</td></tr>
   <tr><td>PHP 7.1</td><td>4.0.0</td><td>1.0.0</td></tr>
  </table>
~%%
%%

%%(DOCNEW 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
== ((#профайлер)) Профайлер Blackfire ==
((https://blackfire.io Профайлер Blackfire)) от SensioLabs автоматически собирает данные о выполнении вашего кода, такие как использование ОЗУ, время ЦПУ и ввод/вывод диска. В Homestead легко использовать этот профайлер для ваших приложений.

Все необходимые пакеты уже установлены в коробку Homestead, вам надо просто задать ID **сервера** и его ключ в файле %%(t)Homestead.yaml%%:
%%(conf)
blackfire:
  - id: your-server-id
    token: your-server-token
    client-id: your-client-id
    client-token: your-client-token
~%%

После настройки прав доступа для Blackfire переподключите коробку с помощью команды %%(sh)vagrant provision%% из вашей папки %%(t)Homestead%%. Обязательно загляните в ((https://blackfire.io/getting-started документацию Blackfire)), чтобы узнать, как установить расширение Blackfire для вашего браузера.
%%