イントロダクション
Laravel Sail(セイル、帆、帆船)は、LaravelのデフォルトのDocker開発環境を操作するための軽量コマンドラインインターフェイスです。 Sailは、Dockerの経験がなくても、PHP、MySQL、Redisを使用してLaravelアプリケーションを構築するための優れた出発点を提供します。
Sailの本質は、docker-compose.yml
ファイルとプロジェクトのルートに保存されているsail
スクリプトです。sail
スクリプトは、docker-compose.yml
ファイルで定義されたDockerコンテナを操作するための便利なメソッドをCLIで提供します。
Laravel Sailは、macOS、Linux、Windows(WSL2を使用)に対応しています。
インストールと準備
Laravel Sailはいつも、新しいLaravelアプリケーションとともに自動的にインストールされるため、すぐ使用を開始できます。新しいLaravelアプリケーションを作成する方法については、使用しているオペレーティングシステム用のLaravelインストールドキュメントを参照してください。インストール時には、アプリケーションで操作するSailサポートサービスを選択するよう求められます。
既存アプリケーションへのSailインストール
既存のLaravelアプリケーションでSailを使うことに興味を持っている場合は、Composerパッケージマネージャを使用してSailをインストールできます。もちろん、以降の手順は、既存のローカル開発環境で、Composerの依存関係をインストールできると仮定しています。
composer require laravel/sail --dev
Sailをインストールした後は、sail:install
Artisanコマンドを実行してください。このコマンドは、Sailのdocker-compose.yml
ファイルをアプリケーションのルートへリソース公開します。
php artisan sail:install
最後に、Sailを立ち上げましょう。Sailの使い方を学び続けるには、このドキュメントの残りを続けてお読みください。
./vendor/bin/sail up
サービスの追加
既存のSailのインストールにサービスを追加したい場合は、sail:add
Artisanコマンドを実行してください。
php artisan sail:add
Devcontainerの使用
もし、Devcontainer内で開発したい場合は、--devcontainer
オプションをsail:install
コマンドで指定してください。--devcontainer
オプションは、sail:install
コマンドに、デフォルトの.devcontainer/devcontainer.json
ファイルをアプリケーションのルートにリソース公開するように指示します。
php artisan sail:install --devcontainer
シェルエイリアスの設定
デフォルトでSailコマンドは、すべての新しいLaravelアプリケーションに含まれているvendor/bin/sail
スクリプトを使用して起動します。
./vendor/bin/sail up
しかし、Sailコマンドを実行するため、vendor/bin/sail
、と繰り返しタイプする代わりに、Sailのコマンドをより簡単に実行できるようなシェルエイリアスを設定したいと思うでしょう。
alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'
これを常に利用できるようにするには、ホームディレクトリにあるシェルの設定ファイル、例えば
~/.zshrc
や ~/.bashrc
へ追加後、シェルを再起動するとよいでしょう。
シェルエイリアスを設定すると、sail
と入力するだけで、Sailコマンドを実行できます。このドキュメントの残りの例では、このエイリアスを設定済みであることを前提にしています。
sail up
Sailの開始と停止
Laravel
Sailのdocker-compose.yml
ファイルは、Laravelアプリケーションの構築を支援するために連携するさまざまなDockerコンテナを定義します。これらの各コンテナは、docker-compose.yml
ファイルのservices
設定内のエントリです。laravel.test
コンテナは、アプリケーションを提供するメインのアプリケーションコンテナです。
Sailを開始する前に、ローカルコンピューターで他のWebサーバまたはデータベースが実行されていないことを確認する必要があります。アプリケーションのdocker-compose.yml
ファイルで定義されているすべてのDockerコンテナを起動するには、up
コマンドを実行する必要があります。
sail up
すべてのDockerコンテナをバックグラウンドで起動するには、Sailを「デタッチdetached)」モードで起動します。
sail up -d
アプリケーションのコンテナが開始されると、Webブラウザ(http:// localhost)でプロジェクトにアクセスできます。
すべてのコンテナを停止するには、Control+Cキーを押してコンテナの実行を停止してください。もしくは、コンテナがバックグラウンドで実行されている場合は、stop
コマンドを使用します。
sail stop
コマンドの実行
Laravel Sailを使用する場合、アプリケーションはDockerコンテナ内で実行され、ローカルコンピューターから分離されます。さらにSailは、任意のPHPコマンド、Artisanコマンド、Composerコマンド、Node / NPMコマンドなど、アプリケーションに対してさまざまなコマンドを実行するための便利な方法も提供します。
Laravelのドキュメントを読むと、Sailを参照しないComposer、Artisan、Node/NPMコマンドの参照をよく目にするでしょう。こうした実行例は、これらのツールがローカルコンピューターにインストールされていることを前提としています。ローカルのLaravel開発環境にSailを使用している場合は、Sailを使用してこれらのコマンドを実行する必要があります。
# Artisanコマンドをローカル環境で実行
php artisan queue:work
# Laravel Sailの中でArtisanコマンドを実行
sail artisan queue:work
PHPコマンドの実行
PHPコマンドは、php
コマンドを使用して実行します。もちろん、これらのコマンドは、アプリケーション用に構成されたPHPバージョンを使用して実行されます。Laravel
Sailで利用可能なPHPバージョンの詳細については、PHPバージョンのドキュメントを参照してください。
sail php --version
sail php script.php
Composerコマンドの実行
Composerコマンドは、composer
コマンドを使用して実行します。
Laravel
Sailのアプリケーションコンテナには、Composer2.xがインストール済みです。
sail composer require laravel/sanctum
既存アプリケーションでComposer依存関係のインストール
チームでアプリケーションを開発している場合、最初にLaravelアプリケーションを作成するのは自分ではないかもしれません。そのため、アプリケーションのリポジトリをローカルコンピュータにクローンした後、Sailを含むアプリケーションのComposer依存関係は一切インストールされていません。
アプリケーションの依存関係をインストールするには、アプリケーションのディレクトリに移動し、次のコマンドを実行します。このコマンドは、PHPとComposerを含む小さなDockerコンテナを使用して、アプリケーションの依存関係をインストールします。
docker run --rm \
-u "$(id -u):$(id -g)" \
-v "$(pwd):/var/www/html" \
-w /var/www/html \
laravelsail/php81-composer:latest \
composer install --ignore-platform-reqs
laravelsail/phpXX-composer
イメージを使用する場合、アプリケーションで使用する予定のPHPと同じバージョン(74
、80
、81
)を使用する必要があります。
Artisanコマンドの実行
Laravel
Artisanコマンドは、artisan
コマンドを使用して実行します。
sail artisan queue:work
Node/NPMコマンドの実行
Nodeコマンドはnpm
コマンドを使用して実行し、NPMコマンドはnpm
コマンドを使用して実行します。
sail node --version
sail npm run dev
ご希望であれば、NPMの代わりにYarnを使用できます。
sail yarn
データベース操作
MySQL
お気づきかもしれませんが、アプリケーションのdocker-compose.yml
ファイルには、MySQLコンテナのエントリが含まれています。このコンテナはDockerボリュームを使用しているため、コンテナを停止して再起動しても、データベースに保存されているデータは保持されます。
さらに、MySQLコンテナの初回起動時に、2つのデータベースが作成されます。最初のデータベースは、環境変数DB_DATABASE
の値で命名され、ローカル開発用に使用するものです。もうひとつは、testing
という名前のテスト専用データベースで、テストが開発データに干渉しないようにするためのものです。
コンテナを起動したら、アプリケーションの.env
ファイル内のDB_HOST
環境変数をmysql
に設定することで、アプリケーション内のMySQLインスタンスに接続できます。
ローカルマシンからアプリケーションのMySQLデータベースに接続するには、TablePlusのようなグラフィカルなデータベース管理アプリケーションを使用する方が多いでしょう。デフォルトでは、MySQLデータベースへはlocalhost
の3306ポートでアクセスでき、アクセス資格情報はDB_USERNAME
とDB_PASSWORD
環境変数の値に対応します。あるいは、DB_PASSWORD
環境変数値をパスワードとして、root
ユーザーとして接続することもできます。
Redis
アプリケーションのdocker-compose.yml
ファイルには、Redisコンテナのエントリも含まれています。このコンテナはDockerボリュームを使用しているため、コンテナを停止して再起動しても、Redisデータに保存されているデータは保持されます。コンテナを起動したら、アプリケーションの.env
ファイル内のREDIS_HOST
環境変数をredis
に設定することで、アプリケーション内のRedisインスタンスに接続できます。
ローカルマシンからアプリケーションのRedisデータベースに接続するには、TablePlusなどのグラフィカルデータベース管理アプリケーションを使用できます。デフォルトでは、Redisデータベースはlocalhost
のポート6379でアクセスできます。
MeiliSearch
Sailのインストール時にMeiliSearchサービスのインストールを選択した場合、アプリケーションのdocker-compose.yml
ファイルには、Laravel Scoutとコンパチブルである、この強力な検索エンジンのエントリが含まれます。コンテナを起動したら、環境変数MEILISEARCH_HOST
にhttp://meilisearch:7700
を設定すると、アプリケーション内のMeiliSearchインスタンスに接続できます。
ローカルマシンから、Webブラウザのhttp://localhost:7700
に移動して、MeiliSearchのWebベース管理パネルへアクセスできます。
ファイルストレージ
本番環境でアプリケーションを実行する際に、Amazon
S3を使用してファイルを保存する予定であれば、Sailをインストールする際にMinIOサービスをインストールするとよいでしょう。MinIOはS3互換のAPIを提供しており、本番のS3環境で「テスト」ストレージバケットを作成せずに、Laravelのs3
ファイルストレージドライバを使ってローカルに開発するために使用できます。Sailのインストール時にMinIOのインストールを選択すると、アプリケーションのdocker-compose.yml
ファイルにMinIOの設定セクションが追加されます。
アプリケーションのデフォルトfilesystems
設定ファイルには、s3
ディスクのディスク設定がすでに含まれています。このディスクを使ってAmazon
S3と連携するだけでなく、その構成を制御する関連環境変数を変更するだけで、MinIOなどのS3互換のファイルストレージサービスと連携することができます。例えば、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
LaravelのFlysystemインテグレーションで、MinIOを使用している場合、適切なURLを生成するには、AWS_URL
環境変数を定義してアプリケーションのローカルURLと一致させ、URLパスにバケット名を含める必要があります:
AWS_URL=http://localhost:9000/local
http://localhost:8900
のMinIOコンソールからバケットを作成できます。MinIOコンソールのデフォルトユーザー名はsail
、パスワードはpassword
です。
Warning!! MinIOを使用している場合の、
temporaryUrl
メソッドによる一時保存用URL生成はサポートしていません。
テスト実行
Laravelは、はじめからすばらしいテストサポートを提供しています。Sailのtest
コマンドを使用してアプリケーションの機能と単体テストを実行できます。PHPUnitで指定できるCLIオプションはすべて、test
コマンドに渡せます。
sail test
sail test --group orders
Sailのtest
コマンドは、test
Artisanコマンドを実行するのと同じです。
sail artisan test
デフォルトでSailは、テストがデータベースの現在の状態に影響を与えないよう、専用のtesting
データベースを作成します。Laravelのデフォルトインストールは、Sailがテストを実行するときにこのデータベースを使用するように、phpunit.xml
ファイルを構成します。
<env name="DB_DATABASE" value="testing"/>
Laravel Dusk
Laravel
Duskは、表現力豊かで使いやすいブラウザ自動化およびテストのAPIを提供します。Sailのおかげで、Seleniumやその他のツールをローカルコンピューターにインストールしなくても、これらのテストを実行できます。使い始めるには、アプリケーションのdocker-compose.yml
ファイルでSeleniumサービスのコメントを解除します。
selenium:
image: 'selenium/standalone-chrome'
volumes:
- '/dev/shm:/dev/shm'
networks:
- sail
次に、アプリケーションのdocker-compose.yml
ファイルのlaravel.test
サービスにselenium
のdepends_on
エントリがあることを確認します。
depends_on:
- mysql
- redis
- selenium
最後に、Sailを起動してdusk
コマンドを実行することにより、Duskテストスイートを実行できます。
sail dusk
Apple Silicon上のSelenium
ローカルマシンに Apple Silicon
チップが搭載されている場合、selenium
サービスにはseleniarm/standalone-chromium
イメージを使用する必要があります。
selenium:
image: 'seleniarm/standalone-chromium'
volumes:
- '/dev/shm:/dev/shm'
networks:
- sail
メールのプレビュー
Laravel
Sailのデフォルトのdocker-compose.yml
ファイルは、Mailpitのサービスエントリを含んでいます。Mailpitは、ローカル開発中にアプリケーションが送信したメールを傍受し、ブラウザでメールメッセージをプレビューできるように、便利なWebインタフェースを提供します。Sailを使用している場合、Mailpitのデフォルトのホストは、mailpit
で、ポート1025経由で利用可能です。
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null
Sailが起動している場合、http://localhost:8025で、MailpitのWebインターフェイスにアクセスできます:
コンテナCLI
アプリケーションのコンテナ内でBashセッションを開始したい場合があるでしょう。shell
コマンドを使用してアプリケーションのコンテナに接続し、ファイルとインストールされているサービスを検査したり、コンテナ内で任意のシェルコマンドを実行したりできます。
sail shell
sail root-shell
新しいLaravelTinkerセッションを開始するには、tinker
コマンドを実行します。
sail tinker
PHPバージョン
Sailは現在、PHP8.2、PHP8.1、PHP8.0、PHP7.4を利用したアプリケーションの実行をサポートしています。SailのデフォルトPHPバージョンは8.2です。アプリケーションの実行に使用するPHPバージョンを変更するには、アプリケーションのdocker-compose.yml
ファイル内のlaravel.test
コンテナのbuild
定義を更新してください。
# PHP 8.2
context: ./vendor/laravel/sail/runtimes/8.2
# PHP 8.1
context: ./vendor/laravel/sail/runtimes/8.1
# PHP8.0
context: ./vendor/laravel/sail/runtimes/8.0
# PHP7.4
context: ./vendor/laravel/sail/runtimes/7.4
さらに、アプリケーションで使用するPHPのバージョンを反映するために、image
名を更新することもできます。このオプションも、アプリケーションのdocker-compose.yml
ファイルで定義されています。
image: sail-8.1/app
アプリケーションのdocker-compose.yml
ファイルを更新した後、コンテナイメージを再構築する必要があります。
sail build --no-cache
sail up
Nodeバージョン
SailはデフォルトでNode16をインストールします。イメージをビルドする際にインストールするNodeバージョンを変更するには、アプリケーションのdocker-compose.yml
ファイル中の、laravel.test
サービスのbuild.args
定義を変更してください。
build:
args:
WWWGROUP: '${WWWGROUP}'
NODE_VERSION: '14'
アプリケーションのdocker-compose.yml
ファイルを更新した後、コンテナイメージを再構築する必要があります。
sail build --no-cache
sail up
サイトの共有
同僚のためにサイトをプレビューしたり、アプリケーションとのWebhook統合をテストしたりするために、サイトを公開して共有する必要がある場合があります。サイトを共有するには、
share
コマンドを使用します。このコマンドを実行すると、アプリケーションへのアクセスに使用するランダムなlaravel-sail.site
URLが発行されます。
sail share
share
コマンドでサイトを共有するときは、TrustProxies
ミドルウェア内でアプリケーションの信頼できるプロキシを設定する必要があります。これを行わないと、url
やroute
などのURL生成ヘルパは、URL生成時に使用するべき正しいHTTPホストを決定できません。
/**
* アプリケーションで信頼するプロキシ
*
* @var array|string|null
*/
protected $proxies = '*';
共有サイトでサブドメインを選択する場合は、share
コマンドを実行するときにsubdomain
オプションを指定します。
sail share --subdomain=my-sail-site
Note:
share
コマンドは、BeyondCodeによるオープンソースのトンネリングサービスであるExposeにより提供しています。
Xdebugによるデバッグ
LaravelSailのDockerの設定には、PHP用の人気で強力なデバッガであるXdebugをサポートしています。XDebugを有効にするには、Xdebugを設定するために、アプリケーションの.env
ファイルに変数を追加する必要があります。XDebugを有効にするには、Sailを開始する前に適切なモードを設定する必要があります。
SAIL_XDEBUG_MODE=develop,debug,coverage
LinuxホストIP設定
環境変数XDEBUG_CONFIG
は、内部でclient_host=host.docker.internal
と定義されてため、XdebugはMacとWindows(WSL2)で適切に設定されます。ローカルマシンがLinuxの場合、Docker
Engine17.06.0以上とCompose1.16.0以上が動作していることを確認してください。動作していない場合は、以下のようこの環境変数を手作業で定義する必要があります。
まず、以下のコマンドを実行して、環境変数に追加する正しいホストIPアドレスを決定します。通常、<container-name>
は、アプリケーションを提供するコンテナの名前であるべきで、多くの場合、_laravel.test_1
で終わります。
docker inspect -f {{range.NetworkSettings.Networks}}{{.Gateway}}{{end}} <container-name>
正しいホストIPアドレスを取得したら、アプリケーションの.env
ファイル内でSAIL_XDEBUG_CONFIG
変数を定義する必要があります。
SAIL_XDEBUG_CONFIG="client_host=<host-ip-address>"
Xdebug CLI使用法
Artisanのコマンドを実行する際に、sail debug
コマンドを使ってデバッグセッションを開始することができます。
# Xdebugなしでartisanコマンドを実行
sail artisan migrate
# Xdebugでartisanコマンドを実行
sail debug migrate
Xdebug ブラウザ使用法
Webブラウザでアプリケーションを操作しながらデバッグするには、WebブラウザからXdebugセッションを開始するためのXdebugが提供する手順に従ってください。
PhpStormを使用している場合は、設定なしのデバッグに関するJetBrainのドキュメントを確認してください。
Warning!! Laravel Sailはアプリケーション提供を
artisan serve
に依存しています。artisan serve
コマンドは、Laravelバージョン8.53.0以降では、XDEBUG_CONFIG
とXDEBUG_MODE
変数のみを受け付けます。古いバージョンのLaravel(8.52.0以下)では、これらの変数をサポートしていないため、デバッグ接続を受け付けません。
Sailカスタマイズ
Sailは単なるDockerであるため、Sailに関するほぼすべてを自由にカスタマイズできます。Sail独自のDockerfileをリソース公開するには、sail:publish
コマンドを実行します。
sail artisan sail:publish
このコマンドを実行すると、Laravel
Sailが使用するDockerfileとその他の設定ファイルが、アプリケーションのルートディレクトリ内のdocker
ディレクトリに配置されます。Sailのインストールをカスタマイズした後、アプリケーションの
docker-compose.yml
ファイル内のアプリケーションコンテナのイメージ名を変更したいと思うことでしょう。それを行ったら、build
コマンドを使用してアプリケーションのコンテナを再構築してください。アプリケーション・イメージに一意な名前を割り当てることは、Sailを使用して1台のマシンで複数のLaravelアプリケーションを開発する場合に特に重要です。
sail build --no-cache