Laravel

# Laravel 11.x+ Framework Guide

This file is automatically included by the motspilot pipeline when `FRAMEWORK="laravel"` is set in config. It provides framework-specific knowledge for all pipeline phases.

<framework_tool_affinity>
Laravel-specific tool routing:
- Use `php artisan make:model Name -mfcrs` to scaffold Model + Migration + Factory + Controller + Resource + Seeder — never handwrite boilerplate from scratch.
- Use `php artisan make:migration create_things_table` to scaffold migration files — never handwrite the timestamp prefix.
- Use `php artisan route:list` to verify route conflicts before adding new routes.
- Use `php artisan make:request StoreThingRequest` to generate Form Request classes — never validate inside controllers.
- Use `php artisan make:policy ThingPolicy --model=Thing` to scaffold authorization policies.
- Use `php artisan make:test ThingTest` (Feature) or `php artisan make:test ThingTest --unit` (Unit).
- For constant values: grep `app/Models/` and `app/Enums/` for existing constants/enums before defining new ones.
- For queue jobs: `php artisan make:job ProcessThing` — never dispatch closures for non-trivial work.
- For events: `php artisan make:event ThingCreated` + `php artisan make:listener SendThingNotification --event=ThingCreated`.
</framework_tool_affinity>

---

## Version Reference

**This guide is for Laravel 11.x+ (including 12.x). Do NOT use patterns removed in Laravel 11.**

Laravel 11 introduced a streamlined application structure. Laravel 12 is a maintenance release with no breaking changes from 11. Both share the same patterns.

| What | Laravel 11.x+ (correct) | Pre-11 (WRONG for new projects) |
|------|------------------------|-------------------------------|
| Application bootstrap | `bootstrap/app.php` (code-first config) | `app/Http/Kernel.php`, `app/Console/Kernel.php` |
| Middleware registration | `->withMiddleware()` in `bootstrap/app.php` | `$middleware` arrays in `Kernel.php` |
| Exception handling | `->withExceptions()` in `bootstrap/app.php` | `app/Exceptions/Handler.php` |
| Service providers | Single `AppServiceProvider` | 5 default providers |
| Scheduled tasks | `routes/console.php` using `Schedule` facade | `app/Console/Kernel.php` `schedule()` method |
| Default middleware dir | None (define inline or in `bootstrap/app.php`) | `app/Http/Middleware/` |
| Health check route | Built-in `/up` route | Manual |
| Model casts | `protected function casts(): array` method | `protected $casts = []` property |
| Accessor/Mutator syntax | `Illuminate\Database\Eloquent\Casts\Attribute` return type | `getNameAttribute()` / `setNameAttribute()` |
| Password hashing | `Hash::make()` with bcrypt default (Argon2id configurable) | Same |
| Coding standard | PSR-12 | PSR-12 |
| PHP minimum | 8.2 | 8.1 (Laravel 10), 8.0 (Laravel 9) |

---

## Naming Conventions

Laravel uses convention over configuration. Follow these exactly to avoid extra config:

| What | Convention | Example |
|------|-----------|---------|
| Model class | Singular, PascalCase | `PlatformPackage` |
| Table name | Plural, snake_case | `platform_packages` |
| Column name | snake_case | `created_at`, `user_id`, `is_active` |
| Controller class | Singular resource + `Controller` | `PlatformPackageController` |
| Form Request | `Store`/`Update` + Model + `Request` | `StorePlatformPackageRequest` |
| Policy class | Model + `Policy` | `PlatformPackagePolicy` |
| Event class | Past tense, PascalCase | `PlatformPackageCreated` |
| Listener class | Imperative verb, PascalCase | `SendPackageNotification` |
| Job class | Imperative verb, PascalCase | `ProcessPackagePayment` |
| Notification class | Imperative/descriptive, PascalCase | `PackageShipped` |
| Migration file | `create_things_table` / `add_status_to_things_table` | `2026_04_16_120000_create_platform_packages_table` |
| Factory class | Model + `Factory` | `PlatformPackageFactory` |
| Seeder class | Model/Plural + `Seeder` | `PlatformPackageSeeder` |
| Middleware class | PascalCase, descriptive | `EnsureUserIsAdmin` |
| Enum | Singular, PascalCase | `PackageStatus` |
| Blade view | kebab-case or snake_case | `platform-packages/show.blade.php` |
| Route name | Dot-separated, resource-style | `platform-packages.show` |
| Config file | snake_case | `platform_packages.php` |
| Foreign key | Singular model + `_id` | `platform_package_id` |
| Pivot table | Singular models, alphabetical, snake_case | `package_user` |

**Match what the existing project uses.** If it uses `snake_case` view names, do not introduce `kebab-case`.

---

## Files to Explore (Architecture Phase)

When exploring a Laravel codebase, read these files like a detective: