laravel-framework

name	laravel-framework
description	Laravel 12 / PHP 8.4 backend conventions for this monorepo. Use when adding controllers, Form Requests, Resources, middleware, routes, or any work inside apps/laravel/. Triggers on tasks involving PHP, Artisan commands, service providers, or the Laravel app directory.
frameworks	["laravel"]
languages	["php"]
category	backend
updated	"2026-04-29T00:00:00.000Z"

Laravel Framework Skill

Quick Reference

When to Use: Adding controllers, Form Requests, API Resources, routes, middleware, or service providers in apps/laravel/

Version: Laravel 12, PHP 8.4

Running commands: All Artisan commands proxy through the api Docker container via pnpm scripts or docker compose exec api php artisan …

Directory Layout

apps/laravel/
├── app/
│   ├── Http/
│   │   ├── Controllers/       # Invokable single-action controllers
│   │   │   └── Auth/
│   │   │       ├── Web/       # Cookie-session auth
│   │   │       └── Mobile/    # PAT auth
│   │   ├── Middleware/        # Custom HTTP middleware
│   │   ├── Requests/          # Form Request validation classes
│   │   └── Resources/         # API Resource transformers
│   ├── Models/                # Eloquent models
│   └── Providers/             # Service providers
├── bootstrap/
├── config/
├── database/
│   ├── factories/
│   ├── migrations/
│   └── seeders/
├── routes/
│   ├── api.php                # All API routes (versioned under /v1)
│   └── web.php
└── tests/
    ├── Feature/               # HTTP-level integration tests (Pest)
    └── Unit/                  # Pure unit tests (Pest)

Controller Pattern (invokable)

Prefer single-action invokable controllers. Each action in its own class.

// app/Http/Controllers/TodoController.php
namespace App\Http\Controllers;

use App\Http\Requests\StoreTodoRequest;
use App\Http\Resources\TodoResource;
use App\Models\Todo;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;

/**
 * @group Todos
 */
class TodoController extends Controller
{
    /**
     * List todos
     *
     * Returns all todos belonging to the authenticated user.
     *
     * @response 200 [{"id":1,"title":"Buy milk","completed":false,"created_at":"2025-01-01T00:00:00.000000Z"}]
     */
    public function index(Request $request): AnonymousResourceCollection
    {
        return TodoResource::collection(
            $request->user()->todos()->latest()->get()
        );
    }

    /**
     * Create todo
     *
     * @response 201 {"id":2,"title":"Buy eggs","completed":false,"created_at":"2025-01-01T00:00:00.000000Z"}
     */
    public function store(StoreTodoRequest $request): TodoResource
    {
        $todo = $request->user()->todos()->create($request->validated());
        return new TodoResource($todo);
    }
}

Form Request Validation

// app/Http/Requests/StoreTodoRequest.php
namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreTodoRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true; // Auth guard handles access; Form Request validates shape
    }

    public function rules(): array
    {
        return [
            'title'     => ['required', 'string', 'max:255'],
            'completed' => ['boolean'],
        ];
    }
}

API Resource

// app/Http/Resources/TodoResource.php
namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class TodoResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'         => $this->id,
            'title'      => $this->title,
            'completed'  => $this->completed,
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }
}

Route Definition

All API routes live in routes/api.php under the /v1 prefix.

// routes/api.php
Route::prefix('v1')->group(function () {
    Route::get('/health', HealthController::class);

    Route::middleware('auth:sanctum')->group(function () {
        Route::get('/me', fn (Request $request) => response()->json($request->user()));
        Route::apiResource('todos', TodoController::class);
    });
});

Common Artisan Commands

# Generate a controller (invokable)
docker compose exec api php artisan make:controller FeatureController --invokable

# Generate a controller with CRUD methods
docker compose exec api php artisan make:controller FeatureController --api

# Generate Form Request
docker compose exec api php artisan make:request StoreFeatureRequest

# Generate API Resource
docker compose exec api php artisan make:resource FeatureResource

# Generate Model + migration + factory + seeder
docker compose exec api php artisan make:model Feature -mfs

# Run migrations
docker compose exec api php artisan migrate

# Regenerate OpenAPI spec
pnpm -F @repo/laravel openapi:generate

pnpm Script Shims

Command	Proxies to
pnpm -F @repo/laravel dev	docker compose up api mysql
pnpm -F @repo/laravel test	docker compose exec api php artisan test
pnpm -F @repo/laravel lint	docker compose exec api ./vendor/bin/pint --test
pnpm -F @repo/laravel format	docker compose exec api ./vendor/bin/pint
pnpm -F @repo/laravel typecheck	docker compose exec api ./vendor/bin/phpstan analyse
pnpm -F @repo/laravel openapi:generate	Runs Scribe + YAML→JSON conversion

Adding a New Feature Checklist

1. Create migration: make:model Feature -mfs
2. Define fillable/casts on model
3. Create Form Request(s): make:request StoreFeatureRequest
4. Create API Resource: make:resource FeatureResource
5. Create Controller: make:controller FeatureController --api
6. Register routes in routes/api.php
7. Add Scribe @group, @bodyParam, @response annotations
8. Write Pest feature test in tests/Feature/
9. Regenerate OpenAPI: pnpm -F @repo/laravel openapi:generate
10. Run Orval: pnpm -F @repo/api-client generate to update TS hooks