このリポジトリはPHP Webアプリフレームワークである、LaravelのLTSバージョンである5.5の公式英文ドキュメントを日本語へ翻訳しています。
This project is maintained by okinaka
ローカル開発環境を含め、PHP開発全体を愉快なものにしようとLaravelは努力しています。Vagrantは、仮想マシンの管理と事前設定を行う、簡単でエレガントな手段を提供しています。
Laravel Homestead（入植農地、「ホームステード」）はパッケージを事前に済ませた、Laravel公式の”box”で、PHPやWebサーバ、その他のサーバソフトウェアをローカルマシンにインストールする必要なく、素晴らしい開発環境を準備できます。オペレーティングシステムでごちゃごちゃになる心配はもうありません！ Vagrant boxは完全に使い捨てできます。何かの調子が悪くなれば壊して、数分のうちにそのboxを再生成できます！
HomesteadはWindowsやMac、Linuxシステム上で実行でき、Nginx WebサーバとPHP7.2、PHP7.1、PHP7.0、PHP5.6、MySQL、PostgreSQL、Redis、Memcached、Node、他にも素晴らしいLaravelプリケーションを開発するために必要となるものすべてを含んでいます。
{note} Windowsを使用している場合は、ハードウェア仮想化(VT-x)を有効にする必要があります。通常、BIOSにより有効にできます。UEFI system上のHyper-Vを使用している場合は、VT-xへアクセスするため、さらにHyper-Vを無効にする必要があります。
Homestead環境を起動する前に、VirtualBox 5.2か、VMWare、Parallels、と共にVagrantをインストールする必要があります。全ソフトウェア共に簡単に使用できるビジュアルインストーラが、人気のあるオペレーティングシステム全部に用意されています。
VMwareプロバイダを使用するには、VMware Fusion/WorkstationとVMware Vagrantプラグインを購入する必要があります。無料ではありませんが、VMwareが提供する共有フォルダは最初からよりスピーディーです。
Parallelsプロバイダを使用するには、Parallels Vagrantプラグインをインストールする必要があります。これは無料です。
VirtualBox/VMwareとVagrantをインストールし終えたら、laravel/homestead boxをVagrantへ追加するため次のコマンドを端末で実行する必要があります。boxをダウンロードし終えるまで、接続速度にもよりますが数分かかるでしょう。
vagrant box add laravel/homestead
このコマンドが失敗する場合、Vagrantを更新する必要があります。
リポジトリをクローンするだけでHomesteadをインストールできます。自分の「ホーム」ディレクトリの中のHomesteadフォルダへリポジトリをクローンするのことは、自分のLaravel（とPHP）の全プロジェクトをホストしておくHomestead Boxを用意するのだと考えてください。
cd ~
git clone https://github.com/laravel/homestead.git Homestead
masterブランチは常に安定しているわけではないため、バージョンタグがついたHomesteadをチェックアウトすべきでしょう。最新の安定バージョンは、GitHubのリリースページで見つかります。
cd Homestead
// クローンしたいリリースバージョン
git checkout v7.0.1
Homesteadリポジトリをクローンしたら、Homestead.yaml設定ファイルを生成するために、bash init.shコマンドをHomesteadディレクトリで実行します。
// Mac / Linux...
bash init.sh
// Windows...
init.bat
Homestead.yamlファイル中のproviderキーは、Vagrantのプロバイダとして、virtualbox、vmware_fusion、vmware_workstation、parallelsのどれを使用するかを指定します。使用するプロバイダの値を指定してください。
provider: virtualbox
Homestead.yamlファイルのfoldersプロパティには、Homestead環境と共有したい全フォルダがリストされています。これらのフォルダの中のファイルが変更されると、ローカルマシンとHomestead環境との間で同期されます。必要なだけ共有フォルダを設定してください！
folders:
- map: ~/code
to: /home/vagrant/code
少数のサイトを作るだけなら、この包括的なマッピングは上手く動作します。しかし、多くのサイトが継続的に成長していくに連れ、パフォーマンスの問題が発生してきます。この問題はとても大きいファイルを含むローエンドのマシンやプロジェクトで、悲痛なほど顕著に現れます。この問題が起きたら、全プロジェクトを自身のVagrantフォルダにマップしてください。
folders:
- map: ~/code/project1
to: /home/vagrant/code/project1
- map: ~/code/project2
to: /home/vagrant/code/project2
NFSを有効にするには、同期するフォルダにフラグを指定するだけです。
folders:
- map: ~/code
to: /home/vagrant/code
type: "nfs"
{note} NFSを使用する場合は、vagrant-bindfsプラグインのインストールを考慮してください。このプラグインは、Homestead下のファイルとディレクトリのユーザー／グループパーミッションを正しく維持します。
さらに、Vagrantの同期フォルダでサポートされている任意のオプションを、optionsキーの下に列挙して渡すことができます。
folders:
- map: ~/code
to: /home/vagrant/code
type: "rsync"
options:
rsync__args: ["--verbose", "--archive", "--delete", "-zz"]
rsync__exclude: ["node_modules"]
Nginxには詳しくない？ 問題ありません。sitesプロパティでHomestead環境上のフォルダと「ドメイン」を簡単にマップできます。サイト設定のサンプルは、Homestead.yamlファイルに含まれています。これも必要に応じ、Homestead環境へサイトを好きなだけ追加してください。便利に使えるように、Homesteadは皆さんが作業する全てのLaravelプロジェクトの仮想環境を提供します。
sites:
- map: homestead.test
to: /home/vagrant/code/Laravel/public
sitesプロパティをHomestead boxのプロビジョニング後に変更した場合、仮想マシンのNginx設定を更新するため、vagrant reload --provisionを再実行する必要があります。
Nginxサイトの”domains”に追加したサイトをあなたのコンピューターのhostsファイルにも追加してください。hostsファイルはローカルドメインへのリクエストをHomestead環境へ転送してくれます。MacとLinuxでは、/etc/hostsにこのファイルがあります。Windows環境では、C:\Windows\System32\drivers\etc\hostsです。次の行のように追加してください。
192.168.10.10 homestead.test
設定するIPアドレスにはHomestead.yamlファイルの中の値を確実に指定してください。ドメインをhostsファイルへ追加したら、Webブラウザーでサイトにアクセスできます。
http://homestead.test
Homestead.yamlのリンクを編集終えたら、Homesteadディレクトリでvagrant upコマンドを実行してください。Vagrantは仮想マシンを起動し、共有フォルダとNginxサイトを自動的に設定します。
仮想マシンを破壊するには、vagrant destroy --forceコマンドを使用します。
Homesteadをグローバルにインストールし、全プロジェクトで同じHomestead Boxを共有する代わりに、Homesteadインスタンスを管理下のプロジェクトごとに設定することもできます。プロジェクトごとにHomesteadをインストールする利点は、Vagrantfileをプロジェクトに用意すれば、プロジェクトに参加している他の人達も、vagrant upだけで仕事にとりかかれることです。
Homesteadをプロジェクトに直接インストールするには、Composerを使います。
composer require laravel/homestead --dev
Homesteadがインストールできたら、VagrantfileとHomestead.yamlファイルをプロジェクトルートへ生成するためにmakeコマンドを使ってください。makeコマンドはHomestead.yamlファイルのsitesとfoldersディレクティブを自動的に設定します。
Mac / Linux:
php vendor/bin/homestead make
Windows:
vendor\bin\homestead make
次にvagrant upコマンドを端末で実行し、ブラウザでhttp://homestead.testのプロジェクトへアクセスしてください。/etc/hostsファイルにhomestead.testか、自分で選んだドメインのエントリーを追加する必要があることを忘れないでください。
MySQLの代わりにMariaDBを使用したい場合は、mariadbオプションをHomestead.yamlファイルへ追加してください。このオプションはMySQLを削除し、MariaDBをインストールします。MariaDBはMySQLとそのまま置き換えられる代用ソフトウェアですので、mysqlデータベースドライバをそのままアプリケーションで使用できます。
box: laravel/homestead
ip: "192.168.10.10"
memory: 2048
cpus: 4
provider: virtualbox
mariadb: true
Elasticsearchをインストールするには、Homestead.yamlファイルへelasticsearchオプションを追加してください。デフォルトのインストールではhomesteadと言う名前で、２GBのメモリを割り付けます。Elasticsearchには、オペレーティングシステムのメモリの半分以上を割り当てないでください。つまり、Homesteadマシンには最低４GBのメモリを確実に割り付けてください。
box: laravel/homestead
ip: "192.168.10.10"
memory: 4096
cpus: 4
provider: virtualbox
elasticsearch: true
HomesteadでBashのエイリアスを指定するには、Homesteadディレクトリにある aliases ファイルを編集します。
alias c='clear'
alias ..='cd ..'
aliasesファイルを更新した後に、vagrant reload --provisionコマンドを使い、Homesteadを再度プロヴィジョニングする必要があります。これにより新しいエイリアスを使うことができます。
MacとLinuxシステムでは、Bashプロファイルへ簡単なBash関数を追加すれば実現できます。Windowsでは、PATHに「バッチ」ファイルを追加すれば、行えます。以下のスクリプトはシステムのどこからでも、どんなVagrantコマンドでも実行できるようにし、自動的にHomesteadをインストール済みのディレクトリで実行します。
function homestead() {
( cd ~/Homestead && vagrant $* )
}
エイリアス中の~/Homesteadパスを実際のHomesteadインストール場所を示すように調整してください。関数がインストールできたら、システムのどこからでもhomestead upやhomestead sshのように実行できます。
以下の内容のhomestead.batバッチファイルを、マシン上に作成してください。
@echo off
set cwd=%cd%
set homesteadVagrant=C:\Homestead
cd /d %homesteadVagrant% && vagrant %*
cd /d %cwd%
set cwd=
set homesteadVagrant=
スクリプト例中のC:\Homesteadパスは、実際にHomesteadをインストールした場所を指すように調整してください。ファイルを作成したら、PATHへファイルの場所を追加します。これでhomestead upやhomestead sshのようなコマンドをシステムのどこからでも実行できます。
Homesteadディレクトリでvagrant ssh端末コマンドを実行すれば、仮想マシンにSSHで接続できます。
しかし、Homesteadマシンには頻繁にSSHでアクセスする必要があると思いますから、ホストマシンから素早くHomestead boxへSSH接続できるように、上記の「関数」を追加することを検討してください。
homesteadのデータベースは、初めからMySQLとPostgreSQLの両方を設定できます。更に便利なように、Laravelの.envファイルは、Laravelでこれらのデータベースが最初から利用できるように設定されています。
ホストマシンのデータベースクライアントから、MySQLかPostgreSQLデータベースへ接続するには、127.0.0.1のポート33060(MySQL)か、ポート54320(PostgreSQL)へ接続する必要があります。ユーザー名はhomestead、パスワードはsecretです。
{note} ホストマシンからデータベースへ接続するには、標準的ではないポートだけを使用してください。Laravelのデータベース設定ファイル中では、デフォルトの3306と5432ポートを使用することができます。Laravelは仮想マシンの内部で動作しているからです。
Homestead環境をプロビジョニングし、実働した後に、LaravelアプリケーションをNginxサイトへ追加したいこともあるでしょう。希望するだけのLaravelアプリケーションを一つのHomestead環境上で実行することができます。新しいサイトを追加するには、Homestead.yamlファイルへ追加するだけです。
sites:
- map: homestead.test
to: /home/vagrant/code/Laravel/public
- map: another.test
to: /home/vagrant/code/another/public
Vagrantが”hosts”ファイルを自動的に管理しない場合は、新しいサイトを追加する必要があります。
192.168.10.10 homestead.test
192.168.10.10 another.test
サイトを追加したら、vagrant reload --provisionコマンドをHomesteadディレクトリで実行します。
Laravelベースではないプロジェクトも簡単に実行できるようにするため、Homesteadは様々なタイプのサイトをサポートしています。たとえば、symfony2サイトタイプを使えば、HomesteadにSymfonyアプリケーションを簡単に追加できます。
sites:
- map: symfony2.test
to: /home/vagrant/code/Symfony/web
type: symfony2
指定できるサイトタイプはapache、laravel（デフォルト）、proxy、silverstripe、statamic、symfony2、symfony4です。
paramsサイトディレクティブを使用し、Nginxのfastcgi_param値を追加できます。例として、値にBARを持つFOOパラメータを追加してみましょう。
sites:
- map: homestead.test
to: /home/vagrant/code/Laravel/public
params:
- key: FOO
value: BAR
グローバルな環境変数は、Homestead.yamlファイルで追加指定できます。
variables:
- key: APP_ENV
value: local
- key: FOO
value: bar
Homestead.yamlを変更したら、vagrant reload --provisionを実行し、再プロビジョンするのを忘れないでください。これにより全インストール済みPHPバージョンに対するPHP-FPM設定と、vagrantユーザーの環境も更新されます。
schedule:run Artisanコマンドだけを毎分実行することにより、Cronジョブのスケジュールを簡単に行う方法をLaravelは提供しています。schedule:runコマンドはApp\Console\Kernelクラスの定義を調べ、どのジョブを実行すべきかを決定します。
Homesteadサイトでschedule:runコマンドを実行したい場合は、サイトを定義するときにscheduleオプションをtrueに設定してください。
sites:
- map: homestead.test
to: /home/vagrant/code/Laravel/public
schedule: true
こうしたサイト用のCronジョブは、仮想マシンの/etc/cron.dフォルダの中に定義されます。
Mailhogを使用すると、簡単に送信するメールを捉えることができ、受信者に実際に届けなくとも内容を調べることができます。これを使用するには、.envファイルのメール設定を以下のように更新します。
MAIL_DRIVER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
以下のポートが、Homestead環境へポートフォワードされています。
ご希望ならば追加のポートをVagrant Boxへフォワードすることもできます。プロトコルを指定することもできます。
ports:
- send: 50000
to: 5000
- send: 7777
to: 777
protocol: udp
共同作業者やクライアントと、現在作業中の内容を共有したい場合もあるでしょう。Vagrantには、vagrant shareにより、これをサポートする方法が組み込み済みです。しかし、この方法はHomestead.yamlファイルに複数サイトを設定している場合には動作しません。
この問題を解決するため、Homesteadは独自のshareコマンドを持っています。使用を開始するには、vagrant sshによりHomesteadマシンとSSH接続し、share homestead.testを実行してください。これにより、Homestead.yaml設定ファイルのhomestead.testサイトが共有されます。もちろん、homestead.testの代わりに他の設定済みサイトを指定できます。
share homestead.test
コマンド実行後、ログと共有サイトへアクセスするURLを含んだ、Ngrokスクリーンが現れます。カスタムリージョン、サブドメイン、その他のNgrok実行オプションをカスタマイズしたい場合は、shareコマンドへ追加してください。
share homestead.test -region=eu -subdomain=laravel
{note} Vagrantは本質的に安全なものではなく、
shareコマンドによりインターネット上に自分の仮想マシンを晒すことになることを覚えておいてください。
{note} この機能は、Nginx使用時のみ利用できます。
Homestead6から、同一仮想マシン上での複数PHPバージョンをサポートを開始しました。Homestead.yamlファイルで、特定のサイトでどのバージョンのPHPを使用するのかを指定できます。利用できるPHPバージョンは、”5.6”、”7.0”、”7.1”、”7.2（デフォルト）”です。
sites:
- map: homestead.test
to: /home/vagrant/code/Laravel/public
php: "5.6"
さらに、コマンドラインではサポート済みPHPバージョンをすべて利用できます。
php5.6 artisan list
php7.0 artisan list
php7.1 artisan list
php7.2 artisan list
Homestead.yamlファイルのnetworkプロパティは、Homestead環境のネットワークインターフェイスを設定します。多くのインターフェイスを必要に応じ設定可能です。
networks:
- type: "private_network"
ip: "192.168.10.20"
ブリッジインターフェイスを有効にするには、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)"
２つの簡単な手順で、Homesteadをアップデートできます。最初にvagrant box updateコマンドを使い、Vagrant boxを更新してください。
vagrant box update
次に、Homesteadのソースコードを更新する必要があります。リポジトリをクローンしている場合は、リポジトリをクローンしたもともとの場所で、git pull origin masterを単に実行するするだけです。
プロジェクトのcomposer.jsonファイルにより、Homesteadをインストールしている場合は、composer.jsonファイルに"laravel/homestead": "^6"が含まれていることを確認し、依存パッケージを更新してください。
composer update
デフォルトのHomestead設定は、natdnshostresolver設定をonにしています。これにより、HomesteadはホストのオペレーティングシステムのDNS設定を利用します。この動作をオーバーライドしたい場合は、Homestead.yamlへ以下の行を追加してください。
provider: virtualbox
natdnshostresolver: off