laravel-ops

What this skill does

# Laravel Operations

Authoritative reference for Laravel 11+ development: architecture decisions, Eloquent patterns, authentication strategies, queue configuration, and testing approaches.

---

## Architecture Decision Tree

```
What type of application?
│
├─ Full-stack web (HTML responses)
│  ├─ Simple CRUD, small team → Monolith (Blade + Eloquent directly)
│  │   └─ Use action classes for business logic over 20 lines
│  ├─ Rich interactivity needed → Livewire (server-driven reactivity)
│  │   └─ Add Alpine.js for client-side micro-interactions
│  └─ SPA-like feel, React/Vue team → Inertia.js
│      └─ Keep server-side routing, dump client-side routing overhead
│
├─ API backend (JSON responses)
│  ├─ Single consumer (mobile/SPA) → API-only with Sanctum SPA auth
│  ├─ Multiple consumers / public → RESTful API with token auth
│  └─ Complex graph queries → Consider GraphQL (lighthouse-php/lighthouse)
│
├─ Large team / complex domain
│  ├─ Domain-driven → Modular monolith (app/Modules/{Domain}/)
│  │   ├─ Each module: Models, Actions, Events, Jobs, Http/
│  │   └─ Shared: app/Shared/ for cross-cutting concerns
│  └─ Independent deployability needed → Microservices
│      └─ Use Laravel Octane for high-throughput services
│
└─ What business logic pattern?
   ├─ Simple CRUD, < 20 lines → Direct Eloquent in controller
   ├─ Reusable operation (create order, send invoice) → Action class
   │   └─ Single public handle() or execute() method
   ├─ Complex queries, multiple data sources → Repository pattern
   │   └─ Interface + Eloquent implementation (enables swapping)
   └─ Cross-cutting operations (audit, caching) → Service class
       └─ Inject via constructor, bind in ServiceProvider
```

### Action Class vs Repository vs Service

| Pattern | Use When | Example |
|---------|----------|---------|
| Action class | Single, reusable business operation | `CreateOrderAction`, `SendInvoiceAction` |
| Repository | Abstract data access, multiple sources | `OrderRepository` with `EloquentOrderRepository` |
| Service | Orchestrate multiple actions/repos | `OrderService` combining payment + inventory |
| Direct Eloquent | Simple CRUD, < 5 lines in controller | `User::create($data)` |

---

## Eloquent Quick Reference

### Relationships

| Relationship | Method | Foreign Key Convention |
|-------------|--------|----------------------|
| `hasOne` | `return $this->hasOne(Profile::class)` | `profiles.user_id` |
| `hasMany` | `return $this->hasMany(Post::class)` | `posts.user_id` |
| `belongsTo` | `return $this->belongsTo(User::class)` | `posts.user_id` |
| `belongsToMany` | `return $this->belongsToMany(Role::class)` | `role_user` pivot |
| `hasManyThrough` | `return $this->hasManyThrough(Post::class, User::class)` | Country → User → Post |
| `morphTo` | `return $this->morphTo()` | `{col}_type`, `{col}_id` |
| `morphMany` | `return $this->morphMany(Comment::class, 'commentable')` | Polymorphic |
| `morphToMany` | `return $this->morphToMany(Tag::class, 'taggable')` | Polymorphic pivot |

### Eager Loading

```php
// Prevent N+1: always eager load in controllers
$posts = Post::with(['author', 'comments.author', 'tags'])->paginate(15);

// Conditional eager loading (load after retrieval)
$user->load('posts.comments');
$user->loadMissing('posts'); // only if not already loaded

// Eager load counts (no SELECT *)
$posts = Post::withCount('comments')->get();

// Constrained eager loading
$posts = Post::with(['comments' => fn($q) => $q->approved()->latest()])->get();
```

### Query Scopes

```php
// Local scope (reusable query constraint)
public function scopeActive(Builder $query): void
{
    $query->where('status', 'active');
}

// Usage: User::active()->get()

// Dynamic scope
public function scopeOfType(Builder $query, string $type): void
{
    $query->where('type', $type);
}
// Usage: User::ofType('admin')->get()
```

### Mass Assignment

```php
// Fillable (allowlist - preferred)
protected $fillable = ['name', 'email', 'password'];

// Guarded (denylist - use [] only if you trust all input)
protected $guarded = ['id', 'is_admin'];

// Never set guarded = [] in production code
```

---

## Artisan Command Cheat Sheet

| Command | Purpose | Common Options |
|---------|---------|----------------|
| `make:model Post -mfs` | Model + migration + factory + seeder | `-c` controller, `-r` resource |
| `make:controller PostController -r` | Resource controller (7 methods) | `--api` skips create/edit |
| `make:request StorePostRequest` | Form request for validation | |
| `make:job ProcessPayment` | Queueable job class | `--sync` for sync job |
| `make:event OrderPlaced` | Event class | |
| `make:listener SendOrderConfirmation -e OrderPlaced` | Listener for event | `--queued` |
| `make:notification InvoicePaid` | Notification class | |
| `make:policy PostPolicy -m Post` | Policy with model | |
| `make:middleware EnsureUserIsAdmin` | HTTP middleware | |
| `make:command SendDailyReport` | Custom Artisan command | |
| `migrate` | Run pending migrations | `--step` for individual |
| `migrate:rollback` | Roll back last batch | `--step=5` |
| `migrate:fresh --seed` | Drop all + re-migrate + seed | |
| `db:seed` | Run all seeders | `--class=UserSeeder` |
| `tinker` | REPL with app context | |
| `route:list` | Show all routes | `--name=api` filter |
| `route:cache` | Cache routes for production | |
| `config:cache` | Cache config for production | |
| `view:cache` | Pre-compile Blade templates | |
| `optimize` | Run all cache commands | `optimize:clear` to reset |
| `queue:work` | Process queue jobs | `--queue=high,default` |
| `queue:listen` | Work + auto-reload on code change | |
| `queue:failed` | List failed jobs | |
| `queue:retry all` | Retry all failed jobs | |
| `schedule:run` | Run due scheduled tasks | |
| `schedule:work` | Run scheduler every minute (dev) | |
| `key:generate` | Generate APP_KEY | |
| `test` | Run PHPUnit/Pest tests | `--filter=UserTest` |
| `test --parallel` | Run tests in parallel | `--processes=4` |
| `vendor:publish` | Publish package assets/config | `--tag=config` |

---

## Authentication Decision Tree

```
What do you need?
│
├─ SPA (Vue/React) + Laravel API backend
│  └─ Sanctum SPA authentication
│     ├─ Cookie-based (same domain or subdomain)
│     ├─ Csrf-cookie endpoint: GET /sanctum/csrf-cookie
│     └─ No tokens in localStorage (XSS safe)
│
├─ Mobile app or third-party API consumers
│  └─ Sanctum API tokens (Bearer tokens)
│     ├─ createToken($name, $abilities)
│     ├─ Token abilities for fine-grained control
│     └─ Token expiration with token:prune schedule
│
├─ Traditional web app (server-rendered)
│  ├─ Just need auth pages quickly → Breeze
│  │   ├─ Minimal, educational, Blade or Inertia stack
│  │   └─ Install: composer require laravel/breeze --dev
│  ├─ Need teams, 2FA, profile management → Jetstream
│  │   ├─ Livewire or Inertia stack
│  │   └─ Install: composer require laravel/jetstream
│  └─ Need headless auth (API + custom UI) → Fortify
│      ├─ Actions in app/Actions/Fortify/
│      └─ Customize: CreateNewUser, UpdateUserPassword
│
└─ Custom / enterprise
   ├─ LDAP/SAML → socialiteproviders/saml2
   ├─ OAuth social login → laravel/socialite
   └─ Custom guard → Implement Guard + UserProvider contracts
```

### Sanctum Quick Setup

```php
// config/sanctum.php - stateful domains for SPA
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost')),

// API token creation
$token = $user->createToken('mobile-app', ['orders:read', 'orders:write']);
return ['token' => $token->plainTextToken];

// Check token ability
Route::get('/orders', function (Request $request) {
    $request->user()->tokenCan('orders:read'); // bool
});

// Protect routes
Route::middleware('auth:sanctum')->group(function () {
    // authenticated routes
});
```

---

## Queue Decision Tree

```
Queue driver selection:
│
├─ Development / testing
│  └─ sync driver (executes immediately, no worker needed)
│     QUEUE_CONNECTION=sync
│
├─ Small app, no Redis