コンテンツにスキップ
Laravel

Laravel Sail

はじめに

Laravel Sail は、LaravelのデフォルトのDocker開発環境と対話するための軽量コマンドラインインターフェースです。Sailは、PHP、MySQL、Redisを使用してLaravelアプリケーションを構築するための素晴らしい出発点を提供し、Dockerの事前知識は必要ありません。

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` ファイルをアプリケーションのルートに公開し、Dockerサービスに接続するために必要な環境変数で `.env` ファイルを変更します

php artisan sail:install

最後に、Sailを起動できます。Sailの使用方法の詳細については、このドキュメントの残りの部分を読み続けてください

./vendor/bin/sail up
exclamation

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

追加サービスの追加

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

php artisan sail:add

Devcontainerの使用

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を起動する前に、ローカルコンピューターで他のWebサーバーまたはデータベースが実行されていないことを確認する必要があります。アプリケーションの `docker-compose.yml` ファイルで定義されているすべてのDockerコンテナを起動するには、 `up` コマンドを実行する必要があります

sail up

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

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を使用してこれらのコマンドを実行する必要があります

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

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

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という名前の専用のテストデータベースであり、テストが開発データに干渉しないようにします。

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

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

MongoDB

Sailのインストール時にMongoDBサービスをインストールすることを選択した場合、アプリケーションのdocker-compose.ymlファイルには、MongoDB Atlas Localコンテナのエントリが含まれています。これは、検索インデックスなどのAtlas機能を備えたMongoDBドキュメントデータベースを提供します。このコンテナはDockerボリュームを使用するため、コンテナを停止して再起動しても、データベースに格納されたデータは保持されます。

コンテナを起動したら、アプリケーションの.envファイル内のMONGODB_URI環境変数をmongodb://mongodb:27017に設定することで、アプリケーション内からMongoDBインスタンスに接続できます。認証はデフォルトで無効になっていますが、mongodbコンテナを起動する前に、MONGODB_USERNAMEおよびMONGODB_PASSWORD環境変数を設定して認証を有効にすることができます。その後、接続文字列に認証情報を追加します。

MONGODB_USERNAME=user
MONGODB_PASSWORD=laravel
MONGODB_URI=mongodb://${MONGODB_USERNAME}:${MONGODB_PASSWORD}@mongodb:27017

MongoDBとアプリケーションをシームレスに統合するために、MongoDBが公式にメンテナンスしているパッケージをインストールできます。

ローカルマシンからアプリケーションのMongoDBデータベースに接続するには、Compassなどのグラフィカルインターフェースを使用できます。デフォルトでは、MongoDBデータベースはlocalhostのポート27017でアクセス可能です。

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ベースの管理パネルにアクセスできます。

Typesense

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

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

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

ファイルストレージ

本番環境でアプリケーションを実行しているときにAmazon S3を使用してファイルを保存する予定がある場合は、Sailのインストール時にMinIOサービスをインストールすることをお勧めします。 MinIOは、本番のS3環境に「テスト」ストレージバケットを作成することなく、Laravelの`s3`ファイルストレージドライバを使用してローカルで開発するために使用できるS3互換APIを提供します。 Sailのインストール中にMinIOをインストールすることを選択した場合、MinIO構成セクションがアプリケーションの`docker-compose.yml`ファイルに追加されます。

デフォルトでは、アプリケーションの`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を使用する場合にLaravelのFlysystem統合が適切なURLを生成するには、アプリケーションのローカルURLと一致し、URLパスにバケット名を含めるように`AWS_URL`環境変数を定義する必要があります。

AWS_URL=http://localhost:9000/local

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

exclamation

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`サービスは`selenium/standalone-chromium`イメージを使用する必要があります。

selenium:
    image: 'selenium/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の実行中は、http://localhost:8025でMailpit Webインターフェースにアクセスできます。

コンテナCLI

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

sail shell
 
sail root-shell

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

sail tinker

PHPバージョン

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

# PHP 8.4
context: ./vendor/laravel/sail/runtimes/8.4
 
# 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

さらに、アプリケーションで使用されている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
lightbulb

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

Xdebugを使ったデバッグ

Laravel SailのDocker構成には、PHPの人気のある強力なデバッガーであるXdebugのサポートが含まれています。 Xdebugを有効にするには、アプリケーションの`.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 20.10+を使用している場合、`host.docker.internal`が使用可能であり、手動構成は必要ありません。

20.10より古いDockerバージョンでは、`host.docker.internal`はLinuxではサポートされておらず、ホストIPを手動で定義する必要があります。 これを行うには、`docker-compose.yml`ファイルでカスタムネットワークを定義することにより、コンテナの静的IPを構成します。

networks:
  custom_network:
    ipam:
      config:
        - subnet: 172.20.0.0/16
 
services:
  laravel.test:
    networks:
      custom_network:
        ipv4_address: 172.20.0.2

静的IPを設定したら、アプリケーションの.envファイル内にSAIL_XDEBUG_CONFIG変数を定義します。

SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"

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ブラウザを介してアプリケーションと対話しながらアプリケーションをデバッグするには、WebブラウザからXdebugセッションを開始するためのXdebugによって提供される指示に従ってください。

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

exclamation

Laravel Sailは、アプリケーションを提供するためにartisan serveコマンドに依存しています。artisan serveコマンドは、Laravelバージョン8.53.0以降では、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コマンドを使用してアプリケーションのコンテナを再構築します。 アプリケーションイメージに一意の名前を割り当てることは、Sailを使用して単一のマシンで複数のLaravelアプリケーションを開発する場合に特に重要です。

sail build --no-cache