🦁

laravelコマンドで Starter Kit を展開し、Sail で固める Laravel 開発環境構築ガイド

2025/11/13に公開

TL;DR

前提

最低限dockerは動く。dockerが動かないと前提は全部崩れるのでこの記事を参考にした開発は無理です。
ここではWSL2で書くけど汎用Linux使ってもok
システムにphpやcomposerは導入しない
Gitレポジトリをどこかに持っている人(なければ別にlocalにbare作ってもokっちゃok)

初回セットアップのゴール

composer コンテナで laravel new
Sailをインストール
Sailを起動する
PHP バージョンを本番と合わせる
- 依存関係を再構築
Pest に変換する
- テストを通す
npm run dev でvite HMR開発サーバーを起動する
ソースフォーマットを行う
Git に初期コミット
- .env.example を整備する
AI開発の準備

システムに PHP や Composer を入れずにプロジェクトを展開する方法

laravelコマンドを用意

# composerイメージからbashシェルを起動
docker run --rm -it -v "$PWD":/app -w /app composer bash

し、dockerシェルから

# composerパッケージをrequireして
composer -n global require laravel/installer &&
# 環境変数PATHをセットし
export PATH="$PATH:/tmp/vendor/bin" &&
# バージョン情報を出せるように
laravel --version

これでlaravelコマンドが使える。

インストールの為のnpmを用意

ここで composerイメージ内でnpmを使えるようにしておくと最後躓かない。この環境においては、apkによりnpmを用意する

apk update
apk add npm

すると

f238dbd71be8:/app# laravel --version
Laravel Installer 5.23.0
f238dbd71be8:/app# npm --version
11.3.0

このようにlaravelコマンドとnpmコマンドが利用できるようになる。

laravel newする

ここでは --react を付与しInertia.js + Reactでプロジェクトを開始する。プロジェクトはtestappとしている。

# react指定、phpunit指定、インストール後にnpm処理指定でlaravel newしている
laravel new --react --phpunit --npm testapp

を実行する。ここでAI Boost のインストールは No とする。Boostも後から入れられるのでここでは付与しない。なるべくクリーンな状態でプロジェクトを展開するのがよい(後から追加できるのは後にする)。ただしnpmを導入したのでこれはやらせている

ここでdockerシェルを抜けない

抜けちゃってた場合は

docker run --rm -it -v "$PWD":/app -w /app composer bash

で再度起動する。

Laravel Sailのinstall

Laravel Sailのパッケージ自体はインストール済みなので、ここでプロジェクトディレクトリにcdした後php artisan sail:installする

cd testapp/
php artisan sail:install

すると

d74192579ea2:/app/testapp# php artisan sail:install

 ┌ Which services would you like to install? ───────────────────┐
 │ › ◼ mysql                                                  ┃ │
 │   ◻ pgsql                                                  │ │
 │   ◻ mariadb                                                │ │
 │   ◻ mongodb                                                │ │
 │   ◻ redis                                                  │ │
 └────────────────────────────────────────────────── 1 selected ┘
  Use the space bar to select options.

このようにインストールするサービスを選択できる。以下はAIが書いてきたそれぞれのサービスの表説明

サービス名	用途	概要	注意点（実務的な視点）
mysql	RDBMS	最も一般的な MySQL サーバー。Laravel との相性は良い。	8.x 系はローカルと本番の差異が出やすい。Aurora/MySQL 互換を見る場合はバージョン固定が無難。
pgsql	RDBMS	PostgreSQL。最近は MySQL よりも堅牢で好まれがち。	JSONB、CTE など高機能だが、MySQL 前提コードを書いていると移行が雑になる。
mariadb	RDBMS	MySQL 互換派生。軽量でローカル用途には十分。	本番 MySQL と微妙に挙動が異なるため、安易に混在させると事故る。
mongodb	NoSQL	ドキュメント指向 DB。スキーマレス。	Laravel の純正サポートは無く、外部パッケージ依存。ORM の思想がかみ合わない。
redis	KVストア	キャッシュ、ジョブキュー、セッションに定番。高速。	パブサブやジョブ用途は良いが、永続データ用途には向かない。
valkey	KVストア	Redis 互換 OSS（Redis 7 のフォーク）。	互換は高いが完全一致ではない。最新機能は差異が出る場合がある。
memcached	KVストア	シンプルかつ高速なメモリキャッシュ。	キー長やサイズ制限が厳しめ。Redis がほぼ上位互換。
meilisearch	検索	全文検索エンジン。高速で軽量、使いやすい API。	複雑な検索要件（スコア調整など）は限界が早い。
typesense	検索	Meilisearchと同系統の高速検索。厳密な型を持つ。	合理的だが、エコシステムは Meilisearch より狭め。
minio	S3互換	S3 互換のローカルオブジェクトストレージ。	実利用は AWS S3 と挙動差が多少あるため、過信は禁物。
rustfs	ファイルストア	Rust 製の高速ファイルシステムを謳うストレージ。	正直ニッチで実務利用例は少ない。触って理解したい人向け。
mailpit	メール	開発用メールキャプチャ（Mailhog の後継扱い）。	本番メールとは違うため、メールフォーマット検証には十分だが配信挙動は別物。
rabbitmq	メッセージキュー	AMQP ベースの典型的 MQ。スケールしやすい。	Laravel 標準は Redis Queue のため、MQ 必須でない限り過剰装備になりがち。
selenium	E2Eテスト	ブラウザ自動テスト用。Dusk と併用される。	UI テストはそもそも維持コストが高い。必要な場面は限定的。
soketi	WebSocket	Pusher 互換の高速 WebSocket サーバ。	便利だが、WebSocket を本番運用する責務が増える。要件が強くないとオーバーキル。

ここでの筆者の推奨は以下の2つにチェックを付ける事である。

pgsql: 2025年の新規案件でインフラ構成が許容されるなら迷わず選択したい。
mailpit: スターターキットにパスワードリマインダーでメール送信する機能がある以上避けては通れない。メールサービスを無効にするならリマインダーを無効にしないといけない

完了すると

 ┌ Which services would you like to install? ───────────────────┐
 │ pgsql                                                        │
 │ mailpit                                                      │
 └──────────────────────────────────────────────────────────────┘



   INFO  Sail scaffolding installed successfully. You may run your Docker containers using Sail's "up" command.

➜ ./vendor/bin/sail up

   WARN  A database service was installed. Run "artisan migrate" to prepare your database:

➜ ./vendor/bin/sail artisan migrate

このように

./vendor/bin/sail up
./vendor/bin/sail artisan migrate

の2つを行うように言われる。ただしここではまだ実行しなくて良い。

この段階でdockerシェルをexitして抜ける。

とりあえずlaravelをsail経由で起動してみる

sailを使わないパターンとしてはphp artisan serveなどがあるが、その機能はここでは使わない。

まず、権限を実行ユーザーに揃える

ここで今の事項ユーザーがadminという名前だったのでここではadminに権限を揃えている

sudo chown admin:admin . -R

admin:adminの部分は各自のユーザーに適合するようにコマンドを入力すること

./vendor/bin/sailする

これは普通に起動するとシェルを占有するので別シェルを駆使する(-dオプションもあるけど、開発は大抵シェルを開きっぱなしの方がうまく行く気がする)

起動するとこのような感じでシェルが待受モードになる

もし、ポートを変更したいなら

sailは .envを参照するので、ここに書く。

# ポート8000を使いたい場合
APP_PORT=8000

ここではAPP_PORT=8000を設定し、一度sailを停止し再度./vendor/bin/sail upした

データーベースエラー

このようになったら以下のコマンドでDBを初期化する(シェルが占有されている場合はもう1つ起動するなどして対応する)

./vendor/bin/sail artisan migrate:fresh --seed

これでトップページが表示されるはずだ

トップページが正常に表示された

実際に開発に入る前にやる事(このまま開発すると問題になる点)

ここまでは一般的な手順だが、本題はここからで、このまま開発すると問題が出る点がいくつかある、まず見てみよう。

PHPのバージョンはデプロイ先サーバーのバージョンと一致しているか？

sailで導入すると基本的にはその時点での最新のPHPバージョンとなる。まずこれを確認してみよう。

$ ./vendor/bin/sail php --version
PHP 8.4.14 (cli) (built: Oct 27 2025 20:53:56) (NTS)
Copyright (c) The PHP Group
Built by Debian
Zend Engine v4.4.14, Copyright (c) Zend Technologies
    with Zend OPcache v8.4.14, Copyright (c), by Zend Technologies
    with Xdebug v3.4.5, Copyright (c) 2002-2025, by Derick Rethans

このように、ここではPHP 8.4.14が導入された。デプロイ先が8.4を許容するならこれでよいが、たとえば8.2系までしか容認しない環境もある。以下にダウングレードの手順を記す。8.4で行く人は以下のセクションは飛ばしてテストまで移動してOK。

たとえばPHP8.2に対応する

php artisan sail:install --php 8.2

でインストールする。8.4から比べると以下のdiffがあるので手修正してもok

compose.yaml

index 0a132cc..d51a796 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -1,11 +1,11 @@
 services:
     laravel.test:
         build:
-            context: './vendor/laravel/sail/runtimes/8.4'
+            context: './vendor/laravel/sail/runtimes/8.2'
             dockerfile: Dockerfile
             args:
                 WWWGROUP: '${WWWGROUP}'
-        image: 'sail-8.4/app'
+        image: 'sail-8.2/app'
         extra_hosts:
             - 'host.docker.internal:host-gateway'
         ports:

ビルドコンテキストを変更した場合は、再ビルドが必要になる。初回は比較的時間がかかる。

# dockerイメージをキャッシュ無しで再度作るコマンド
./vendor/bin/sail build --no-cache

ビルドが全て完了したら一度停止し、再度upする

./vendor/bin/sail up

これでphpのバージョンは8.2となる。以降この環境で開発をすすめれば本番と齟齬が出辛いだろう。

$ ./vendor/bin/sail php --version
PHP 8.2.29 (cli) (built: Jul  3 2025 13:08:18) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.2.29, Copyright (c) Zend Technologies
    with Zend OPcache v8.2.29, Copyright (c), by Zend Technologies
    with Xdebug v3.4.5, Copyright (c) 2002-2025, by Derick Rethans

ライブラリーの整合性を合わせる

PHP のバージョンを変更したため、まず composer.lock を削除して依存関係を再生成する。

# composer.lockファイルを消して再生成する準備をする
rm composer.lock

ここで Sail 経由 で ./vendor/bin/sail composer update を実行する

$ ./vendor/bin/sail composer update
Loading composer repositories with package information
Updating dependencies
Nothing to modify in lock file
Writing lock file
Installing dependencies from lock file (including require-dev)
Nothing to install, update or remove
Generating optimized autoload files
> Illuminate\Foundation\ComposerScripts::postAutoloadDump
> @php artisan package:discover --ansi

   INFO  Discovering packages.

  inertiajs/inertia-laravel ............................................. DONE
  laravel/fortify ....................................................... DONE
  laravel/pail .......................................................... DONE
  laravel/sail .......................................................... DONE
  laravel/tinker ........................................................ DONE
  laravel/wayfinder ..................................................... DONE
  nesbot/carbon ......................................................... DONE
  nunomaduro/collision .................................................. DONE
  nunomaduro/termwind ................................................... DONE

81 packages you are using are looking for funding.
Use the `composer fund` command to find out more!
> @php artisan vendor:publish --tag=laravel-assets --ansi --force

   INFO  No publishable resources for tag [laravel-assets].

No security vulnerability advisories found.」

このようになっていれば問題ない。インストーラーの選択でPestを入れちゃった場合はダウングレード対応が必要なのでAIに聞くなりして何とか頑張る事

テスト

Pest変換

Pest変換はこの段階で行う

./vendor/bin/sail composer require pestphp/pest pestphp/pest-plugin-drift --dev --with-all-dependencies
./vendor/bin/sail pest --init
./vendor/bin/sail pest --drift

テストを通す

とりあえず全部テストする

./vendor/bin/sail test

...
   PASS  Tests\Feature\Settings\TwoFactorAuthenticationTest
  ✓ two factor settings page can be rendered                             0.04s
  ✓ two factor settings page requires password confirmation when enable… 0.03s
  ✓ two factor settings page does not requires password confirmation wh… 0.03s
  ✓ two factor settings page returns forbidden response when two factor… 0.03s

  Tests:    41 passed (129 assertions)
  Duration: 2.69s

となればok。重要な事はテストが崩壊したままコミットしない事である。ここは何とか頑張ってテストを修正してコミットするクセを付ける事。

フロントエンド回りの調整

スターターキットによりnpm installは実行されているから一々npm installする必要はない。別のシェルで./vendor/bin/sail npm run devを実行

# viteでHMRする開発サーバーを起動
./vendor/bin/sail npm run dev

viteが起動した

このようにsailとviteがずっと起動しっぱなしというのが現在の開発環境の基本である。

開発を実行する前に

pint

laravelではpintというコードフォーマッターが付いており、基本的にそれに従うようにスターターキットのCIとかは組まれているので、実行する

./vendor/bin/pint

フロントエンドの整形とチェック

これもformatterが用意されているので順々に実行する

npm run format
npm run lint
npm run types

を動作させる。

なお、npmは以下のようにサブコマンドが定義されている

    "scripts": {
        "build": "vite build",
        "build:ssr": "vite build && vite build --ssr",
        "dev": "vite",
        "format": "prettier --write resources/",
        "format:check": "prettier --check resources/",
        "lint": "eslint . --fix",
        "types": "tsc --noEmit"
    },

git管理

ここで Git に投入してバージョン管理を開始する。

git init .
git add .
git commit -m "init"

.env.exampleの整備

ここで一度外部リポジトリーにpushして取り直すと良いのだが、sailによりセットされた .envと .env.example では違いが見られる

.env 2025-11-13 20:02:28.960941299 +0900

@@ -1,8 +1,9 @@
 APP_NAME=Laravel
 APP_ENV=local
-APP_KEY=
+APP_KEY=base64:Y4Exe7jPqXzqm9vu3GVGdcqvVFyI8qPlKCSy5x+CAhI=
 APP_DEBUG=true
-APP_URL=http://localhost
+APP_URL=http://localhost:8000
+APP_PORT=8000

 APP_LOCALE=en
 APP_FALLBACK_LOCALE=en
@@ -11,7 +12,7 @@
 APP_MAINTENANCE_DRIVER=file
 # APP_MAINTENANCE_STORE=database

-# PHP_CLI_SERVER_WORKERS=4
+PHP_CLI_SERVER_WORKERS=4

 BCRYPT_ROUNDS=12

@@ -20,12 +21,12 @@
 LOG_DEPRECATIONS_CHANNEL=null
 LOG_LEVEL=debug

-DB_CONNECTION=sqlite
-# DB_HOST=127.0.0.1
-# DB_PORT=3306
-# DB_DATABASE=laravel
-# DB_USERNAME=root
-# DB_PASSWORD=
+DB_CONNECTION=pgsql
+DB_HOST=pgsql
+DB_PORT=5432
+DB_DATABASE=laravel
+DB_USERNAME=sail
+DB_PASSWORD=password

 SESSION_DRIVER=database
 SESSION_LIFETIME=120
@@ -47,10 +48,10 @@
 REDIS_PASSWORD=null
 REDIS_PORT=6379

-MAIL_MAILER=log
+MAIL_MAILER=smtp
 MAIL_SCHEME=null
-MAIL_HOST=127.0.0.1
-MAIL_PORT=2525
+MAIL_HOST=mailpit
+MAIL_PORT=1025
 MAIL_USERNAME=null
 MAIL_PASSWORD=null
 MAIL_FROM_ADDRESS="hello@example.com"

開発するあたってこのような設定を .env.example に移動しておいた方がいいこともあるから、ここは適時取捨選択されたい

cloneして、開発環境を瞬時に用意できるように何度かやってみる事。その際にひっかかった点は必ずドキュメントするとよい。

必要ならLaravel Boostを導入

boostを入れるならこの後でやっといた方がいいです。

php artisan boost:install

Devコンテナー

これは次回