Forem: K. Polash

Why Your System Fails on the Most Predictable Day of the Year

K. Polash — Wed, 01 Apr 2026 16:30:00 +0000

Most applications don't fail because of bad code.

They fail because of bad architecture decisions made early that nobody questioned
until it was too late.

Here's what actually breaks systems at scale:

Everything talking to everything (no clear boundaries)
The database doing work the application should do
Synchronous processing where async was needed
One giant service that owns too much responsibility
No separation between reads and writes under heavy load

None of these are framework problems. None of these are language problems.
They are thinking problems.

The Scenario: University Enrollment Day

Think about course enrollment day at any university.

Every semester, thousands of students flood the portal at the exact same time, each trying to register for their courses. The load is not a surprise. The date is on the calendar. It happens every single semester like clockwork.

But the system was never designed for it.

Every request hits the same flow — check eligibility, check seat availability, write enrollment, update seat count — all synchronously, all at once. No queue. No cache. No separation between reads and writes. Just a database choking under the weight of an entirely predictable moment.

Students get timeout errors. Duplicate enrollments. Lost seats they were fully eligible for. Everyone refreshes in panic. And every semester, someone calls IT to "increase the server capacity" and nothing really changes.

The code isn't broken. The thinking is.

What's Actually Going On

Most teams look at this and see one problem: too much traffic. So they throw more servers at it. It helps a little, then fails again next semester.

The reality is there are 5 separate problems here, each requiring a different solution. Solving one without the others just moves the failure to a different place.

🔥 The Spike

Thousands of simultaneous requests will bring any database to its knees regardless of hardware. A queue, a cache layer, and read/write separation need to work together. Most teams implement one and call it done.

🔁 The Race Condition

Even with a queue, two workers can read "1 seat available" at the same time, both pass eligibility, and both enroll into the last seat. The queue serialized intake. It did not serialize processing. You need locking — pessimistic, optimistic, or distributed — and each has real tradeoffs.

👆 The Double Click

A student hits Enroll and the page is slow. They click again. Now two identical requests are in flight. Even with locking in place, without idempotency handling both clicks can create two enrollment records. This is not a database problem. It is an API design problem — and the one most teams discover only after finding duplicate records in production.

💥 The Half-Enrolled Student

A successful enrollment is not one database write. It is a chain: write the record, decrement the seat count, send confirmation, update the academic record, generate a fee entry. What happens if the system crashes after step 2?

The seat is taken. The student has no confirmation. The database says enrolled. The academic record disagrees. Designing for the middle of failure is architecture. Designing only for the happy path is wishful thinking.

🕳️ The Stale Cache Trap

The cache says 5 seats available. The database already has 0. Students attempt to enroll based on stale data, hit the lock, fail, and get a confusing error even though the portal showed availability 3 seconds ago. The cache improved performance but silently introduced a trust problem. Cache invalidation strategy needs to be designed upfront, not patched after support tickets pile up.

The Questions That Actually Matter

The engineers who scale systems well ask different questions from the start:

Where are my bottlenecks under 10x load?
What happens if this one service goes down?
Am I coupling things that should be independent?
What happens in the middle of a failure, not just at the end?
Can the same request safely arrive twice?

None of these have anything to do with which framework you picked or which cloud provider you use. They are design questions. Thinking questions.

I wrote a full deep dive on all 5 problems with concrete solutions for each one.

👉 Read the full article here →

Architecture is not about knowing the right tools. It is about asking the right questions early enough that the answers still matter.

Laravel Queue vs defer(): When to Use Each (Laravel 11, 12 & 13)

K. Polash — Mon, 30 Mar 2026 06:48:29 +0000

Laravel 11 quietly introduced one of the most practical helpers in years: defer().

It lets you run code after the HTTP response has been sent — no queue worker, no Redis, no Supervisor config. Just:

defer(fn () => Metrics::recordOrder($order));

The user gets the response instantly. The closure runs after. Zero extra infrastructure.

But a lot of developers are either ignoring it or misusing it. So here's the honest breakdown.

The One-Line Rule

defer() → "I'm okay if this is lost on a crash"
Queue Job → "This must succeed, and retry if it fails"

What defer() actually does

Runs a closure in the same PHP process, after the HTTP response is sent.

use function Illuminate\Support\defer;

Route::post('/orders', function (Request $request) {
    $order = Order::create($request->validated());

    defer(fn () => Metrics::recordOrder($order)); // fires AFTER response

    return response()->json($order, 201); // returned immediately
});

Key behaviours:

Skips execution if the response is a 4xx or 5xx (use ->always() to override)
Can be named and cancelled: defer(fn () => ..., 'name') + defer()->forget('name')
Doesn't survive a server crash — not persisted anywhere

Version support: Laravel 11+ only. Not available in Laravel 10 or earlier.

Quick Comparison Table

Feature	Queue Job	defer()
Needs queue worker	✅ Yes	❌ No
Needs Redis / DB driver	✅ Yes	❌ No
Persisted to storage	✅ Yes	❌ No
Retries on failure	✅ Yes	❌ No
Delayed execution	✅ Yes	❌ No
Monitoring (Horizon)	✅ Yes	❌ No
Zero setup	❌ No	✅ Yes
Runs after response	separate process	✅ same process

Use defer() for:

Recording analytics after an order
Incrementing page view / "last seen" counters
Busting a cache key after a resource is created
Non-critical internal Slack notifications
Lightweight audit trail writes

Use Queue Jobs for:

Transactional emails (must not be lost)
Payment webhooks and API calls (must retry)
Image/file processing (CPU heavy)
Delayed tasks ("send reminder in 24 hours")
Anything monitored via Horizon or Telescope

⚠️ The Swoole Gotcha

If you use Swoole or FrankenPHP, always import Laravel's defer() explicitly:

// WRONG on Swoole — calls Swoole's defer(), not Laravel's
defer(fn () => Metrics::record($data));

// CORRECT
use function Illuminate\Support\defer;
defer(fn () => Metrics::record($data));

Swoole has its own global defer(). The conflict is silent and will cost you hours.

Testing Deferred Functions

public function test_order_records_metrics(): void
{
    $this->withoutDefer(); // runs deferred closures immediately

    Metrics::shouldReceive('recordOrder')->once();

    $this->postJson('/api/orders', ['product_id' => 1, 'qty' => 2])
         ->assertStatus(201);
}

Full post

For the full decision guide (including the 8-question decision matrix, Laravel 13 notes, and full code examples):

👉 pola5h.github.io/blog/laravel-queue-vs-defer/

What do you use defer() for in your projects? Drop it in the comments 👇

Laravel 13 drops March 17 — here's every new feature with code examples

K. Polash — Sun, 08 Mar 2026 15:11:16 +0000

Laravel 13 is 9 days away. Taylor Otwell announced it at Laracon EU 2026 and the headline is: zero breaking changes. Smoothest upgrade in Laravel's history.

Here's everything that's changing, with before/after code for the features that actually matter day-to-day.

PHP 8.3 is now the minimum

First the housekeeping. Laravel 13 drops PHP 8.2 support. Check your version:

php -v

If you're on 8.2, upgrade your server before upgrading Laravel. Everything else in this list is non-breaking and optional.

1. PHP Attributes — the headline feature

This is the one everyone will be talking about. Instead of declaring model config, job settings, and command signatures as class properties, you can now use native PHP #[Attribute] syntax.

Models — before:

class Invoice extends Model
{
    protected $table = 'invoices';
    protected $primaryKey = 'invoice_id';
    protected $keyType = 'string';
    public $incrementing = false;
    protected $fillable = ['amount', 'status', 'user_id'];
    protected $hidden = ['internal_notes'];

    // actual model logic starts way down here...
}

Models — after:

#[Table('invoices', key: 'invoice_id', keyType: 'string', incrementing: false)]
#[Fillable('amount', 'status', 'user_id')]
#[Hidden('internal_notes')]
class Invoice extends Model
{
    // your real logic is immediately visible
}

Jobs — before:

class ProcessPayment implements ShouldQueue
{
    public $connection = 'redis';
    public $queue = 'payments';
    public $tries = 3;
    public $timeout = 60;
}

Jobs — after:

#[WithQueue(connection: 'redis', queue: 'payments', tries: 3, timeout: 60)]
class ProcessPayment implements ShouldQueue
{
    // queue config declared, not buried
}

Commands — before:

class SendReportCommand extends Command
{
    protected $signature = 'report:send {--force}';
    protected $description = 'Send the weekly report email';
}

Commands — after:

#[Command(signature: 'report:send {--force}', description: 'Send the weekly report email')]
class SendReportCommand extends Command
{
}

This also works on listeners, notifications, mailables, broadcast events, requests — around 15 locations total. And again: fully optional. Your existing code works exactly as before.

2. Cache::touch() — extend TTL without re-fetching

This one's been a quiet performance footgun for years. To extend a cache item's expiry you had to fetch the value, then re-store it:

// Before — 2 round trips, full payload transfer
$value = Cache::get('user_session:123');
Cache::put('user_session:123', $value, now()->addHour());

Laravel 13:

// After — single EXPIRE command to Redis
Cache::touch('user_session:123', 3600);

Under the hood: Redis gets one EXPIRE command. Memcached uses native TOUCH. Database driver runs a single UPDATE. No value retrieval, no payload transfer.

If you're extending TTLs on every request at scale (sliding sessions, rate limit windows, subscription checks) — this adds up fast.

3. Reverb database driver — real-time without Redis

Scaling Laravel Reverb horizontally previously required Redis. Laravel 13 adds a database driver so you can use MySQL or PostgreSQL instead:

'reverb' => [
    'scaling' => [
        'driver' => 'database', // new — no Redis required
    ],
],

For small-to-medium projects that don't want to provision a separate Redis instance just for WebSockets, this is a big deal.

4. Passkey authentication

Passkeys (WebAuthn — Face ID, fingerprint, hardware keys) are now built into Laravel's starter kits and Fortify. No third-party packages. Scaffolded automatically on new Laravel 13 apps.

5. Laravel AI SDK goes stable

The Laravel AI SDK exits beta on March 17 alongside Laravel 13. First-class LLM integration (OpenAI, Anthropic, others) with proper queue support and Laravel-native conventions.

6. Teams support returns to starter kits

Jetstream had Teams. The newer starter kits didn't. Laravel 13 brings it back with a cleaner implementation.

Other improvements worth knowing

MySQL DELETE…JOIN now correctly applies ORDER BY and LIMIT — previously silently ignored
HTTP pool concurrency defaults to 2 instead of null — pooled requests are now actually concurrent out of the box
Symfony 7.4 and 8.0 support

How to upgrade

"require": {
    "php": "^8.3",
    "laravel/framework": "^13.0"
}

composer update
php artisan config:clear
php artisan cache:clear
php artisan view:clear

Make sure PHP 8.3 is running first. Test on staging before touching production.

Full feature breakdown

I wrote a more detailed version with upgrade notes and FAQ on my blog:

👉 Laravel 13 New Features: Everything You Need to Know

Which feature are you most excited about? PHP Attributes are the headline but I think Cache::touch() is the one that will quietly save the most performance at scale. Drop your thoughts below.

The Laravel Sanctum setup that actually works (and what trips most people up)

K. Polash — Sun, 08 Mar 2026 06:47:31 +0000

I've set up Sanctum in probably 8 or 9 Laravel projects at this point — payroll systems, SaaS tools, e-commerce APIs. Every time I onboard a junior dev or review someone's code, I see the same 3-4 mistakes repeated. So here's the setup that works, plus the exact things that will silently break it.

First: what Sanctum actually does

Sanctum issues a plain-text token, stores a hashed version in your personal_access_tokens table, and validates it on every request with a database lookup. That's it. No JWT, no signatures, no decoding — just a DB row.

This is why token revocation is trivially easy with Sanctum and nightmarish with JWT. Delete the row, the token is dead instantly.

The setup (Laravel 12)

Step 1 — Install (Laravel 10 and below only)

Laravel 11 and 12 ship with Sanctum already. If you're on 10:

composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

Step 2 — Add the trait to your User model

This is the one people forget most often:

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
}

Without this, createToken() doesn't exist on your model, and you'll get a cryptic error.

Step 3 — Routes

Route::prefix('v1')->group(function () {

    // Public
    Route::post('auth/register', [AuthController::class, 'register']);
    Route::post('auth/login',    [AuthController::class, 'login']);

    // Protected
    Route::middleware('auth:sanctum')->group(function () {
        Route::post('auth/logout', [AuthController::class, 'logout']);
        Route::get('auth/me',     [AuthController::class, 'me']);
    });

});

Step 4 — The AuthController

public function login(Request $request)
{
    $request->validate([
        'email'    => 'required|email',
        'password' => 'required',
    ]);

    if (! Auth::attempt($request->only('email', 'password'))) {
        return response()->json(['message' => 'Invalid credentials'], 401);
    }

    $token = Auth::user()->createToken('auth_token')->plainTextToken;

    return response()->json([
        'user'  => Auth::user(),
        'token' => $token,
    ]);
}

public function logout(Request $request)
{
    $request->user()->currentAccessToken()->delete();
    return response()->json(['message' => 'Logged out']);
}

Step 5 — Send the token

Authorization: Bearer 1|yourtokenhere...

Note the format — 1|randomstring. The number is the token ID in the database. Send the full string.

The 4 things that will silently break your setup

1. Forgetting HasApiTokens on the User model
You'll get a "method not found" error on createToken(). Always check this first.

2. Sending the token wrong
It must be Authorization: Bearer YOUR_TOKEN. Not a query param, not a cookie, not Token YOUR_TOKEN. Bearer, exactly.

3. Not running migrations
The personal_access_tokens table doesn't exist yet. Run php artisan migrate and confirm the table is there.

4. CORS blocking your frontend
Add your frontend URL to config/cors.php:

'allowed_origins'      => ['https://yourfrontend.com'],
'supports_credentials' => true,

Revoking tokens

This is where Sanctum shines vs JWT:

// Logout current device
$request->user()->currentAccessToken()->delete();

// Logout all devices
$user->tokens()->delete();

With JWT, you'd need a denylist and extra infrastructure. With Sanctum, it's one line.

Setting token expiry

In config/sanctum.php:

// Expire after 60 days (value is in minutes)
'expiration' => 60 * 24 * 60,

// Never expire
'expiration' => null,

Should you use Sanctum or JWT?

Use Sanctum if you're building an API for your own app (SPA, mobile). Use JWT only if you need stateless cross-service auth in a microservices setup. For 90% of Laravel projects, Sanctum is the right call.

I wrote a full breakdown here: Does Laravel Sanctum use JWT? →

Full tutorial

If you want the complete version with register, me endpoint, token abilities, and more — I wrote it up here:

👉 Laravel Sanctum Setup Tutorial (2026)

Already using Sanctum?

I built a Laravel API Starter Kit with Sanctum pre-configured — auth, roles, pagination, API versioning all included. Saves a few hours on every new project. $19 on Gumroad if you want to check it out.

What issues have you run into with Sanctum? Drop them below — happy to help debug.

blade-flags gives you SVG rectangles. This gives you flags users actually recognize.

K. Polash — Fri, 06 Mar 2026 03:57:03 +0000

There's already a popular Laravel flag package. outhebox/blade-flags has 663k installs, and it works fine.

So why did I build another one?

Because SVG rectangular flags and emoji flags solve different problems — and most Laravel apps actually need the emoji version.

The difference nobody talks about

When your user sees this in your app:

<x-flag-icon type="country" code="bd" width="24px" />

They see: 🇧🇩

That's the flag they see in WhatsApp. In Twitter. In their phone keyboard. In every modern app, they use it daily. Their brain recognizes it in zero milliseconds.

blade-flags renders a tiny rectangular SVG of the Bangladeshi flag — accurate, technically correct, and completely unfamiliar to most users. It looks like something from a government website.

Emoji flags match the visual language of the modern web. SVG flags don't.

When does this actually matter?

If you're building a developer tool or admin dashboard — use blade-flags. SVG flags look sharp and professional at small sizes in dense UIs.

If you're building anything user-facing — locale switchers, user profiles, country selectors, chat apps, language pickers — use Twemoji flags. Users recognize them instantly. That recognition reduces friction.

The mental model test: your user doesn't think "ISO 3166-1 alpha-2 code for Bangladesh." They think 🇧🇩. Build for that.

Installation

composer require pola5h/laravel-flags

Auto-registered on Laravel 5.5+. No config publishing, no setup. Done.

Usage

{{-- Country flag --}}
<x-flag-icon type="country" code="us" width="24px" height="24px" />

{{-- Language flag --}}
<x-flag-icon type="language" code="bn" width="24px" height="24px" />

Two parameters that matter: type (country or language) and code (ISO 2-letter code). Width and height are optional — they default to auto.

Country flags

Any ISO 3166-1 alpha-2 code works:

<x-flag-icon type="country" code="us" width="20px" /> 🇺🇸 United States
<x-flag-icon type="country" code="gb" width="20px" /> 🇬🇧 United Kingdom
<x-flag-icon type="country" code="bd" width="20px" /> 🇧🇩 Bangladesh
<x-flag-icon type="country" code="de" width="20px" /> 🇩🇪 Germany
<x-flag-icon type="country" code="jp" width="20px" /> 🇯🇵 Japan

Dynamic usage from a model:

<x-flag-icon type="country" code="{{ $user->country_code }}" width="20px" />

250+ countries supported.

Language flags

Language flags map to the country most associated with that language. Bengali → Bangladesh, Arabic → Saudi Arabia, French → France.

<x-flag-icon type="language" code="en" width="20px" /> English
<x-flag-icon type="language" code="bn" width="20px" /> Bengali
<x-flag-icon type="language" code="ar" width="20px" /> Arabic
<x-flag-icon type="language" code="zh" width="20px" /> Chinese
<x-flag-icon type="language" code="fr" width="20px" /> French

Dynamic with the current app locale:

<x-flag-icon type="language" code="{{ app()->getLocale() }}" width="20px" />

100+ languages supported.

The use case I built this for: locale switchers

This is where the difference is most visible. A locale switcher with SVG flags feels like a dropdown from 2012. With Twemoji flags it feels native — like switching language on your iPhone.

@foreach ($availableLocales as $locale)
    <a href="{{ route('locale.switch', $locale) }}"
       class="{{ app()->getLocale() === $locale ? 'active' : '' }}">
        <x-flag-icon
            type="language"
            code="{{ $locale }}"
            width="18px"
            height="18px"
        />
        {{ strtoupper($locale) }}
    </a>
@endforeach

Clean, familiar, instant recognition.

Side-by-side comparison

	`pola5h/laravel-flags`	`outhebox/blade-flags`
Flag style	Twemoji emoji 🇧🇩	SVG rectangular
Best for	User-facing UI	Admin/dev tools
Countries	250+	300+
Language flags	✅ Yes	❌ No
Zero config	✅ Yes	✅ Yes
License	MIT	MIT
Installs	New	663k

The one thing blade-flags doesn't have at all: language flags. If you need to show a flag for Bengali, Arabic, or French — not the country, but the language — this package is currently your only option in the Laravel ecosystem.

How I Structure Every Laravel REST API Project

K. Polash — Thu, 05 Mar 2026 15:14:53 +0000

Every time I start a new Laravel API project, I used to spend half a day on the same setup:

Sanctum authentication
Spatie roles & permissions
Consistent JSON error responses
API versioning
Rate limiting

After doing this on project after project, I finally settled on a structure that works every time. Here's exactly how I do it.

1. Consistent JSON Response Format

The first thing I set up is a trait that forces every endpoint to return the same JSON structure. Nothing is more annoying than an API that returns different formats for success vs errors.

<?php

namespace App\Traits;

trait ApiResponseTrait
{
    public function successResponse($data, $message = 'Success', $statusCode = 200)
    {
        return response()->json([
            'success' => true,
            'message' => $message,
            'data'    => $data,
            'meta'    => [
                'version'   => 'v1',
                'timestamp' => now()->toISOString(),
            ],
        ], $statusCode);
    }

    public function errorResponse($message = 'Error', $statusCode = 400, $errors = [])
    {
        return response()->json([
            'success' => false,
            'message' => $message,
            'errors'  => $errors,
            'meta'    => [
                'version'   => 'v1',
                'timestamp' => now()->toISOString(),
            ],
        ], $statusCode);
    }

    public function notFoundResponse($message = 'Resource not found')
    {
        return $this->errorResponse($message, 404);
    }

    public function unauthorizedResponse($message = 'Unauthorized')
    {
        return $this->errorResponse($message, 401);
    }

    public function validationErrorResponse($errors, $message = 'Validation failed')
    {
        return $this->errorResponse($message, 422, $errors);
    }
}

Every controller uses this trait. No more inconsistent responses.

2. Global Exception Handler

Instead of handling exceptions in every controller, I catch everything in one place.

<?php

namespace App\Exceptions;

use Illuminate\Auth\AuthenticationException;
use Illuminate\Database\Eloquent\ModelNotFoundException;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Throwable;

class Handler extends ExceptionHandler
{
    public function render($request, Throwable $exception)
    {
        if ($request->expectsJson()) {

            if ($exception instanceof ModelNotFoundException) {
                return response()->json([
                    'success' => false,
                    'message' => 'Resource not found',
                ], 404);
            }

            if ($exception instanceof AuthenticationException) {
                return response()->json([
                    'success' => false,
                    'message' => 'Unauthenticated',
                ], 401);
            }

            if ($exception instanceof ValidationException) {
                return response()->json([
                    'success' => false,
                    'message' => 'Validation failed',
                    'errors'  => $exception->errors(),
                ], 422);
            }

            if ($exception instanceof NotFoundHttpException) {
                return response()->json([
                    'success' => false,
                    'message' => 'Route not found',
                ], 404);
            }
        }

        return parent::render($request, $exception);
    }
}

Now every exception returns clean JSON automatically — no more ugly HTML error pages in your API.

3. API Versioning Structure

I always separate routes and controllers by version. This way future changes don't break existing clients.

app/Http/Controllers/Api/
├── V1/
│   ├── AuthController.php
│   └── UserController.php
└── V2/  ← ready for the future

In routes/api.php:

use App\Http\Controllers\Api\V1\AuthController;
use App\Http\Controllers\Api\V1\UserController;

Route::prefix('v1')->group(function () {

    // Public auth routes
    Route::prefix('auth')->middleware('throttle:auth')->group(function () {
        Route::post('register', [AuthController::class, 'register']);
        Route::post('login',    [AuthController::class, 'login']);
    });

    // Protected routes
    Route::middleware('auth:sanctum')->group(function () {
        Route::post('auth/logout',  [AuthController::class, 'logout']);
        Route::get('auth/me',       [AuthController::class, 'me']);
        Route::get('users',         [UserController::class, 'index']);
    });

});

Clean, versioned, easy to extend.

4. Sanctum Authentication

I use Laravel Sanctum for all API authentication. Here's a clean AuthController:

<?php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Http\Requests\Api\LoginRequest;
use App\Http\Requests\Api\RegisterRequest;
use App\Models\User;
use App\Traits\ApiResponseTrait;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Hash;

class AuthController extends Controller
{
    use ApiResponseTrait;

    public function register(RegisterRequest $request)
    {
        $user = User::create([
            'name'     => $request->name,
            'email'    => $request->email,
            'password' => Hash::make($request->password),
        ]);

        $user->assignRole('user');

        $token = $user->createToken('api-token')->plainTextToken;

        return $this->successResponse([
            'user'  => $user,
            'token' => $token,
        ], 'Registration successful', 201);
    }

    public function login(LoginRequest $request)
    {
        if (!Auth::attempt($request->only('email', 'password'))) {
            return $this->unauthorizedResponse('Invalid credentials');
        }

        $user  = Auth::user();
        $token = $user->createToken('api-token')->plainTextToken;

        return $this->successResponse([
            'user'  => $user,
            'token' => $token,
        ], 'Login successful');
    }

    public function logout(Request $request)
    {
        $request->user()->currentAccessToken()->delete();
        return $this->successResponse(null, 'Logged out successfully');
    }

    public function me(Request $request)
    {
        return $this->successResponse(
            $request->user()->load('roles', 'permissions')
        );
    }
}

5. Spatie Roles & Permissions

I always use spatie/laravel-permission for roles. Here's my seeder:

<?php

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Spatie\Permission\Models\Permission;
use Spatie\Permission\Models\Role;

class RolePermissionSeeder extends Seeder
{
    public function run(): void
    {
        // Create permissions
        $permissions = [
            'view users',
            'edit users',
            'delete users',
            'manage roles',
        ];

        foreach ($permissions as $permission) {
            Permission::firstOrCreate(['name' => $permission]);
        }

        // Create roles and assign permissions
        $admin = Role::firstOrCreate(['name' => 'admin']);
        $admin->syncPermissions($permissions);

        $editor = Role::firstOrCreate(['name' => 'editor']);
        $editor->syncPermissions(['view users', 'edit users']);

        Role::firstOrCreate(['name' => 'user']);
    }
}

Run php artisan db:seed --class=RolePermissionSeeder and you have a full role system ready.

6. Rate Limiting

In app/Providers/RouteServiceProvider.php:

RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});

RateLimiter::for('auth', function (Request $request) {
    return Limit::perMinute(10)->by($request->ip());
});

Stricter limits on auth routes to prevent brute force. General API routes get 60 requests per minute.

The Result

Every response from my API looks like this:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "roles": ["admin"],
    "permissions": ["view users", "edit users"]
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-03-05T10:00:00Z"
  }
}

Clean, consistent, predictable. Every endpoint. Every time.

Wrapping Up

This structure took me several projects to settle on. The key principles are:

One response format — use a trait, enforce it everywhere
One place for exceptions — global handler, not per-controller
Version from day one — you'll thank yourself later
Roles from day one — adding them later is painful

If you don't want to set all this up manually, I packaged everything into a ready-to-use starter kit — migrations, seeders, controllers, Postman collection, and README all included.

👉 Laravel API Starter Kit

What does your Laravel API structure look like? I'd love to hear how others approach this in the comments.