DEV Community: K. Polash

Building Vendzoo: How I Built a Full Business OS for SMEs — Fraud Detection, 4 Couriers, RFM Engine & More

K. Polash — Sat, 15 Aug 2026 09:31:54 +0000

From COD fraud nightmares to automated intelligence: the story of building a business platform for Bangladesh's e-commerce market.

🎯 The Problem That Started Everything

Picture this.

A small shop owner is managing their online business. They've got WooCommerce for the website, Excel sheets for stock tracking, Pathao open on one phone, Steadfast on another, and Facebook Page orders coming in through DMs. They have a physical notebook for customer history, and absolutely no way to know if a new customer is a fraudster who'll refuse the delivery.

Every morning starts with copy-pasting order details from three different places. Every afternoon is spent manually messaging courier agents. Every evening is reconciling which orders got delivered, which got returned, and how much money actually came in.

This isn't a unique story. This is the daily reality of thousands of SME owners, retailers, and e-commerce merchants.

I built Vendzoo to end this chaos.

Vendzoo is an all-in-one SaaS Business OS: POS, Inventory, Courier, Fraud Detection, Customer Intelligence, Marketing, and Analytics, all in one dashboard.
🌐 vendzoo.com

This is the story of how it was built, the real problems we solved, and the decisions that shaped the product.

🏗️ The System at a Glance

Vendzoo is built on Laravel 13 with PHP 8.3, backed by MySQL, with a Tailwind CSS v4 and Vite 8 frontend. Nothing exotic, just a solid, modern stack chosen for reliability and developer ergonomics.

What makes it interesting isn't the stack. It's the three layers sitting on top of it.

The core layer handles POS, orders, inventory, invoicing, and multi-user access with role-based permissions.

The integration layer connects to everything a merchant already uses: WooCommerce, Shopify, Facebook Commerce, Pathao, Steadfast, RedX, Carrybee, Firebase, Telegram, SMS, WhatsApp, and Email.

The intelligence layer is where Vendzoo earns its "Business OS" label: a fraud risk engine, customer segmentation, churn prediction, courier performance analytics, inventory velocity tracking, and full profit & loss reporting. All running automatically in the background.

Chapter 1: The Courier Problem: 4 Companies, 1 Unified System

Bangladesh's e-commerce runs almost entirely on COD (Cash on Delivery). And there are four major courier companies: Pathao, Steadfast, RedX, and Carrybee. Each has its own API, its own authentication system, its own webhook format, and its own quirks.

The tempting approach is to write four separate integrations and treat each courier differently throughout the codebase. We didn't do that.

One Contract, Four Implementations

Every courier in Vendzoo follows the exact same internal contract. Whether the merchant is using Pathao or Carrybee, the rest of the system asks the same question in the same way and gets the same type of answer back. The dashboard doesn't know or care which courier it's talking to.

This means adding a new courier in the future requires writing exactly one new implementation: nothing else in the system needs to change.

Three Delivery Pricing Modes, One Calculator

Different merchants price delivery differently. Some charge a flat rate: ৳60 inside Dhaka, ৳120 outside. Some use weight-based tiers with different prices for different brackets. Some let the courier's own API calculate the charge live based on distance and weight.

A single delivery calculator handles all three modes, knows which to use, and falls back gracefully if the courier API is temporarily unavailable. The merchant configures their preference once. After that, pricing just works, in POS orders, WooCommerce orders, and manual orders alike.

The Webhook Lifecycle

When Pathao delivers an order, or returns it, they notify Vendzoo via webhook. The flow is immediate: the webhook arrives, we identify the courier, we update the order status, we log the update, and we notify the merchant via push notification and Telegram, all within seconds.

We keep each courier's updates in dedicated storage rather than one mixed log. This makes reporting cleaner and debugging faster. If something's off with Steadfast tracking, you look at Steadfast's data, not a pile of mixed records from all four couriers.

Chapter 2: The Fraud Engine: Protecting Merchants from COD Return Losses

This is the feature I'm proudest of.

Why COD Fraud Hurts More Than People Realize

When a customer refuses a COD delivery, the merchant doesn't just miss the sale. They absorb the outbound delivery fee, the return delivery fee, the COD handling charge, and sometimes the cost of damaged packaging, on top of the lost inventory value. Do this a few hundred times a month, and it becomes a serious financial problem.

The frustrating part is that these risky customers are often repeat offenders. The same phone number that refused delivery on three other merchants' orders will show up as a fresh "new customer" on your store, with no visible history.

A Three-Pillar Risk Score

Every order in Vendzoo receives a Unified Risk Score from 0 to 100, built from three independent signals that we combine with different weightings.

The first signal is the customer's delivery success rate within your own store. If they've placed multiple orders with you and consistently accepted delivery, that's a strong positive signal. If they've returned or refused most of their orders, that weight pulls the score down.

The second signal comes from an external courier fraud database that tracks delivery behavior across many merchants and platforms, not just yours. A customer who is completely new to your store might have a well-documented history of refusing deliveries elsewhere. This cross-platform view is what makes the score meaningfully different from just checking your own records.

The third signal is a basic consistency check: does the phone number on the customer's profile match the phone number on the shipping address? A mismatch is a small red flag. Fraud attempts often involve different contact numbers at different stages.

A combined score above 80 is low risk. The 50–80 range is medium, proceed with awareness. Below 50 triggers an instant alert to the merchant before the parcel is dispatched.

What Happens When the External Service Goes Down?

This was one of the most important design decisions in the entire system. External APIs go down. Servers have outages. Networks have timeouts.

If the fraud data service is unavailable, Vendzoo doesn't block orders or throw errors. It falls back in layers: first to recent cached data for that phone number, then to older cached data marked as stale, and finally to a neutral mid-range score if nothing is cached at all. The merchant always gets a result. The order always flows. The system is never hostage to a third-party outage.

Preventing Duplicate Alerts Under Load

Here's a subtle problem: if two background workers pick up the same high-risk order at the same moment, the merchant could receive two identical "HIGH RISK!" alerts. Confusing and unprofessional.

The fix is an atomic database update. The first worker to record the notification wins. The second worker checks, sees it's already been recorded, and exits quietly. No matter how many workers are running in parallel, exactly one notification goes out, guaranteed at the database level, not just in application logic.

Chapter 3: Customer Intelligence: Knowing Who Your Customers Really Are

Every merchant has the same questions, but almost none of them have good answers: Who are my most loyal customers? Who bought once and never came back? Who is about to churn? Who should I send a win-back offer to right now?

Vendzoo builds answers to all of these automatically, without the merchant lifting a finger.

RFM: A Framework That's Stood the Test of Time

RFM stands for Recency, Frequency, and Monetary value. It's a customer segmentation method that's been used in direct marketing for decades, and it remains one of the most practical and interpretable frameworks for understanding customer behavior.

Recency measures how recently a customer placed their last order. A customer who ordered yesterday is more engaged than one who ordered eight months ago, even if the older customer's total spend is higher.

Frequency counts how many successful deliveries a customer has completed. Repeat buyers who consistently accept delivery are a fundamentally different category from one-time buyers, even if the one-time buyer spent more on that single order.

Monetary tracks the total revenue generated from completed orders. This filters out the customers who order often but return often too; only successfully delivered orders contribute to the monetary score.

Each dimension gets a score, and the combined result automatically places every customer into a persona: Champions, Loyal Customers, At Risk, Big Spenders, Promising, Hibernating, High Return Risk, or Lost. These labels update in the background continuously, so when a merchant opens their customer list, they immediately see who needs attention and who deserves a reward.

Churn Prediction Without Machine Learning

Separately from the RFM segmentation, Vendzoo runs a lightweight churn prediction based on a simple principle: the longer since a customer's last order, the higher the probability they've moved on.

Customers who haven't ordered in over a month get flagged as potentially at risk. Those who've gone quiet for 60 days are hibernating. At 90 days, they're classified as lost. These aren't predictions from a trained model; they're clear, explainable thresholds that work well for the SME context and can be acted on directly without a data scientist in the loop.

Chapter 4: Inventory Intelligence: Smarter Stock Management

Sales Velocity

Vendzoo tracks the average number of units sold per day for every product, what's commonly called sales velocity. It's derived from historical sales movement data, calculated automatically, and updated daily.

The value of knowing velocity is simple: a product selling 15 units a day has completely different restocking needs than one selling 3 units a week. Without this number, merchants either reorder too late (stockouts) or too early (cash tied up in dead inventory).

When to Reorder: Suggested Automatically

Using sales velocity together with the typical lead time to receive new stock, Vendzoo suggests a reorder threshold for each product. When current stock drops to that threshold, it's time to reorder, not when stock hits zero. The buffer accounts for the days it takes new stock to arrive and a small safety cushion for demand spikes.

These suggestions appear on the inventory dashboard without any configuration from the merchant. The system calculates them fresh in the background every day, invisibly.

Built for Scale from the Start

One early performance mistake was calculating velocity for each product one at a time: a separate database query per SKU. With 10 products in development, this was fine. In production with a merchant managing 2,000 SKUs, it became a serious bottleneck.

The fix was restructuring the calculation to aggregate data for all products in a single database query, then distribute the results. The math is identical; the number of queries dropped from 2,000 to 1. This now runs entirely in the background, finishing long after the merchant's page has loaded, with zero impact on their experience.

Chapter 5: Courier Intelligence: Which Courier Actually Performs Best for You?

Every merchant has a preferred courier. Most of those preferences are based on gut feel, past complaints, or a colleague's recommendation, not data.

Vendzoo builds the data view instead. For every courier a merchant has ever used, it calculates the actual delivery success rate broken down by destination area, using the merchant's own real order history, not industry averages or courier marketing materials.

If a merchant has shipped 200 orders to Chittagong with RedX and 180 were delivered, that's a 90% success rate for that courier in that area. If Pathao handled 150 orders to the same area with 105 deliveries, that's 70%. The recommendation is clear, and it's built entirely from the merchant's own data, no external API required.

Chapter 6: WooCommerce & Shopify: One Dashboard, All Channels

Many Bangladesh merchants have both an online store and a physical shop. The inventory nightmare: the website shows 10 units in stock, but 8 were already sold at the counter this morning.

Vendzoo solves this by treating all channels as part of the same inventory pool. When an order is placed on WooCommerce, stock is deducted from the same pool that POS orders use. When a Shopify order syncs, the same thing. There's one source of truth, and every channel reads from and writes to it.

When a WooCommerce Order Arrives

A customer places an order on the website. Within seconds, the webhook reaches Vendzoo: we check for duplicates, find or create the customer by phone number, resolve the delivery charge, create the order in the Vendzoo dashboard, deduct stock, and notify the merchant. From that point on, the merchant handles everything in Vendzoo: booking the courier, updating status, managing returns. The WooCommerce dashboard becomes unnecessary for day-to-day operations.

Shopify at Scale

Syncing inventory to Shopify for a merchant with thousands of products can't be done in one shot: it'll time out. Vendzoo breaks the sync into small batches and processes each batch as a separate background job. If one batch fails due to a network issue or API rate limit, only that batch retries, not the entire catalog.

Chapter 7: Marketing Automation: Targeted, Not Broadcast

Most merchant marketing is the same blast to everyone: "20% off this weekend!" Vendzoo makes it possible to do something much more effective: send the right message to the right customer at the right moment.

Because every customer already has an RFM badge, merchants can build campaigns that target specific segments. A win-back campaign can go exclusively to customers who haven't ordered in over 45 days. A loyalty reward can target Champions and Loyal Customers only. High Return Risk customers can be excluded from all outgoing campaigns automatically.

The audience builds itself. The merchant writes the message and picks the segment.

Behind the scenes, campaigns use a dedicated queue channel, enforce rate limits per messaging provider, and retry failed sends with increasing delays: 30 seconds, then 2 minutes, then 5 minutes. Campaign sending also pauses automatically after 10 pm to respect customer boundaries, and resumes the next morning.

If a merchant manually triggers a campaign at the exact same moment a scheduled send fires, the system ensures only one dispatch happens, through an atomic lock at the database level that prevents any double-sending.

Chapter 8: Real-Time Notifications

Merchants need to know about new orders and delivery updates the instant they happen, not on their next login.

Vendzoo supports push notifications through Firebase and message delivery through Telegram. Connecting Telegram is a one-tap flow: the merchant gets a unique time-limited link, taps it, and their Telegram account is permanently linked. Every important event (new order, parcel delivered, high-risk alert) arrives as a Telegram message in addition to a push notification.

The Firebase integration is built without any heavyweight SDK dependency: a lightweight custom implementation that handles token caching and minimizes unnecessary API calls.

Chapter 9: Order Lifecycle: A State Machine That Prevents Mistakes

Orders in Vendzoo follow a defined lifecycle, and transitions between states are enforced by the system itself. You can't mark an order as returned without it having been delivered first. You can't skip from pending to completed in a delivery order. The only transitions the UI shows are the ones that are actually valid from the current state.

For takeaway (POS) orders, the flow is simple: Pending to Completed, with Cancelled and On Hold as side paths.

For delivery orders, the full path runs from Pending through Confirmed, Ready to Ship, In Courier, Delivered, and finally Completed, with Returned, On Hold, and Cancelled available at the right stages.

The result is data that's always logically consistent. Reporting is clean. Status histories make sense. There's no way to accidentally create an order that's "delivered but was never with a courier."

Chapter 10: Subscriptions: Feature Limits Done Right

Locking In What You Signed Up For

When a merchant subscribes to a plan, Vendzoo takes a snapshot of that plan's limits and locks them to the subscription. If an admin later changes the plan's limits for new subscribers, existing merchants are unaffected, they keep what they signed up for, for the duration of their subscription.

This matters for trust. Merchants shouldn't wake up to find they've exceeded limits on a plan they've been paying for, because someone changed the rules without them.

Upgrading Without Losing Your History

When a merchant upgrades to a higher-tier plan, their existing usage counts carry over correctly. A merchant who had 90 products on their previous plan doesn't get a "free" reset to zero products used when they upgrade: the 90 transfers to the new plan's higher limit. Small detail, but it closes a loophole that would otherwise let merchants game usage tracking.

What Vendzoo Has Become

What started as an attempt to replace a few Excel sheets has grown into something much larger: 76 data models, 35 service classes, 31 background jobs, four courier integrations, three e-commerce platform connections, and five notification channels, all working together in a system that feels simple to use because the complexity is fully hidden.

The stack is Laravel 13 with PHP 8.3, Tailwind CSS v4, Vite 8, Pest PHP 4 for testing, and Sentry for production monitoring. The development environment starts with a single command that concurrently runs the server, frontend hot-reload, queue worker, and log viewer in one terminal window.

The product is live. Real merchants use it daily. And there's still a long roadmap ahead: a mobile app, bKash and Nagad payment gateway integration, automated COD remittance reconciliation, and multi-currency support for cross-border selling.

Try Vendzoo

🌐 vendzoo.com

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.