Sanctum

Building Robust API Resource Management with Laravel When building a modern API, managing a core resource like an office requires more than just standard CRUD operations. It demands a sophisticated approach to data integrity, security, and user notifications. In this deep dive, we explore how to implement high-level Laravel patterns to manage the lifecycle of a resource. This isn't just about moving data from a request to a database; it's about ensuring that every state change is authorized, every transaction is atomic, and every stakeholder is notified when critical data shifts. Building an application like Ergodnc necessitates a strict focus on the backend first. By taking an API-first approach, you ensure that the business logic is decoupled from the presentation layer. This allows for cleaner testing and future flexibility, whether you eventually build a web frontend or a mobile app. We will focus on the creation, updating, and deletion of office resources, utilizing Eloquent and Sanctum to handle the heavy lifting. Atomic Integrity with Database Transactions One of the most common pitfalls in web development is leaving the database in an inconsistent state. Imagine a scenario where you successfully create an office record but the subsequent query to attach tags fails. You're left with an 'orphaned' office that lacks metadata. To prevent this, we utilize DB Transactions. ```php use Illuminate\Support\Facades\DB; DB::transaction(function () use ($attributes) { $office = Office::create($attributes); $office->tags()->attach($attributes['tags']); return $office; }); ``` By wrapping these queries in a callback, Laravel ensures that if any exception occurs within the closure, the entire process rolls back. This 'all-or-nothing' approach is non-negotiable for professional applications. Additionally, note the move from `sync()` to `attach()` during the creation phase. While `sync()` is powerful for updates because it compares existing relationships, `attach()` is more performant for new records as it skips the unnecessary 'check' query. Rethinking Validation: The Resource Validator Pattern While Laravel provides Form Requests, they can sometimes obscure the logic by moving validation to a hidden layer of the request lifecycle. A more explicit and reusable approach is the **Resource Validator** pattern. This involves creating a dedicated class—like an `OfficeValidator`—that handles the logic for both creation and updates. The OfficeValidator Class ```php namespace App\Models\Validators; use App\Models\Office; use Illuminate\Validation\Rule; use Illuminate\Support\Facades\Validator; class OfficeValidator { public function validate(Office $office, array $attributes): array { return Validator::make($attributes, [ 'title' => [Rule::when($office->exists, 'sometimes'), 'required', 'string'], 'latitude' => [Rule::when($office->exists, 'sometimes'), 'required', 'numeric'], 'longitude' => [Rule::when($office->exists, 'sometimes'), 'required', 'numeric'], 'price_per_day' => [Rule::when($office->exists, 'sometimes'), 'required', 'integer', 'min:100'], 'tags' => ['array'], 'tags.*' => ['integer', Rule::exists('tags', 'id')], ])->validate(); } } ``` By passing the model instance to the validator, we can use `Rule::when($office->exists, 'sometimes')`. This clever trick allows us to use the same ruleset for POST (create) and PUT (update) requests. In an update, the `sometimes` rule tells Laravel to only run the `required` validation if the key is actually present in the request. This avoids the frustration of a user being forced to provide every single field when they only wanted to change the title. Authorization and Custom Policies Security isn't just about who is logged in; it's about who owns the data. Laravel Policies provide a clean, centralized way to organize authorization logic. ```php public function update(User $user, Office $office) { return $user->id === $office->user_id; } ``` Inside the `OfficeController`, we invoke this via `$this->authorize('update', $office)`. This keeps the controller skinny and ensures that even if a user knows the ID of someone else's office, they cannot modify it. Using Sanctum tokens with specific scopes further tightens this by ensuring the token itself has permission to perform 'office:update' actions. Managing State Changes and Notifications In a marketplace like Ergodnc, changes to critical fields—like price or location—should trigger a re-review by an administrator. We can use Eloquent's `isDirty()` method to detect these changes before saving. ```php $office->fill($attributes); $requiresReview = $office->isDirty(['latitude', 'longitude', 'price_per_day']); if ($requiresReview) { $office->approval_status = Office::STATUS_PENDING; } $office->save(); if ($requiresReview) { Notification::send($admin, new OfficePendingApprovalNotification($office)); } ``` This logic ensures the system remains trustworthy. If a host tries to bait-and-switch a price, the office is automatically pulled from public view and an admin is alerted via an OfficePendingApprovalNotification. By using the `shouldQueue` interface on the notification class, we ensure the API response remains snappy while the email delivery happens in the background. Logic for Soft Deletions and Constraints Deleting a resource isn't always as simple as removing a row. We must respect business constraints. For example, an office cannot be deleted if it has active reservations. We can use the `throwIf()` helper for a readable, expressive check: ```php throw_if( $office->reservations()->where('status', Reservation::STATUS_ACTIVE)->exists(), ValidationException::withMessages(['office' => 'Cannot delete office with active reservations.']) ); $office->delete(); ``` Because we use Soft Deletes, the record stays in the database with a `deleted_at` timestamp. This provides an audit trail and allows for recovery if a deletion was accidental. Syntax Notes and Best Practices - **API First**: Build the endpoints and test them thoroughly before touching a line of CSS. This ensures your core logic is sound. - **Route Model Binding**: Always use type-hinting in your controller methods (e.g., `update(Office $office)`) to let Laravel handle the 404 logic automatically. - **Spike and Stabilize**: It's okay to write messy code to get a feature working (the spike). Just make sure you come back to refactor, abstract, and add tests (the stabilize) before shipping. - **Test with JSON**: When testing API endpoints, use `deleteJson()` or `postJson()` to ensure the framework returns the correct 422 Unprocessable Entity status codes rather than 302 redirects. By following these methodical steps—implementing transactions, centralizing validation, and enforcing strict ownership—you build more than just a feature; you build a resilient system architecture.