🎉

Laravel Starter Kit はどう生成されているのか — Maestro contribution 実践編

2026/05/15に公開

Laravel

laravel13

tech

前回、phpstan/larastanでエラーを検出したものがある

例えばこれ

これはreact-starter-kitのエラーであった。実際にgithubには21 variantsのgithubリポジトリーとbranchがある。たとえば

https://github.com/laravel/react-starter-kit

であれば

react-starter-kitのブランチリスト

teams
workos
workos-teams

のようなbranchもかかえている。さらには

https://github.com/laravel/blank-react-starter-kit

blank_がprefixに付くものが別にあるというので、これらを管理しているのがlaravel/maestroであった。

ここで前回larastanを使い検出していたのはreact-starter-kitのmainブランチだけであった。他のvariantもそれぞれlarastanには結構ひっかかる事を確認しているため、これは「larastanした方がいいよ、Levelをどこにあわせるかはお任せるすけど」的なissueを立てる事を方針とする、とした。

PRするもの

ここまでが戦略であり、ここからは実戦である。なお、ここでPRを仕掛けるのは事前に検知していた比較的重大めのエラーで、これはreact-starter-kitのworkosブランチで作業する。ここではmaestroによりビルドされた成果物でまず確認してみることにした。

git clone -b workos https://github.com/laravel/react-starter-kit.git react-starter-kit-workos

このようにreact-starter-kitのworkosブランチをreact-starter-kit-workos/ に持ってきたので、そこでcdし、環境をととのえるのであるが、今回は単純にlarastanするだけなので環境構築はそこそこでよいだろう。

cd react-starter-kit-workos
composer require --dev larastan/larastan

ここで以下のphpstan.neonをproject rootに配置する

phpstan.neon

includes:
    - vendor/larastan/larastan/extension.neon

parameters:
    paths:
        - app
        - routes
        - bootstrap/app.php

    level: 5

    tmpDir: storage/framework/cache/phpstan

実際にここからphpstanを仕掛ける。設定ではlevelを5としたが、実際にはコマンドラインで指定することにした。まずLevel 0である

% ./vendor/bin/phpstan --level=0
Note: Using configuration file /opt/home-admin/react-starter-kit-workos/phpstan.neon.
 13/13 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 ------ ------------------------------------------------------------------------------------
  Line   app/Http/Requests/Settings/TwoFactorAuthenticationRequest.php
 ------ ------------------------------------------------------------------------------------
  11     Class App\Http\Requests\Settings\TwoFactorAuthenticationRequest uses unknown trait
         Laravel\Fortify\InteractsWithTwoFactorState.
         🪪  trait.notFound (non-ignorable)
         💡  Learn more at https://phpstan.org/user-guide/discovering-symbols
 ------ ------------------------------------------------------------------------------------



 [ERROR] Found 1 error

ここでLevel 0すら通らないというのは重大なエラーであり、当該を見ることにする

ここで use InteractsWithTwoFactorState; しているものの、この環境ではFortifyが含まれていない、かつ2FAの機能が削除されているため、浮いてしまっている。したがって削除してよいと判断できる。

% git status
On branch workos
Your branch is up to date with 'origin/workos'.

Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        deleted:    app/Http/Requests/Settings/TwoFactorAuthenticationRequest.php

ここまでが生成物での作業である。ただし、これをreact-starter-kitのリポジトリーにはもうPRできないため、maestroを用意する

これをlaravel/maestroで表現する

まず、laravel/maestroをcloneする

git clone https://github.com/laravel/maestro.git

README.mdのInitial Setupに従い、実行する

cd orchestrator
composer install
npm install

さらにREADMEに従い php artisan buildするのであるが、ここで何も付けないとインラクティブモードになる。ここでは既にvariantが決まっているので、そのvariantでbuildをする

# react kitの workos variantで `build`
php artisan build --kit=react --workos

実行結果

% php artisan build --kit=react --workos

 Building React (WorkOS) starter kit...

 Copying Shared Blank files...

 Copying Inertia Blank Base kit files...

 Copying Inertia Blank React kit files...

 Copying Shared Base files...

 Copying Inertia Base kit files...

 Copying Inertia React kit files...

 Copying Shared WorkOS files...

 Copying Inertia WorkOS Base files...

 Copying Inertia WorkOS React files...

 Replacing component placeholders...

 Replacing variant placeholders...

 React (WorkOS) starter kit built successfully in the 'build' folder.

 Run 'composer kit:run' to start the development server.

ここで重要なのは ../build/ ディレクトリが生成されたことである。

% ls ../build
app        components.json  database          phpunit.xml          public     routes   tsconfig.json
artisan    composer.json    eslint.config.js  pint.json            README.md  storage  vite.config.ts
bootstrap  config           package.json      pnpm-workspace.yaml  resources  tests

ただし、これを起動するには orchestrator/ のディレクトリから

composer kit:run

するという仕様だ。

ここで http://localhost:8000 で「対象の」starter kitが起動する

laravel/maestroにより起動されたstarter kit。workosバージョンにつきRegisterは外れている

maestroのディレクトリーについて

以下のようなディレクトリーが構成される

.
├── browser_tests
├── build
├── kits
└── orchestrator

このディレクトリのうち、実際の修正は ../build/ 内で行う。したがって

cd ../build

しておく。

 maestro ディレクトリ構造まとめ
 kits/スターターキットのソース。継承レイヤー構造になっていて、ここだけがgit管理の対象。編集・コミットはここ。

 orchestrator/kits/ からスターターキットを生成する Laravel アプリ。
php artisan build でレイヤーを合成して build/ を作る。
composer kit:run でビルド＋ウォッチャーを起動する。

 build/orchestrator/ が生成した完成品（.gitignore対象）。
composer kit:run が動いている間は build/ を編集すると kits/ に自動同期される。
開発中の作業場所。

 browser_tests/全キット共通の E2E テスト（Playwright / Pest）。
composer kits:browser-tests 実行時に build/ にコピーされて使われる。

kits/ が原本

build/ が試し書き用の生成物(commitしない)

orchestrator/  がその変換エンジン

browser_tests/ がテストスイート
作業の流れは

build/ を編集
ウォッチャーが kits/ の適切なレイヤーに自動同期

kits/ に差分が積まれる
kits/ をコミット

phpstanのエラーを再現する

laravel/maestroにはphpstan/larastanが「一切含まれていない」ので、build/ でこれらをinstallし、前の現象を再現する。

ここでは前の手順と同様 larastan/larastan をcomposer installして確認すればよい。

composer require --dev larastan/larastan

前と同じneonを配置すれば確認できる

% ./vendor/bin/phpstan --level=0
Note: Using configuration file /opt/home-admin/maestro/build/phpstan.neon.
 13/13 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 ------ ------------------------------------------------------------------------------------
  Line   app/Http/Requests/Settings/TwoFactorAuthenticationRequest.php
 ------ ------------------------------------------------------------------------------------
  11     Class App\Http\Requests\Settings\TwoFactorAuthenticationRequest uses unknown trait
         Laravel\Fortify\InteractsWithTwoFactorState.
         🪪  trait.notFound (non-ignorable)
         💡  Learn more at https://phpstan.org/user-guide/discovering-symbols
 ------ ------------------------------------------------------------------------------------



 [ERROR] Found 1 error

修正をしていないため、当然エラーは消えない

maestro流に揃える

ここからはmaestroの流儀なので説明が難しいのだが要点だけ話す。

ここで kits/Inertia/Base/ を見ると TwoFactorAuthenticationRequest.php が存在し、「全てのバリアントに配布される」状態であった。実際にはこれはFortify関連につき
kits/Inertia/Fortify/Base/ に移動されるべきのであった。

対策としてはシンプルにファイルを Inertia/Base/ から Inertia/Fortify/Base/ へ移動するだけ。SecurityController と同じレイヤーに揃えることで、Fortify ビルドのみに含まれるようになる。

つまり、変更はたったこれだけ。

% git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        renamed:    kits/Inertia/Base/app/Http/Requests/Settings/TwoFactorAuthenticationRequest.php -> kits/Inertia/Fortify/Base/app/Http/Requests/Settings/TwoFactorAuthenticationRequest.php

PRする、が

問題はこれを直すだけに留まらず、phpstan/larastanでまともに検査されていない体質である。前回検証したものに関しても実際にはphpstan/larastanで簡単に検証できるため、これをやった方がいいよ、でも、どういう仕組みでやって、どうCIして、どのレベルで仕掛けるかはリポジトリーのメンテの中核に居ないからPRするのもアレなのでissueとさせていただきますよ、ってことでまずissueを立てる事にする。

作成されたissue

作成されたPR