メインコンテンツまでスキップ

Laravel Sail

はじめに​

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 アプリケーションには Laravel Sail が自動的にインストールされるため、すぐに使用を開始できます。新しい Laravel アプリケーションを作成する方法については、お使いのオペレーティングシステム向けの Laravel のインストールドキュメントを参照してください。インストール中に、アプリケーションが連携する Sail サポートされたサービスを選択するように求められます。

既存のアプリケーションに Sail をインストールする​

既存の Laravel アプリケーションで Sail を使用したい場合は、Composer パッケージマネージャを使用して Sail を簡単にインストールできます。もちろん、これらの手順は、既存のローカル開発環境が Composer 依存関係をインストールできるようになっていることを前提としています：

composer require laravel/sail --dev

Sail をインストールした後、sail:install Artisan コマンドを実行できます。このコマンドは、Sail の docker-compose.yml ファイルをアプリケーションのルートに公開し、Docker サービスに接続するために必要な環境変数を .env ファイルに変更します：

php artisan sail:install

最後に、Sail を起動できます。Sail の使用方法を引き続き学習するには、このドキュメントの残りを読み続けてください：

./vendor/bin/sail up
警告

Docker Desktop for Linux を使用している場合は、次のコマンドを実行して default Docker コンテキストを使用する必要があります：docker context use default。

追加のサービスの追加​

既存の Sail インストールに追加のサービスを追加したい場合は、sail:add Artisan コマンドを実行できます：

php artisan sail:add

Devcontainers の使用​

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

php artisan sail:install --devcontainer

Sail イメージの再構築​

時々、イメージのパッケージやソフトウェアが最新であることを確認するために、Sail イメージを完全に再構築したい場合があります。build コマンドを使用してこれを実行できます:

docker compose down -v

sail build --no-cache

sail up

シェルエイリアスの設定​

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

./vendor/bin/sail up

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

alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

これを常に利用できるようにするためには、~/.zshrc や ~/.bashrc などのホームディレクトリ内のシェル設定ファイルにこれを追加し、その後シェルを再起動してください。

シェルエイリアスが設定されたら、sail と入力するだけで Sail コマンドを実行できます。このドキュメントの残りの例では、このエイリアスが設定されていると仮定します:

sail up

Sail の起動と停止​

Laravel Sail の docker-compose.yml ファイルは、Laravel アプリケーションを構築するのに役立つさまざまな Docker コンテナを定義しています。これらのコンテナは、docker-compose.yml ファイルの services 構成内のエントリです。laravel.test コンテナは、アプリケーションを提供する主要なアプリケーションコンテナです。

Sail を起動する前に、ローカルコンピュータで他のウェブサーバーやデータベースが実行されていないことを確認してください。アプリケーションの docker-compose.yml ファイルで定義されているすべての Docker コンテナを起動するには、up コマンドを実行する必要があります:

sail up

すべての Docker コンテナをバックグラウンドで起動するには、Sail を「デタッチド」モードで起動できます:

sail up -d

アプリケーションのコンテナが起動したら、ウェブブラウザでプロジェクトにアクセスできます：http://localhost。

すべてのコンテナを停止するには、単純にコンテナの実行を停止するために Control + C を押すことができます。または、コンテナがバックグラウンドで実行されている場合は、stop コマンドを使用できます：

sail stop

コマンドの実行​

Laravel Sail を使用すると、アプリケーションは Docker コンテナ内で実行され、ローカルコンピュータから分離されます。ただし、Sail は任意の PHP コマンド、Artisan コマンド、Composer コマンド、および Node / NPM コマンドなど、さまざまなコマンドをアプリケーションに対して実行する便利な方法を提供します。

Laravel ドキュメントを読む際に、Composer、Artisan、Node / NPM コマンドについて Sail に言及されていない例がよく見られます。 これらの例は、これらのツールがローカルコンピュータにインストールされていることを前提としています。ローカルの Laravel 開発環境で Sail を使用している場合は、Sail を使用してこれらのコマンドを実行する必要があります：

# Running Artisan commands locally...
php artisan queue:work

# Running Artisan commands within Laravel Sail...
sail artisan queue:work

PHP コマンドの実行​

PHP コマンドは php コマンドを使用して実行できます。もちろん、これらのコマンドは、アプリケーションに構成された PHP バージョンを使用して実行されます。Laravel Sail で利用可能な PHP バージョンについて詳しく知りたい場合は、PHP バージョンのドキュメント を参照してください：

sail php --version

sail php script.php

Composer コマンドの実行​

Composer コマンドは composer コマンドを使用して実行できます。Laravel Sail のアプリケーションコンテナには Composer のインストールが含まれています：

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/php83-composer:latest \
    composer install --ignore-platform-reqs

laravelsail/phpXX-composer イメージを使用する場合、アプリケーションで使用するPHPのバージョン（80、81、82、または 83）と同じバージョンを使用する必要があります。

Artisanコマンドの実行​

Laravel Artisanコマンドは、artisanコマンドを使用して実行できます：

sail artisan queue:work

Node / NPMコマンドの実行​

Nodeコマンドは node コマンドを使用して実行し、NPMコマンドは npm コマンドを使用して実行できます：

sail node --version

sail npm run dev

必要であれば、NPMの代わりにYarnを使用することもできます：

sail yarn

データベースとのやり取り​

MySQL​

お気づきかもしれませんが、アプリケーションの docker-compose.yml ファイルには、MySQLコンテナのエントリが含まれています。このコンテナは、Dockerボリュームを使用して、データベースに保存されているデータがコンテナの停止および再起動時にも永続化されるようになっています。

さらに、MySQLコンテナが初めて起動すると、2つのデータベースが作成されます。1つ目のデータベースは、DB_DATABASE 環境変数の値を使用して名前が付けられ、ローカル開発用です。2つ目は、testing という名前の専用のテストデータベースであり、テストが開発データと干渉しないようにします。

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

ローカルマシンからアプリケーションのMySQLデータベースに接続するには、TablePlusなどのグラフィカルデータベース管理アプリケーションを使用できます。デフォルトでは、MySQLデータベースは localhost のポート3306でアクセス可能であり、アクセス資格情報は DB_USERNAME および DB_PASSWORD 環境変数の値に対応しています。または、root ユーザーとして接続することもでき、その際にも DB_PASSWORD 環境変数の値がパスワードとして使用されます。

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 インスタンスに接続するために、MEILISEARCH_HOST 環境変数を http://meilisearch:7700 に設定します。

ローカルマシンからは、Meilisearch の Web ベースの管理パネルには、Web ブラウザで http://localhost:7700 にアクセスすることでアクセスできます。

Typesense​

Sail をインストールする際に Typesense サービスをインストールすることを選択した場合、アプリケーションの docker-compose.yml ファイルには、この高速でオープンソースの検索エンジンが Laravel Scout とネイティブに統合されているエントリが含まれています。コンテナを起動した後は、以下の環境変数を設定することで、アプリケーション内の Typesense インスタンスに接続できます：

TYPESENSE_HOST=typesense
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=xyz

ローカルマシンからは、Typesense の API に http://localhost:8108 でアクセスできます。

ファイルストレージ​

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

MinIOを使用する際に適切なURLを生成するために、LaravelのFlysystem統合が正しいURLを生成するために、AWS_URL環境変数を定義する必要があります。これにより、アプリケーションのローカルURLとURLパスにバケット名が含まれます：

AWS_URL=http://localhost:9000/local

MinIOコンソールを使用してバケットを作成することができます。MinIOコンソールはhttp://localhost:8900で利用可能です。MinIOコンソールのデフォルトのユーザー名はsailで、デフォルトのパスワードはpasswordです。

警告

MinIOを使用する際にtemporaryUrlメソッドを介して一時的なストレージURLを生成することはサポートされていません。

テストの実行​

Laravelはボックス外で素晴らしいテストサポートを提供しており、Sailのtestコマンドを使用してアプリケーションの機能テストとユニットテストを実行することができます。Pest / 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'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    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'
    extra_hosts:
        - 'host.docker.internal:host-gateway'
    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 を実行しているときは、Mailpit の Web インターフェースに http://localhost:8025 でアクセスできます

コンテナ CLI​

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

sail shell

sail root-shell

新しいLaravel Tinkerセッションを開始するには、tinkerコマンドを実行できます：

sail tinker

PHP バージョン​

Sail は現在、PHP 8.3、8.2、8.1、または PHP 8.0 を使用してアプリケーションを提供することができます。Sail が現在使用しているデフォルトの PHP バージョンは PHP 8.3 です。アプリケーションの docker-compose.yml ファイル内の laravel.test コンテナの build 定義を更新して、アプリケーションを提供するために使用される PHP バージョンを変更することができます：

# PHP 8.3
context: ./vendor/laravel/sail/runtimes/8.3

# PHP 8.2
context: ./vendor/laravel/sail/runtimes/8.2

# PHP 8.1
context: ./vendor/laravel/sail/runtimes/8.1

# PHP 8.0
context: ./vendor/laravel/sail/runtimes/8.0

さらに、アプリケーションの docker-compose.yml ファイル内で、アプリケーションで使用されている PHP バージョンを反映するために image 名を更新することができます。このオプションもアプリケーションの docker-compose.yml ファイルで定義されています：

image: sail-8.2/app

アプリケーションの docker-compose.yml ファイルを更新した後は、コンテナイメージを再構築する必要があります：

sail build --no-cache

sail up

Node バージョン​

Sail はデフォルトで Node 20 をインストールします。イメージをビルドする際にインストールされる Node バージョンを変更するには、アプリケーションの docker-compose.yml ファイル内の laravel.test サービスの build.args 定義を更新することができます：

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '18'

アプリケーションの docker-compose.yml ファイルを更新した後は、コンテナイメージを再構築する必要があります：

sail build --no-cache

sail up

サイトの共有​

同僚にプレビューを提供するためにサイトを公開したり、アプリケーションとの Webhook 統合をテストしたりする必要がある場合があります。サイトを共有するには、shareコマンドを使用できます。このコマンドを実行すると、アプリケーションにアクセスするために使用できるランダムな laravel-sail.site URL が発行されます：

sail share

shareコマンドを使用してサイトを共有する際には、アプリケーションの bootstrap/app.php ファイル内で trustProxies ミドルウェアメソッドを使用して信頼されるプロキシを構成する必要があります。そうしないと、urlやrouteなどの URL 生成ヘルパーは、URL 生成中に使用すべき正しい HTTP ホストを判断できなくなります。```

    ->withMiddleware(function (Middleware $middleware) {
        $middleware->trustProxies(at: [
            '*',
        ]);
    })

共有サイトのサブドメインを選択する場合は、shareコマンドを実行する際にsubdomainオプションを指定できます：

sail share --subdomain=my-sail-site
注記

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

Xdebugを使用したデバッグ​

Laravel SailのDocker構成には、PHP用の人気で強力なデバッガであるXdebugがサポートされています。Xdebugを有効にするには、Sailを起動する前にアプリケーションの.envファイルにいくつかの変数を追加してXdebugを構成する必要があります。Xdebugを有効にするには、Sailを起動する前に適切なモードを設定する必要があります：

SAIL_XDEBUG_MODE=develop,debug,coverage

LinuxホストIPの構成​

内部的に、XDEBUG_CONFIG環境変数はclient_host=host.docker.internalと定義されているため、XdebugはMacおよびWindows（WSL2）用に適切に構成されます。ローカルマシンがLinuxを実行している場合は、Docker Engine 17.06.0+およびCompose 1.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コマンドを使用できます：

# Run an Artisan command without Xdebug...
sail artisan migrate

# Run an Artisan command with Xdebug...
sail debug migrate

Xdebugブラウザの使用​

Webブラウザを介してアプリケーションとやり取りしながらアプリケーションをデバッグするには、Xdebugによって提供される指示に従って、WebブラウザからXdebugセッションを開始してください。

PhpStormを使用している場合は、JetBrainsのゼロ構成デバッグに関するドキュメントを参照してください。

警告

Laravel Sailは、アプリケーションを提供するために artisan serve を使用しています。 Laravelバージョン8.53.0では、artisan serveコマンドはXDEBUG_CONFIGおよびXDEBUG_MODE変数のみを受け入れます。古いバージョンのLaravel（8.52.0およびそれ以下）はこれらの変数をサポートしておらず、デバッグ接続を受け入れません。

カスタマイズ​

Sailは単なるDockerなので、ほぼすべてをカスタマイズすることができます。 Sailの独自のDockerfileを公開するには、sail:publishコマンドを実行できます：

sail artisan sail:publish

このコマンドを実行すると、Laravel Sailが使用するDockerfileやその他の構成ファイルが、アプリケーションのルートディレクトリ内の docker ディレクトリに配置されます。 Sailのインストールをカスタマイズした後は、アプリケーションの docker-compose.yml ファイル内のアプリケーションコンテナのイメージ名を変更することができます。 その後、buildコマンドを使用してアプリケーションのコンテナを再構築してください。 1台のマシンで複数のLaravelアプリケーションを開発する場合は、特にアプリケーションイメージに一意の名前を割り当てることが重要です：

sail build --no-cache