Laravel Sail 8.x Laravel

イントロダクション

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

Devcontainerの使用

もし、Devcontainer内で開発したい場合は、--devcontainerオプションをsail:installコマンドで指定してください。--devcontainerオプションは、sail:installコマンドに、デフォルトの.devcontainer/devcontainer.jsonファイルをアプリケーションのルートにリソース公開するように指示します。

php artisan sail:install --devcontainer

Bashエイリアスの設定

デフォルトでSailコマンドは、すべての新しいLaravelアプリケーションに含まれているvendor/bin/sailスクリプトを使用して起動します。

./vendor/bin/sail up

vendor/bin/sailを実行するため繰り返し入力する代わりに、Sailコマンドをより簡単に実行できるようにするBashエイリアスを設定することをおすすめします。

alias sail='[ -f sail ] && bash sail || bash vendor/bin/sail'

Bashエイリアスを設定したら、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 prod

ご希望であれば、NPMの代わりにYarnを使用できます。

sail yarn

データベース操作

MySQL

お気づきかもしれませんが、アプリケーションのdocker-compose.ymlファイルには、MySQLコンテナのエントリが含まれています。このコンテナはDockerボリュームを使用しているため、コンテナを停止して再起動しても、データベースに保存されているデータは保持されます。また、MySQLコンテナの起動時に、名前がDB_DATABASE環境変数の値と一致するデータベースが存在することを確認します。

コンテナを起動したら、アプリケーションの.envファイル内のDB_HOST環境変数をmysqlに設定することで、アプリケーション内のMySQLインスタンスに接続できます。

ローカルマシンからアプリケーションのMySQLデータベースに接続するには、TablePlusなどのグラフィカルデータベース管理アプリケーションを使用できます。デフォルトでMySQLデータベースは、localhostのポート3306からアクセスできます。

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_DRIVER=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は、はじめからすばらしいテストサポートを提供しています。Sailのtestコマンドを使用してアプリケーションの機能と単体テストを実行できます。PHPUnitで指定できるCLIオプションはすべて、testコマンドに渡せます。

sail test

sail test --group orders

Sailのtestコマンドは、test Artisanコマンドを実行するのと同じです。

sail artisan test

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

メールのプレビュー

LaravelSailのデフォルトの docker-compose.ymlファイルには、MailHogのサービスエントリが含まれています。MailHogは、ローカル開発中にアプリケーションから送信された電子メールをインターセプトし、ブラウザで電子メールメッセージをプレビューできる便利なWebインターフェイスを提供します。Sailを使う場合、MailHogのデフォルトホストはmailhogで、ポートは1025です。

MAIL_HOST=mailhog
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Sailの実行中に、http://localhost:8025でMailHog Webインターフェイスにアクセスできます。

コンテナCLI

アプリケーションのコンテナ内でBashセッションを開始したい場合があるでしょう。shellコマンドを使用してアプリケーションのコンテナに接続し、ファイルとインストールされているサービスを検査したり、コンテナ内で任意のシェルコマンドを実行したりできます。

sail shell

sail root-shell

新しいLaravelTinkerセッションを開始するには、tinkerコマンドを実行します。

sail tinker

PHPバージョン

Sailは現在、PHP8.1、PHP8.0、PHP7.4を利用したアプリケーションの実行をサポートしています。SailのデフォルトPHPバージョンは8.1です。アプリケーションの実行に使用するPHPバージョンを変更するには、アプリケーションのdocker-compose.ymlファイル内のlaravel.testコンテナーのbuild定義を更新してください。

# 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

After updating your application's docker-compose.yml file, you should rebuild your container images:

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

Tip!! shareコマンドは、BeyondCodeによるオープンソースのトンネリングサービスであるExposeにより提供しています。

Xdebugによるデバッグ

LaravelSailのDockerの設定には、PHP用の人気で強力なデバッガであるXdebugをサポートしています。XDebugを有効にするには、Xdebugを設定するために、アプリケーションの.envファイルに変数を追加する必要があります。XDebugを有効にするには、Sailを開始する前に適切なモードを設定する必要があります。

SAIL_XDEBUG_MODE=develop,debug

LinuxホストIP設定

内部的には、XDEBUG_CONFIG環境変数はclient_host=host.docker.internalとして定義しているため、XdebugはMacとWindows(WSL2)用に正しく設定します。ローカルマシンがLinuxを実行している場合は、この環境変数を手動で定義する必要があります。

まず、以下のコマンドを実行して、環境変数に追加する正しいホスト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を使用している場合は、[設定なしのデバッグ]](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html)に関するJetBrainのドキュメントを確認してください。

Note: 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

Laravel 8.x Laravel Sail