miraqceed / laravel-foundation
どの Laravel のアプリにも要る部品(テストの守り・CSV・ログインのロック・CSP・見張り)
Requires
- php: ^8.3
- ext-intl: *
- ext-mbstring: *
- laravel/framework: ^12.0|^13.0
Requires (Dev)
- brianium/paratest: ^7.0
- laravel/ai: ^1.4
- laravel/fortify: ^1.0
- nunomaduro/collision: ^8.0
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^3.0|^4.0
Suggests
- laravel/ai: AI の費用の上限と記録を使うとき
- laravel/fortify: ログインのロックを Fortify の認証と組み合わせるとき
Provides
None
Conflicts
- laravel/ai: <1.4 || >=2.0
Replaces
None
- dev-main
- v0.8.1
- v0.8.0
- v0.7.0
- v0.6.0
- v0.5.0
- v0.4.0
- v0.3.0
- v0.2.0
- v0.1.2
- v0.1.1
- v0.1.0
- dev-mail-host-safety
- dev-attempts-frozen-time
- dev-release/0.8.1
- dev-two-factor-wrong-codes
- dev-changelog-released-sections
- dev-release/0.8.0
- dev-one-time-codes
- dev-docs-trust-proxies
- dev-release/0.7.0
- dev-small-three
- dev-release/0.6.0
- dev-two-factor
- dev-release/0.5.0
- dev-attempt-limits
- dev-redaction
- dev-release/0.4.0
- dev-fix/watch-list-web
- dev-release/0.3.0
- dev-feat/stall-check
- dev-fix/security-headers-outer-responses
- dev-codex/reserved-email-domains
- dev-feat/unsigned-integer
This package is auto-updated.
Last update: 2026-11-16 23:20:27 UTC
README
どの Laravel のアプリにも要る部品を1つにまとめたパッケージです。Laravel 12〜13、PHP 8.3 以上、PostgreSQL 16 以上・MySQL 8.4・SQLite(試しのみ)に対応します。Redis や常駐のプロセスには頼らず、database のドライバーで動きます。
入れただけではアプリの挙動は変わりません。ただしテストの DB の守りだけは、入れた時点で効きます。 テストがつなぐ DB の名前に test か testing が語として入っていないと(app_test は可、latest は不可)、テストは DB に触れる前に止まります。止まったときの直し方は docs/test-safety.md にあります。
設定で有効にする部品は既定で無効です。CSV・非負整数の計算・予約メールドメインの判定と入力の検証の規則は設定なしで呼び出せます。マクロ・ミドルウェアの別名・コマンドはいつも登録され、無効なら何もしません。ミドルウェアをグループへ自動で足すことはしません。
入れ方
composer require miraqceed/laravel-foundation php artisan vendor:publish --tag=foundation-config # config/foundation.php(任意) php artisan foundation:install # AGENTS.md / CLAUDE.md に AI 向けの節を書く
入れた時点で、テストの DB の守りが効きます(上の注意)。composer require の後にテストが UnsafeTestDatabase で止まったら、テスト用 DB の名前に test か testing を入れます(docs/test-safety.md)。
foundation:install は <!-- foundation:start --> と <!-- foundation:end --> の間だけを書くので、何度流しても節は1つです。AGENTS.md・CLAUDE.md のうちあるものすべてに書き、どちらもなければ AGENTS.md を作ります。節の中身は Boost の指針と同じ原本から作ります。Laravel Boost を使うアプリでは、boost:install がこのパッケージの指針(resources/boost/guidelines/core.blade.php)を見つけ、「Which third-party AI guidelines/skills would you like to install?」の一覧に miraqceed/laravel-foundation を出します。選んだときだけ入ります(Boost の第三者の指針は選んで入れる形)。--no-interaction で流すときは、先に boost.json の packages に "miraqceed/laravel-foundation" を書いておきます。Boost の節と foundation:install の節は、同じファイルに並んでも互いを消しません。
部品
| 部品 | 既定 | 説明書 |
|---|---|---|
テストの守り:名前に test / testing の印のない DB へのテストを、DB に触れる前に止める |
常に有効 | docs/test-safety.md |
| CSV:式の守り・Shift_JIS・ずれない大きな表の読み方 | 常に使える | docs/csv.md |
| 非負整数:整数の上限を超える和・積・切り上げ・比較 | 設定なしで呼んで使う | docs/integer-math.md |
実在しないメールアドレス:example.com・.invalid などの判定・入力の検証の規則・送る前に宛先から外す差し込み |
判定と規則は設定なしで使える。差し込みは無効(foundation.mail.drop_reserved_recipients) |
docs/reserved-email-domains.md |
| 秘密を伏せる:文・入れ子の配列の中の鍵・トークン・パスワード・メールアドレス・電話番号を形で見つけて伏せる(漏れを無くすとは約束しない) | 設定なしで呼んで使う | docs/redaction.md |
| ログインのロック:メールと接続元の失敗を数える(Fortify 対応) | 使うときに組み込む | docs/login.md |
| 試みの数え:ログイン以外の照合(確認コード・合言葉・カードなど)を、照合の前に数えて止める。続けた失敗のロック | 設定なしで呼んで使う | docs/attempts.md |
| 二段階の認証:認証アプリの確認コード(TOTP)を、使い回しと同時の要求を許さずに確かめる(手書きの認証と Fortify の差し替え) | 設定なしで呼んで使う。列は写したマイグレーションで足す | docs/two-factor.md |
DB の接続の時間帯:接続の時間帯がアプリの時間帯とずれていないかを確かめる(foundation:db-timezone) |
設定なしで呼んで使う(自動では確かめない) | docs/database-timezone.md |
本番の設定の点検:APP_DEBUG・APP_KEY・メール・Vite・マイグレーション・信頼するプロキシなどを1つのコマンドで調べる(foundation:deploy-check)。アプリの調べを足せる |
流したときだけ働く(自動では流れない) | docs/deploy-check.md |
子プロセスの環境変数:外のコマンドに .env の秘密を受け継がせない環境の配列 |
設定なしで呼んで使う | docs/child-processes.md |
| 1回だけ使える合言葉:期限つき・ハッシュだけで持ち、同時の要求でも1回だけ通す(機械にトークンを受け取らせる合言葉・入場券など) | 無効(foundation.one_time_codes.enabled。表を作る) |
docs/one-time-codes.md |
| CSP・セキュリティヘッダー | 無効(foundation.security.enabled) |
docs/security.md |
稼働の確かめ:外のスクリプトを読まず、原因を出さない /up(text/plain の OK/NG)。DB の確かめを足せる |
アプリが bootstrap/app.php で Health::route('/up') に書き換えたときだけ。DB は見ない(foundation.health.checks) |
docs/health.md |
| 定期の処理の見張りと知らせ | 無効(foundation.monitoring.enabled) |
docs/monitoring.md |
| AI の費用の上限と記録(Laravel AI SDK で呼ぶ AI の1日・1か月の金額と1日の回数に上限、呼び出しごとの使用量と原価) | 無効(foundation.ai.enabled)。laravel/ai ^1.4 が要る |
docs/ai.md |
利用者が入れた URL をサーバーから開くときの守り(SSRF)は、このパッケージに入れず、別のパッケージ cboxdk/laravel-ssrf を使います。使い方と注意は docs/ssrf.md にあります。
例:schedule の外の処理を見張る
// config/foundation.php 'monitoring' => [ 'enabled' => true, 'external' => ['backup' => ['max_age_minutes' => 1560, 'label' => '日次のバックアップ']], 'alerts' => ['channels' => ['log']], ],
# 失敗も記録したうえで、台本の終了コードを残す(1行の && … || … だと終了コードがいつも 0 になる) if ./backup.sh; then php artisan foundation:record backup else status=$? php artisan foundation:record backup --failed exit "$status" fi
知らせの表(foundation_alerts・foundation_alert_deliveries)は自動では消えません。送れたか諦めて monitoring.alerts.prune_days(既定 90)日たった知らせを消すには、model:prune を schedule に入れ、パッケージのモデルを --model で指します(--model なしの model:prune は app/Models しか見ません):
// routes/console.php Schedule::command('model:prune', ['--model' => [\Miraqceed\Foundation\Monitoring\Alerts\Alert::class]])->daily();
キャッシュのストアが database なら、期限切れの行も自動では消えません(Laravel はその鍵がもう一度読まれたときにだけ消します)。foundation:cache-prune を schedule に入れます(docs/monitoring.md):
// routes/console.php Schedule::command('foundation:cache-prune')->hourly();
命名
表は foundation_、設定は foundation.*、コマンドは foundation:*。パッケージは秘密の値を持たず、設定(.env)から読むだけです。
ライセンス
MIT