Laravel 10.x 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 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

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

サービスの追加

既存の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/php82-composer:latest \
    composer install --ignore-platform-reqs

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

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コンテナの初回起動時に、２つのデータベースが作成されます。最初のデータベースは、環境変数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'
    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が起動している場合、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を利用したアプリケーションの実行をサポートしています。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

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

ドキュメント章別ページ

はじめに
リリースノート アップグレードガイド 貢献ガイド
利用開始
インストール 設定 ディレクトリ構造 フロントエンド スターターキット デプロイ
構成概念
ライフサイクル サービスコンテナ サービスプロバイダ ファサード
基礎
ルーティング ミドルウェア CSRF保護 コントローラ リクエスト レスポンス ビュー Bladeテンプレート アセットの構築 URL生成 セッション バリデーション エラー処理 ログ
より深く知る
Artisanコンソール ブロードキャスト キャッシュ コレクション 契約 イベント ファイルストレージ ヘルパ HTTPクライアント 多言語化 メール 通知 パッケージ開発 プロセス キュー レート制限 文字列 タスクスケジュール
安全
認証 認可 メール確認 暗号化 ハッシュ パスワードリセット
データベース
準備 クエリビルダ ペジネーション マイグレーション シーディング Redis
Eloquent ORM
Eloquentの準備 リレーション コレクション ミューテタ／キャスタ APIリソース シリアライズ ファクトリ
テスト
テストの準備 HTTPテスト コンソールテスト ブラウザテスト データベーステスト モック
パッケージ
Breeze Cashier (Stripe) Cashier (Paddle) Dusk Envoy Fortify Folio Homestead Horizon Jetstream Mix Octane Passport Pennant Pint Precognition Prompts Sail Sanctum Scout Socialite Telescope Valet
API
APIドキュメント

ヘッダー項目移動

注目：アイコン：ページ内リンク設置（リンクがないヘッダーへの移動では、リンクがある以前のヘッダーのハッシュをURLへ付加します。

移動

クリックで即時移動します。

リンク
サイトホーム ページ上部へ
言語
バージョン
10.x 9.x 8.x 7.x 6.x LTS 5.8 5.7 5.6 5.5 LTS 5.4 5.3 5.2 5.1 LTS 5.0 5.dev 4.2

設定

適用ボタンクリック後に、全項目まとめて適用されます。

カラーテーマ
和文指定 Pagination
和文指定 Scaffold
Largeスクリーン表示幅
インデント
本文フォント
コードフォント
フォント適用確認

フォントの指定フィールドから、フォーカスが外れると、当ブロックの内容に反映されます。EnglishのDisplayもPreviewしてください。

フォント設定時、表示に不具合が出た場合、当サイトのクッキーを削除してください。

バックスラッシュを含むインライン\Code\Blockの例です。

以下はコードブロックの例です。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * ユーザに関連する電話レコードを取得
     */
    public function phone()
    {
        return $this->hasOne('App\Phone');
    }
}

設定を保存する前に、表示が乱れないか必ず確認してください。CSSによるフォントファミリー指定の知識がない場合は、フォントを変更しないほうが良いでしょう。

キーボード・ショートカット

オープン操作

P／D／C

ページ（章）移動の左オフキャンバスオープン

H／A

ヘッダー移動モーダルオープン

M／S

移動／設定の右オフキャンバスオープン

ヘッダー移動

T

最初のヘッダーへ移動

E

最後のヘッダーへ移動

N／J

次ヘッダー(H2〜H4)へ移動

B／K

前ヘッダー(H2〜H4)へ移動

その他

?

このヘルプページ表示
閉じる