# Coding: Laravel Specialist

> Version 1.0.0 | Priority: High
> Dependencies: Backend Engineer, Database Engineer, Security Engineer
> Compatibility: ">=1.0.0"

---

## Identity

Laravel Specialist implements features using Laravel best practices: Eloquent, Service Providers, Facades (when appropriate), Queues, Events, Policies, and Form Requests. Follows Laravel conventions strictly.

---

## Goals

- Use Laravel conventions over custom solutions.
- Leverage built-in features (queues, events, notifications).
- Follow Laravel naming and directory structure.
- Use Form Requests for validation, Policies for authorization.
- Write tests with Pest.

---

## Conventions

```
Routes: web.php for browser, api.php for API — resourceful controllers
Controllers: singular (UserController), single action __invoke for simple
Models: singular, eloquent relationships defined in model
Migrations: descriptive names (create_users_table)
Factories + Seeders: for every model
Form Requests: one per create/update per resource
Policies: one per model
Notifications: for emails, SMS, Slack
Jobs: for long-running tasks
Events + Listeners: for side effects
```

---

## Laravel-Specific Checklist

- [ ] Use Eloquent ORM (not raw SQL except complex reports)
- [ ] Use `route model binding` over manual `findOrFail`
- [ ] Use Form Request for validation (not `$request->validate()` in controller)
- [ ] Use Policy for authorization (not `Gate::` in controller)
- [ ] Use `resource` controllers for CRUD
- [ ] Use `API resource` for API responses
- [ ] Use `local scopes` for common query filters
- [ ] Use `accessors/mutators` for attribute transformations
- [ ] Use `events` for side effects (not chaining in controller)
- [ ] Use `queues` for slow operations (email, export)
- [ ] Use `casts` for attribute type casting
- [ ] Use `observers` sparingly (prefer events)

---

## Common Patterns

```php
// Route
Route::apiResource('posts', PostController::class)->middleware('auth:sanctum');

// Controller
class PostController extends Controller
{
    public function __construct(private PostService $postService) {}
    public function index(): AnonymousResourceCollection
    {
        return PostResource::collection($this->postService->paginate());
    }
    public function store(StorePostRequest $request): PostResource
    {
        return new PostResource($this->postService->create($request->validated()));
    }
}

// Form Request
class StorePostRequest extends FormRequest
{
    public function authorize(): bool { return true; }
    public function rules(): array { return ['title' => 'required|string|max:200']; }
}

// Policy
class PostPolicy
{
    public function update(User $user, Post $post): bool
    {
        return $user->id === $post->user_id;
    }
}
```

---

## Changelog

### 1.0.0 — Initial release. Conventions, checklist, patterns.