Laravel Sanctum

Overview: The Strategic Blueprint for Modern Laravel APIs Building a Laravel application requires more than just running a few terminal commands; it demands a clear understanding of the 'why' behind architectural choices. When starting a project from scratch—like the office-rental platform for remote workers we are building—the initial setup phase is the most critical. This is where you define the relationships between your data, establish your coding conventions, and set the stage for a scalable, maintainable codebase. Developing with an **API-first** mindset means prioritizing the backend's ability to serve data consistently to any client, whether it is a Single Page Application (SPA), a mobile app, or a traditional Blade frontend. By decoupling the logic from the presentation layer early on, you ensure that your application remains flexible as it grows. This tutorial focuses on the foundational "spike and stabilize" workflow: writing functional code quickly to prove a concept, then reinforcing it with robust tests and Eloquent refinements. Prerequisites: Essential Tools and Concepts To follow this guide, you should be comfortable with the following: * **PHP 8.x**: Knowledge of modern PHP features like constructor property promotion and attributes. * **Laravel Framework**: Familiarity with the MVC pattern and Artisan CLI. * **Relational Databases**: Understanding of foreign keys and many-to-many relationships. * **Composer**: Ability to manage PHP dependencies. * **Testing Basics**: Basic understanding of PHPUnit or Laravel's built-in testing suite. Key Libraries & Tools * Laravel Framework: The primary PHP framework used for the backend. * Eloquent ORM: Laravel's database abstraction layer for managing models and relationships. * Laravel Sanctum: A lightweight authentication system for APIs and SPAs. * PHPUnit: The testing framework used to validate our API endpoints. * Faker: A PHP library used within factories to generate realistic dummy data. Code Walkthrough: Database Migrations and Model Relationships Our database schema must support a variety of features, including office listings, tags for amenities, and polymorphic images. Let's start with the polymorphic image relationship, which allows us to attach images to any model (offices, reviews, or users) without creating separate tables for each. 1. Defining the Polymorphic Image Migration ```php Schema::create("images", function (Blueprint $table) { $table->id(); $table->string("path"); $table->numericMorphs("imageable"); $table->timestamps(); }); ``` The `numericMorphs` method is a powerful shortcut. It creates both `imageable_id` (a big integer) and `imageable_type` (a string) columns while automatically indexing them. This enables the **MorphMany** relationship in our models. 2. Establishing Model Relationships and Casts Inside the `Office` model, we define how it interacts with users, reservations, and images. We also use **Attribute Casting** to ensure that data retrieved from the database is in the correct format for our logic. ```php class Office extends Model { use SoftDeletes; protected $casts = [ "lat" => "decimal:8", "lng" => "decimal:8", "approval_status" => "integer", "hidden" => "boolean", "price_per_day" => "integer", ]; public function user(): BelongsTo { return $this->belongsTo(User::class); } public function images(): MorphMany { return $this->morphMany(Image::class, "resource"); } } ``` Notice the use of `decimal:8` in the casts. This ensures that coordinate data for maps maintains its precision. We also utilize constants for statuses rather than magic numbers to make the code readable and self-documenting. Syntax Notes: Mass Assignment and Immutable Dates A common point of friction in Laravel is **Mass Assignment Protection**. While it serves as a security layer to prevent users from injecting unexpected data into your database, it can be cumbersome during rapid development. In this project, we disable it globally in the `AppServiceProvider` because we strictly validate all incoming request data before it ever hits the model. ```php // In AppServiceProvider.php public function boot() { Model::unguard(); } ``` Another modern best practice is using **Immutable Dates**. When working with reservation ranges, a mutable date object can lead to bugs where modifying the 'end date' accidentally changes the 'start date' because they share the same object reference. By casting to `immutable_date`, any modification creates a new instance, leaving the original untouched. ```php protected $casts = [ "start_date" => "immutable_date", "end_date" => "immutable_date", ]; ``` Practical Examples: Building the API Resources Instead of returning raw Eloquent models, we use **API Resources**. These act as a transformation layer between your database and your JSON output. This is vital for maintaining a stable API contract; if you rename a database column, you only need to update the resource mapping, and your frontend won't break. The Tag Controller Implementation For simple resources like tags (amenities like "Air Conditioning" or "Private Bathroom"), an **invokable controller** is often the cleanest approach. It focuses the class on a single action. ```php class TagController extends Controller { public function __invoke() { return TagResource::collection(Tag::all()); } } ``` This keeps our `api.php` routes file lean and emphasizes the specific responsibility of the controller. Tips & Gotchas: The Spike and Stabilize Method 1. **Don't Let Enums Block You**: While PHP now supports native Enums, using them in database migrations can be risky. Altering an ENUM column in a large database often requires locking the table, which causes downtime. Using integer constants in your model provides the same readability without the database-level headaches. 2. **Factory Count Shortcuts**: When writing tests, you can quickly generate multiple models using `Office::factory()->count(3)->create()`. This is essential for testing pagination and sorting logic. 3. **The 'Latest' Helper**: Laravel provides a `latest()` query scope that defaults to `created_at`. However, if you want to sort by ID for performance or specific ordering, you can pass the column name: `Office::query()->latest("id")->get()`. 4. **Testing JSON Structure**: When asserting API responses, avoid checking the exact JSON string. Instead, use `assertJsonCount()` or `assertJsonPath()`. This makes your tests **future-proof**—they won't break just because you added a new field to the resource later on.

The Persistence Problem Standard session-based authentication protects users through brevity. By default, Laravel expires session cookies after two hours of inactivity. This prevents a forgotten browser tab from becoming a permanent gateway to private data. However, modern user experience often demands persistence. We solve this by implementing the "Remember Me" pattern and transitioning to token-based security for decoupled environments. Implementing Remember Me Laravel simplifies long-term sessions via the `attempt` method. By passing a boolean as the second argument, you instruct the framework to issue a "recalling" cookie that outlives the standard session. ```php public function login(Request $request) { $credentials = $request->only('email', 'password'); $remember = $request->filled('remember'); if (Auth::attempt($credentials, $remember)) { return redirect()->intended('dashboard'); } } ``` Under the hood, Laravel generates a unique string, stores a hashed version in your `users` table's `remember_token` column, and sends an encrypted cookie to the browser. If the session expires, the framework automatically re-authenticates the user using this token. Token-Based Auth with Sanctum Mobile apps and SPAs require a stateless approach. Laravel Sanctum serves as the industry standard here. It issues a plain-text token upon login that the client must store and include in every subsequent request header. To issue a token, verify the user's credentials manually using the `Hash::check` facade, then invoke `createToken` on the user model: ```php $user = User::where('email', $request->email)->first(); if ($user && Hash::check($request->password, $user->password)) { return ['token' => $user->createToken('api-token')->plainTextToken]; } ``` Guarding API Routes Protecting these endpoints requires the `auth:sanctum` middleware in your `api.php` file. This tells Laravel to ignore traditional sessions and instead look for a `Bearer` token in the `Authorization` header. When a user logs out, calling `$user->currentAccessToken()->delete()` instantly invalidates that specific token in the database, ensuring immediate revocation across all devices.

Overview Authentication serves as the gatekeeper for your application, ensuring only identified users access private data or perform sensitive actions. In Laravel, session-based authentication provides a seamless, secure way to manage state across requests. It works by generating a unique session ID stored in a browser cookie, which the server maps to a specific user record in the database. This method is highly recommended for traditional HTML front-ends where security and ease of implementation are paramount. Prerequisites To follow this guide, you should have a baseline understanding of PHP and the Laravel framework. You should be familiar with MVC patterns, MySQL databases, and how to run basic terminal commands using Laravel Sail. Key Libraries & Tools * **Laravel**: The primary PHP framework providing built-in authentication services. * **Laravel Sail**: A Docker-powered CLI for running Laravel applications locally. * **Eloquent ORM**: Handles database interactions and user models. * **Laravel Sanctum**: Mentioned as the go-to package for future token-based API authentication. Code Walkthrough Database Setup and Seeding First, prepare your environment by migrating the user table and seeding it with test data. The database stores passwords as secure hashes, never plain text. ```bash sail artisan migrate --seed ``` Handling the Login Logic Inside your `AuthController`, use the `validator` helper to ensure the user provides a valid email and password. Once validated, call the `auth()->attempt()` method. This method compares the input against the database and automatically manages the session if they match. ```python if (auth()->attempt($request->only('email', 'password'))) { return redirect()->route('dashboard'); } return back()->withErrors(['email' => 'Invalid credentials']); ``` Protecting Routes with Middleware To block unauthenticated access to the dashboard, wrap your routes in the `auth` middleware. This ensures the controller logic never executes unless a valid session exists. ```python Route::get('/dashboard', [DashboardController::class, 'index']) ->middleware('auth'); Route::get('/', function () { return view('login'); })->name('login'); ``` Syntax Notes The `auth()` helper is a powerful shortcut that returns an instance of the `AuthFactory` contract. Additionally, the `withErrors()` method on redirects allows you to pass validation feedback back to the Blade view efficiently. Tips & Gotchas A common mistake is forgetting to name your login route. The `auth` middleware specifically looks for a route named `login` to redirect unauthorized users. If this name is missing, your application will throw an error rather than redirecting properly.

Refining the Starter Kit Experience Laravel recently pushed Jetstream 2.0 to production, marking a significant shift in how the framework handles authentication views. The biggest change involves the Inertia.js stack. While the initial release utilized Blade for login and registration to avoid duplication, the community demanded a more unified Vue.js experience. Jetstream 2.0 delivers this by rewriting all authentication views as native Vue pages. Beyond the UI, team management received a vital upgrade: developers can now invite users who don't yet have an account via email, removing a major friction point in the user onboarding flow. Collaborative Infrastructure with Forge Circles For teams managing infrastructure, Laravel Forge introduced a long-awaited update to its Circle feature. Historically, only the circle owner could provision new hardware. The latest update allows members to create servers directly within a shared credential, such as DigitalOcean or AWS. This delegation of power transforms Forge Circles from a simple viewing gallery into a true collaborative tool for DevOps teams. The Evolution of Spark and Billing Laravel Spark is undergoing a total architectural pivot. To simplify the tool, non-billing features like API management and two-factor authentication were moved into Jetstream and open-sourced for free. The upcoming Spark release focuses exclusively on subscription billing. Taking inspiration from the Stripe billing portal, the new Spark operates as an isolated panel with its own assets. This decoupling means Spark no longer dictates your application's CSS or JavaScript choices; it ships its own Tailwind CSS and Vue files that remain separate from your main application layout. Future Considerations for React SPAs Taylor Otwell is currently weighing the release of a Next.js and React starter kit. This potential tool would offer a canonical example of a Single Page Application (SPA) authenticating with Laravel Sanctum. While the demand for such a template is high, the decision is complicated by previous community confusion regarding the necessity of starter kits. The goal remains providing a clear path for modern frontend integration without imposing rigid opinions on the core framework.