1# Laravel Patterns
2 
3## Service Layer Pattern
4 
5```php
6<?php
7 
8declare(strict_types=1);
9 
10namespace App\Services;
11 
12use App\DTOs\CreateUserData;
13use App\Models\User;
14use App\Repositories\UserRepositoryInterface;
15use Illuminate\Support\Facades\Hash;
16 
17final readonly class UserService
18{
19    public function __construct(
20        private UserRepositoryInterface $userRepository,
21        private EmailService $emailService,
22    ) {}
23 
24    public function createUser(CreateUserData $data): User
25    {
26        $user = $this->userRepository->create([
27            'name' => $data->name,
28            'email' => $data->email,
29            'password' => Hash::make($data->password),
30        ]);
31 
32        $this->emailService->sendWelcomeEmail($user);
33 
34        return $user;
35    }
36 
37    public function suspendUser(int $userId, string $reason): void
38    {
39        $user = $this->userRepository->findOrFail($userId);
40 
41        $this->userRepository->update($user->id, [
42            'status' => UserStatus::SUSPENDED,
43            'suspension_reason' => $reason,
44            'suspended_at' => now(),
45        ]);
46 
47        $this->emailService->sendSuspensionNotice($user, $reason);
48    }
49}
50```
51 
52## Repository Pattern
53 
54```php
55<?php
56 
57declare(strict_types=1);
58 
59namespace App\Repositories;
60 
61use App\Models\User;
62use Illuminate\Database\Eloquent\Collection;
63 
64interface UserRepositoryInterface
65{
66    public function findOrFail(int $id): User;
67    public function findByEmail(string $email): ?User;
68    public function create(array $data): User;
69    public function update(int $id, array $data): User;
70    public function delete(int $id): void;
71    public function getActive(): Collection;
72}
73 
74final class UserRepository implements UserRepositoryInterface
75{
76    public function findOrFail(int $id): User
77    {
78        return User::findOrFail($id);
79    }
80 
81    public function findByEmail(string $email): ?User
82    {
83        return User::where('email', $email)->first();
84    }
85 
86    public function create(array $data): User
87    {
88        return User::create($data);
89    }
90 
91    public function update(int $id, array $data): User
92    {
93        $user = $this->findOrFail($id);
94        $user->update($data);
95        return $user->fresh();
96    }
97 
98    public function delete(int $id): void
99    {
100        $this->findOrFail($id)->delete();
101    }
102 
103    public function getActive(): Collection
104    {
105        return User::where('status', UserStatus::ACTIVE)
106            ->orderBy('created_at', 'desc')
107            ->get();
108    }
109}
110```
111 
112## Form Requests with Enums
113 
114```php
115<?php
116 
117declare(strict_types=1);
118 
119namespace App\Http\Requests;
120 
121use App\Enums\UserRole;
122use Illuminate\Foundation\Http\FormRequest;
123use Illuminate\Validation\Rule;
124use Illuminate\Validation\Rules\Enum;
125use Illuminate\Validation\Rules\Password;
126 
127final class CreateUserRequest extends FormRequest
128{
129    public function authorize(): bool
130    {
131        return $this->user()?->can('create', User::class) ?? false;
132    }
133 
134    public function rules(): array
135    {
136        return [
137            'name' => ['required', 'string', 'max:255'],
138            'email' => ['required', 'email', 'unique:users,email'],
139            'password' => ['required', Password::min(8)->mixedCase()->numbers()],
140            'role' => ['required', new Enum(UserRole::class)],
141            'settings' => ['sometimes', 'array'],
142            'settings.theme' => ['string', Rule::in(['light', 'dark'])],
143        ];
144    }
145 
146    public function toDto(): CreateUserData
147    {
148        return new CreateUserData(
149            name: $this->validated('name'),
150            email: $this->validated('email'),
151            password: $this->validated('password'),
152            role: UserRole::from($this->validated('role')),
153        );
154    }
155}
156```
157 
158## API Resources
159 
160```php
161<?php
162 
163declare(strict_types=1);
164 
165namespace App\Http\Resources;
166 
167use Illuminate\Http\Request;
168use Illuminate\Http\Resources\Json\JsonResource;
169 
170/**
171 * @mixin \App\Models\User
172 */
173final class UserResource extends JsonResource
174{
175    public function toArray(Request $request): array
176    {
177        return [
178            'id' => $this->id,
179            'name' => $this->name,
180            'email' => $this->email,
181            'status' => $this->status->value,
182            'role' => $this->role->value,
183            'created_at' => $this->created_at->toIso8601String(),
184 
185            // Conditional relationships
186            'posts' => PostResource::collection($this->whenLoaded('posts')),
187            'profile' => new ProfileResource($this->whenLoaded('profile')),
188 
189            // Conditional attributes
190            'is_admin' => $this->when($this->role === UserRole::ADMIN, true),
191 
192            // Pivot data
193            'team_role' => $this->whenPivotLoaded('team_user', fn() =>
194                $this->pivot->role
195            ),
196        ];
197    }
198}
199 
200final class UserCollection extends ResourceCollection
201{
202    public function toArray(Request $request): array
203    {
204        return [
205            'data' => $this->collection,
206            'meta' => [
207                'total' => $this->total(),
208                'per_page' => $this->perPage(),
209            ],
210        ];
211    }
212}
213```
214 
215## Controllers with DTOs
216 
217```php
218<?php
219 
220declare(strict_types=1);
221 
222namespace App\Http\Controllers\Api;
223 
224use App\Http\Controllers\Controller;
225use App\Http\Requests\CreateUserRequest;
226use App\Http\Resources\UserResource;
227use App\Services\UserService;
228use Illuminate\Http\JsonResponse;
229use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
230 
231final class UserController extends Controller
232{
233    public function __construct(
234        private readonly UserService $userService,
235    ) {}
236 
237    public function index(): AnonymousResourceCollection
238    {
239        $users = User::with('profile')
240            ->where('status', UserStatus::ACTIVE)
241            ->paginate(20);
242 
243        return UserResource::collection($users);
244    }
245 
246    public function store(CreateUserRequest $request): JsonResponse
247    {
248        $user = $this->userService->createUser($request->toDto());
249 
250        return (new UserResource($user))
251            ->response()
252            ->setStatusCode(201);
253    }
254 
255    public function show(User $user): UserResource
256    {
257        $user->load(['posts', 'profile']);
258        return new UserResource($user);
259    }
260 
261    public function destroy(User $user): JsonResponse
262    {
263        $this->authorize('delete', $user);
264 
265        $this->userService->deleteUser($user->id);
266 
267        return response()->json(null, 204);
268    }
269}
270```
271 
272## Jobs & Queues
273 
274```php
275<?php
276 
277declare(strict_types=1);
278 
279namespace App\Jobs;
280 
281use App\Models\User;
282use App\Services\EmailService;
283use Illuminate\Bus\Queueable;
284use Illuminate\Contracts\Queue\ShouldQueue;
285use Illuminate\Foundation\Bus\Dispatchable;
286use Illuminate\Queue\InteractsWithQueue;
287use Illuminate\Queue\SerializesModels;
288 
289final class SendWelcomeEmail implements ShouldQueue
290{
291    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
292 
293    public int $tries = 3;
294    public int $timeout = 30;
295 
296    public function __construct(
297        private readonly int $userId,
298    ) {}
299 
300    public function handle(EmailService $emailService): void
301    {
302        $user = User::findOrFail($this->userId);
303        $emailService->sendWelcomeEmail($user);
304    }
305 
306    public function failed(\Throwable $exception): void
307    {
308        \Log::error('Failed to send welcome email', [
309            'user_id' => $this->userId,
310            'error' => $exception->getMessage(),
311        ]);
312    }
313}
314 
315// Dispatching jobs
316SendWelcomeEmail::dispatch($user->id);
317SendWelcomeEmail::dispatch($user->id)->delay(now()->addMinutes(5));
318SendWelcomeEmail::dispatch($user->id)->onQueue('emails');
319```
320 
321## Event Listeners
322 
323```php
324<?php
325 
326declare(strict_types=1);
327 
328namespace App\Events;
329 
330use App\Models\User;
331use Illuminate\Foundation\Events\Dispatchable;
332use Illuminate\Queue\SerializesModels;
333 
334final readonly class UserRegistered
335{
336    use Dispatchable, SerializesModels;
337 
338    public function __construct(
339        public User $user,
340    ) {}
341}
342 
343namespace App\Listeners;
344 
345use App\Events\UserRegistered;
346use App\Jobs\SendWelcomeEmail;
347use Illuminate\Contracts\Queue\ShouldQueue;
348 
349final class SendWelcomeNotification implements ShouldQueue
350{
351    public function handle(UserRegistered $event): void
352    {
353        SendWelcomeEmail::dispatch($event->user->id);
354    }
355}
356 
357// In EventServiceProvider
358protected $listen = [
359    UserRegistered::class => [
360        SendWelcomeNotification::class,
361        UpdateUserStatistics::class,
362    ],
363];
364```
365 
366## Quick Reference
367 
368| Pattern | Purpose | File Location |
369|---------|---------|---------------|
370| Service | Business logic | `app/Services/` |
371| Repository | Data access | `app/Repositories/` |
372| Form Request | Validation | `app/Http/Requests/` |
373| Resource | API responses | `app/Http/Resources/` |
374| Job | Async tasks | `app/Jobs/` |
375| Event | Domain events | `app/Events/` |
376| DTO | Data transfer | `app/DTOs/` |
377| Policy | Authorization | `app/Policies/` |
378