abort_unless — 条件が「偽」なら即座にHTTP例外で中断
helper
2025.12.16
カテゴリ : helper掲載バージョン : Laravel 12・PHP 8.4名前空間 / FQCN / コマンド : abort_unless()関連 : abort / abort_if / throw_unless / abort(403, …) / Gate::authorize変更履歴 : （要確認事項なし）
要点（TL;DR）
条件が満たされないとき（false）に、指定ステータスのHTTP例外を投げて処理を止める。
abort_unless($isAdmin, 403);よくある罠
abort_unless($user, 403) のように「truthy」に頼ると意図せず通る/落ちる（null と空文字など）例外メッセージは本番で露出 しうる（デバッグ用の内部情報を入れない）
$code は int だけでなく Response|Responsable も渡せる（挙動を統一しないと読みにくい） (api.laravel.com )
概要 abort_unless() は、条件が true であることを要求し、満たされない場合は HTTP例外（ステータスコード付き） を投げて即座に中断します。認可チェックや前提条件（存在確認・機能フラグ・署名検証など）を「1行」で書きたいときに便利です。 (Laravel )
構文 / シグネチャ abort_unless(bool $boolean, Response|Responsable|int $code, string $message = '', array $headers = []);
引数 型 必須 既定値 説明 $booleanbool✅ なし true であることを要求する条件（false なら中断）$codeResponse | Responsable | int✅ なし HTTPステータスコード、または返したいレスポンス $messagestring❌ ''例外メッセージ（エラーページ等で使われうる） $headersarray❌ []レスポンスヘッダ（例: ['X-Reason' => '...']）
使用例 最小例 <?php
use Illuminate\Support\Facades\Auth;
abort_unless(Auth::check(), 401, 'Unauthenticated.');
// ここ以降はログイン済みだけが到達する
実務例 <?php
use App\Models\Project;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;
Route::post('/projects/{project}/deploy', function (Request $request, Project $project) {
// 認可（できなければ 403 で中断）
abort_unless(Gate::allows('deploy', $project), 403);
// 署名ヘッダが必須（なければ 422 で中断）
abort_unless($request->hasHeader('X-Signature'), 422, 'Missing signature.');
// …デプロイ処理…
return response()->json(['ok' => true]);
});
よくある落とし穴・注意
条件は「bool」に寄せる ：$user / $id をそのまま渡すより、$user !== null や filled($id) のように意図を固定すると安全です。メッセージに機微情報を入れない ：内部ID・設定値・署名検証の詳細などは露出しない設計に。$code を int 以外で混在させないResponse|Responsable を許容できるのは便利ですが、チーム内で方針がないと読みづらくなります。 (api.laravel.com )
代替・関連APIとの比較
abort_if($cond, 403)：条件が true のとき落とす （abort_unless の反対）。読みやすい方を選ぶ。 (Laravel )abort(403, ...)：条件分岐を自分で書く前提。複雑な分岐やログ出しが必要ならこちら。throw_unless($cond, SomeException::class)：HTTPに限らず例外種別を選びたいとき（ドメイン例外など）。Gate::authorize('ability', $model) / FormRequest::authorize()：認可は「仕組み」に寄せたいとき（方針・テスト・メッセージ統一がしやすい）。
テスト例（Pest） <?php
use Illuminate\Support\Facades\Route;
it('aborts with 403 when condition is false', function () {
Route::get('/__test_abort_unless', function () {
abort_unless(false, 403);
return 'ok';
});
$this->get('/__test_abort_unless')->assertForbidden();
});
トラブルシュート（エラー別） 症状/エラー 原因 対処 期待したのに中断しない 条件が truthy になっている（例："0" は truthy） 明示的に === / !== で bool 化する 403 のはずが別のレスポンスになる $code に `ResponseResponsable` を渡している エラーページにメッセージが出てしまう $message を入れている本番向けメッセージにする／入れない方針にする
参考リンク
