はじめに

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 ([https://docs.microsoft.com/en-us/windows/wsl/about] を介して) でサポートされています。

インストールとセットアップ

Laravel Sail は、新しい Laravel アプリケーションとともに自動的にインストールされるため、すぐに使用を開始できます。新しい Laravel アプリケーションを作成する方法については、オペレーティングシステムに応じた Laravel の インストールドキュメント を参照してください。インストール中に、アプリケーションがどの Sail サポートサービスと対話するかを選択するよう求められます。

既存アプリケーションへの Sail のインストール

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

  1. composer require laravel/sail --dev

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

  1. php artisan sail:install

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

  1. ./vendor/bin/sail up

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

追加サービスの追加

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

  1. php artisan sail:add

Devcontainers の使用

Devcontainer](https://code.visualstudio.com/docs/remote/containers) 内で開発したい場合は、--devcontainer オプションを sail:install コマンドに提供できます。--devcontainer オプションは、sail:install コマンドにデフォルトの .devcontainer/devcontainer.json ファイルをアプリケーションのルートに公開するよう指示します: 

  1. php artisan sail:install --devcontainer

Sail イメージの再構築

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

  1. docker compose down -v
  3. sail build --no-cache
  5. sail up

シェルエイリアスの設定

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

  1. ./vendor/bin/sail up

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

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

これが常に利用可能であることを確認するために、~/.zshrc や ~/.bashrc などのホームディレクトリ内のシェル構成ファイルにこれを追加し、その後シェルを再起動できます。

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

  1. sail up

Sail の開始と停止

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

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

  1. sail up

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

  1. sail up -d

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

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

  1. sail stop

コマンドの実行

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

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

  3. # ローカルで Artisan コマンドを実行...
  5. php artisan queue:work
  8. # Laravel Sail 内で Artisan コマンドを実行...
  10. sail artisan queue:work

PHP コマンドの実行

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

  1. sail php --version
  3. sail php script.php

Composer コマンドの実行

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

  1. sail composer require laravel/sanctum

既存アプリケーションの Composer 依存関係のインストール

チームでアプリケーションを開発している場合、Laravel アプリケーションを最初に作成したのはあなたではないかもしれません。したがって、アプリケーションの Composer 依存関係、Sail を含む、は、アプリケーションのリポジトリをローカルコンピュータにクローンした後にインストールされません。

アプリケーションのディレクトリに移動し、次のコマンドを実行することで、アプリケーションの依存関係をインストールできます。このコマンドは、PHP と Composer を含む小さな Docker コンテナを使用してアプリケーションの依存関係をインストールします: 

  1. docker run --rm \
  2.    -u "$(id -u):$(id -g)" \
  3.    -v "$(pwd):/var/www/html" \
  4.    -w /var/www/html \
  5.    laravelsail/php83-composer:latest \
  6.    composer install --ignore-platform-reqs

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

Artisan コマンドの実行

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

  1. sail artisan queue:work

Node / NPM コマンドの実行

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

  1. sail node --version
  3. sail npm run dev

必要に応じて、NPM の代わりに Yarn を使用することもできます: 

  1. sail yarn

データベースとの対話

MySQL

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

さらに、MySQL コンテナが最初に起動すると、2 つのデータベースが作成されます。最初のデータベースは、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_HOST 環境変数を redis に設定することで、アプリケーション内の Redis インスタンスに接続できます。

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

Meilisearch

Sail をインストールする際に Meilisearch サービスをインストールすることを選択した場合、アプリケーションの docker-compose.yml ファイルには、この強力な検索エンジンのエントリが含まれ、Laravel Scout と統合されています。コンテナを起動したら、アプリケーション内の Meilisearch インスタンスに接続するには、MEILISEARCH_HOST 環境変数を http://meilisearch:7700 に設定します。

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

Typesense

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

  1. TYPESENSE_HOST=typesense
  2. TYPESENSE_PORT=8108
  3. TYPESENSE_PROTOCOL=http
  4. TYPESENSE_API_KEY=xyz

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

ファイルストレージ

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

デフォルトでは、アプリケーションの filesystems 設定ファイルには、s3 ディスクのディスク設定がすでに含まれています。このディスクを使用して Amazon S3 と対話するだけでなく、関連する環境変数を変更することで、MinIO のような S3 互換のファイルストレージサービスと対話することもできます。たとえば、MinIO を使用する場合、ファイルシステム環境変数の設定は次のように定義する必要があります: 

  1. FILESYSTEM_DISK=s3
  2. AWS_ACCESS_KEY_ID=sail
  3. AWS_SECRET_ACCESS_KEY=password
  4. AWS_DEFAULT_REGION=us-east-1
  5. AWS_BUCKET=local
  6. AWS_ENDPOINT=http://minio:9000
  7. AWS_USE_PATH_STYLE_ENDPOINT=true

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

  1. AWS_URL=http://localhost:9000/local

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

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

テストの実行

Laravel は、すぐに使用できる素晴らしいテストサポートを提供しており、Sail の test コマンドを使用してアプリケーションの 機能およびユニットテスト を実行できます。Pest / PHPUnit によって受け入れられる CLI オプションは、test コマンドにも渡すことができます: 

  1. sail test
  3. sail test --group orders

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

  1. sail artisan test

デフォルトでは、Sail は専用の testing データベースを作成し、テストが現在のデータベースの状態に干渉しないようにします。デフォルトの Laravel インストールでは、Sail はテストを実行する際にこのデータベースを使用するように phpunit.xml ファイルを構成します: 

  1. <env name="DB_DATABASE" value="testing"/>

Laravel Dusk

Laravel Dusk は、表現力豊かで使いやすいブラウザ自動化およびテスト API を提供します。Sail のおかげで、ローカルコンピュータに Selenium や他のツールをインストールすることなく、これらのテストを実行できます。始めるには、アプリケーションの docker-compose.yml ファイルで Selenium サービスのコメントを外します: 

  1. selenium:
  2.    image: 'selenium/standalone-chrome'
  3.    extra_hosts:
  4.       - 'host.docker.internal:host-gateway'
  5.    volumes:
  6.         - '/dev/shm:/dev/shm'
  7.    networks:
  8.         - sail

次に、アプリケーションの docker-compose.yml ファイル内の laravel.test サービスに depends_on エントリがあることを確認します: 

  1. depends_on:
  2.     - mysql
  3.     - redis
  4.     - selenium

最後に、Sail を起動し、dusk コマンドを実行することで Dusk テストスイートを実行できます: 

  1. sail dusk

Apple Silicon での Selenium

ローカルマシンに Apple Silicon チップが含まれている場合、selenium サービスは selenium/standalone-chromium イメージを使用する必要があります: 

  1. selenium:
  2.    image: 'selenium/standalone-chromium'
  3.    extra_hosts:
  4.         - 'host.docker.internal:host-gateway'
  5.    volumes:
  6.         - '/dev/shm:/dev/shm'
  7.    networks:
  8.         - sail

メールのプレビュー

Laravel Sail のデフォルト docker-compose.yml ファイルには、Mailpit のサービスエントリが含まれています。Mailpit は、ローカル開発中にアプリケーションによって送信されたメールを傍受し、ブラウザでメールメッセージをプレビューできる便利な Web インターフェースを提供します。Sail を使用している場合、Mailpit のデフォルトホストは mailpit で、ポート 1025 で利用可能です: 

  1. MAIL_HOST=mailpit
  2. MAIL_PORT=1025
  3. MAIL_ENCRYPTION=null

Sail が実行されているとき、Mailpit Web インターフェースには http://localhost:8025 でアクセスできます。

コンテナ CLI

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

  1. sail shell
  3. sail root-shell

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

  1. sail tinker

PHP バージョン

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

  3. # PHP 8.3
  5. context: ./vendor/laravel/sail/runtimes/8.3
  8. # PHP 8.2
  10. context: ./vendor/laravel/sail/runtimes/8.2
  13. # PHP 8.1
  15. context: ./vendor/laravel/sail/runtimes/8.1
  18. # PHP 8.0
  20. context: ./vendor/laravel/sail/runtimes/8.0

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

  1. image: sail-8.2/app

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

  1. sail build --no-cache
  3. sail up

Node バージョン

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

  1. build:
  2.    args:
  3.    WWWGROUP: '${WWWGROUP}'
  4.    NODE_VERSION: '18'

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

  1. sail build --no-cache
  3. sail up

サイトの共有

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

  1. sail share

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

  1. ->withMiddleware(function (Middleware $middleware) {
  2.    $middleware->trustProxies(at: '*');
  3. })

共有サイトのサブドメインを選択したい場合は、share コマンドを実行する際に subdomain オプションを提供できます: 

  1. sail share --subdomain=my-sail-site

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

Xdebug を使用したデバッグ

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

  1. 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 が利用可能で、手動構成は必要ありません。

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

  1. networks:
  2.   custom_network:
  3.    ipam:
  4.    config:
  5.         - subnet: 172.20.0.0/16
  7. services:
  8.   laravel.test:
  9.    networks:
  10.    custom_network:
  11.    ipv4_address: 172.20.0.2

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

  1. SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"

Xdebug CLI の使用

sail debug コマンドを使用して Artisan コマンドを実行するときにデバッグセッションを開始できます: 

  3. # Xdebug なしで Artisan コマンドを実行...
  5. sail artisan migrate
  8. # Xdebug ありで Artisan コマンドを実行...
  10. sail debug migrate

Xdebug ブラウザの使用

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

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

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

カスタマイズ

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

  1. sail artisan sail:publish

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

  1. sail build --no-cache