Laravel Sail の sail:install コマンド
カテゴリ: artisan
タイプ: command
Laravel バージョン: 12.x
PHP バージョン: 8.4
Laravel Sail は Docker ベースの軽量開発環境。sail:install はその環境をプロジェクトに導入するためのコマンドです。
php artisan sail:install [options]
ざっくりまとめ
- 役割：Sail の
docker-compose.ymlを生成し、.envを設定 - 実行タイミング：Sail を初めて使うとき、または既存プロジェクトに追加するとき
- 最小構成例
php artisan sail:install
- 実務例（MySQL, Redis, Xdebug）
php artisan sail:install --with-mysql --with-redis --with-xdebug
コマンド全体（ソース抜粋）
/**
* Sail のインストールコマンド
*
* @command sail:install
*
* @option with-redis Redis コンテナを追加（デフォルト）
* @option with-mysql MySQL コンテナを追加
* @option with-postgres PostgreSQL コンテナを追加
* @option with-mongodb MongoDB コンテナを追加
* @option with-sqlite SQLite（コンテナなし）を使用
* @option with-queue キュードライバ（Redis がデフォルト）を追加
* @option with-mailhog MailHog を追加
* @option with-xdebug PHP コンテナに Xdebug を追加
* @option with-docker 画像をビルドしてからインストール
* @option with-extensions 追加 PHP 拡張機能（カンマ区切り）
*/
このコマンドは
App\Console\Commands\SailInstall.phpに実装され、Sail パッケージのサービスプロバイダで登録されています。
オプション一覧
| オプション | 説明 | デフォルト |
|---|---|---|
--with-redis |
Redis サービスを追加 | あり |
--with-mysql |
MySQL サービスを追加 | なし |
--with-postgres |
PostgreSQL サービスを追加 | なし |
--with-mongodb |
MongoDB サービスを追加 | なし |
--with-sqlite |
SQLite（コンテナなし）を使用 | なし |
--with-mailhog |
MailHog を追加 | なし |
--with-queue |
キュードライバを追加（Redis がデフォルト） | なし |
--with-xdebug |
Xdebug を追加 | なし |
--with-docker |
画像をビルドしてからインストール | なし |
--with-extensions=ext1,ext2,... |
PHP 拡張機能を追加（例: pcov,gmp） |
なし |
--docker-compose-path=path |
Compose ファイルのパスを上書き | docker-compose.yml |
--no-interaction |
確認プロンプトをスキップ | なし |
最小構成例
# デフォルト構成（PHP + MySQL + Redis + Xdebug）
php artisan sail:install
完了後、以下でコンテナを起動します。
./vendor/bin/sail up
実務例（PostgreSQL, Redis, MailHog, Xdebug）
php artisan sail:install \
--with-postgres \
--with-redis \
--with-mailhog \
--with-xdebug
何が起こるか
- Composer が Sail をインストール（既にあれば更新）。
- docker-compose.yml が生成され、選択したサービスが記述。
.envが更新：
DB_CONNECTION=pgsqlREDIS_HOST=redisMAIL_HOST=mailhog
- Sail 画像 がビルド（
--with-dockerがデフォルトで無い場合は手動）。 ./vendor/bin/sail up -dですべてのコンテナを起動。
付随 Artisan コマンド
| コマンド | 役割 |
|---|---|
php artisan sail:build |
Docker イメージをビルド |
php artisan sail:up |
Sail サービスを起動 |
php artisan sail:down |
Sail サービスを停止 |
php artisan sail:restart |
Sail サービスを再起動 |
php artisan sail:status |
コンテナの状態表示 |
php artisan sail:remove |
Sail 設定を削除 |
php artisan sail:publish |
Sail の設定ファイルを公開 |
変更履歴
| バージョン | 変更点 |
|---|---|
| 9.0 | sail:install コマンドが初登場 |
| 12.0 | --with-extensions と --docker-compose-path の追加。破壊的変更なし |
よくある落とし穴と対処法
| 落とし穴 | 症状 | 対処 |
|---|---|---|
| Docker が起動していない | docker: command not found / コンテナ起動失敗 |
Docker Desktop / Engine をインストールし、起動。WSL 2 が必要（Windows） |
docker-compose.yml が見つからない |
Error: docker-compose.yml not found |
一度 php artisan sail:install を実行し、ファイルが生成されているか確認 |
| ポート衝突 | Failed to start service: Address already in use |
docker-compose.yml のポート設定を変更、または競合しているサービスを停止 |
| Xdebug が効かない | デバッグが行えない | Xdebug 用イメージをビルドしているか確認。Windows なら Docker Desktop を最新版に |
.env が更新されない |
DB 設定が古いまま | php artisan sail:install の後、.env が書き換わっているか確認。必要なら composer dump-autoload を実行 |
| Windows で古い Docker Desktop | Xdebug が動かない | Docker Desktop を最新版に更新し、Expose daemon on tcp://localhost:2375 を有効化 |
実務での小技
- Sail をアップデート：Laravel をアップグレードしたら
composer update laravel/sailを実行。 - ビルド時間短縮：
--no-dockerフラグを付けて Docker の起動済み環境を利用。 - Compose のカスタマイズ：インストール後に
docker-compose.ymlを自由に編集。 - Xdebug の使用：デバッグが不要なときは
--with-xdebugを外すとメモリ消費が抑えられます。 - CI/CD：CI で
sail:buildを実行し、sail:upでテスト環境を構築できます。
まとめ
php artisan sail:installは Sail の環境構築を行い、docker-compose.ymlと.envを自動で生成します。- 選択可能なオプションはデータベース（MySQL, PostgreSQL, MongoDB など）、Redis、MailHog、Xdebug など。
- インストール後は
sail:upで起動し、sail:downで停止。 - 追加の Artisan コマンドでビルド・再起動・状態確認などが簡単に行えます。
