As Laravel applications grow, passing arrays between controllers and services can make code harder to understand and maintain. Services may depend on loosely defined data structures, and developers may struggle to determine which fields an operation actually requires.

This is where DTOs (Data Transfer Objects) become useful.

DTOs help you define clear data contracts between different parts of your application. Instead of passing an entire HTTP request or an unstructured array, you can pass an object that explicitly represents the required data.

In this article, we’ll explore:

• What a DTO is and why it matters.

• The benefits and limitations of using DTOs.

• How to implement a DTO in Laravel using a student registration example.

• How to integrate DTOs with Laravel validation and services.

• How Spatie Laravel Data simplifies DTO implementation.

• When to choose plain PHP DTOs versus Spatie Laravel Data.

Let’s get started.

📨 What Is a DTO?

A Data Transfer Object (DTO) is an object designed to carry data between different parts of an application.

Its primary responsibility is to define the structure of the data being transferred, rather than perform the business operation itself.

Consider a student registration application built with Laravel.

When a student registers for a course, the application might need the following information:

• Student name

• Email address

• Age

• Course ID

We could pass this information as an associative array:

$studentData = [
    'name' => 'Rahul Sharma',
    'email' => 'rahul@example.com',
    'age' => 21,
    'course_id' => 1,
];

This works, but the expected structure is implicit. Nothing in the array itself tells us which fields are mandatory or what types they should have.

We can represent the same information using a DTO:

$studentData = new StudentRegistrationData(
    name: 'Rahul Sharma',
    email: 'rahul@example.com',
    age: 21,
    courseId: 1,
);

Now the data is represented by a defined class with explicitly named properties and types.

The key idea: A DTO makes the data contract explicit and provides a structured way to transfer data between application layers.

💡 Why Do We Need DTOs in Laravel?

Laravel makes it easy to access request data:

$request->input('name');
$request->input('email');

For a simple CRUD operation, this may be sufficient.

However, as an application grows, controllers and services can become tightly coupled to HTTP requests or depend on arrays with inconsistent structures.

Consider this service method:

public function register(array $data): Student
{
    // Registration logic
}

What fields does $data require? Is age an integer? Is course_id mandatory? Does the service need the student’s email or the entire request?

The method signature doesn’t tell us.

Now consider this version:

public function register(
    StudentRegistrationData $data
): Student {
    // Registration logic
}

The method explicitly declares the type of data it expects.

DTOs are especially useful when:

• Services contain complex business logic.

• Multiple application components call the same service.

• Data comes from APIs, imports, or external integrations.

• Queued jobs need structured input.

• You want to test services independently of HTTP requests.

• Your application benefits from clear boundaries between layers.

🎯 What Are the Benefits of DTOs?

✅ Clear data contracts

A DTO explicitly defines which fields an operation expects.

Developers can understand the structure of the data by reading the class rather than searching through several controllers and array definitions.

✅ Better separation of concerns

Controllers handle HTTP-related responsibilities, DTOs carry data, and services coordinate business operations.

Each component has a clearer purpose.

✅ Improved type safety

Typed properties help detect certain programming mistakes and make the expected data types explicit.

For example:

public function __construct(
    public string $name,
    public string $email,
    public int $age,
    public int $courseId,
) {}

These declarations help communicate the intended structure, although they do not replace validation of untrusted input.

✅ Easier unit testing

You can construct a DTO directly in a test without creating an HTTP request.

This makes it easier to test service behavior independently of the controller.

✅ Reusability

The same service can receive a DTO from a controller, queued job, console command, or another service.

The service does not need to know where the data originated.

✅ Controlled data transfer

You can explicitly map only the fields needed for an operation. This reduces the risk of accidentally passing unrelated request fields into business logic or database operations.

🛠️ Implementing a DTO in Laravel Using Student Registration

Let’s build a practical student registration workflow using plain PHP DTOs.

The flow will be:

HTTP Request → Validation → DTO → Service → Database

We’ll use a Form Request for validation, a DTO to represent the registration data, a service to handle persistence, and a controller to coordinate the process.

Step 1: Create the DTO class

Create the following file:

app/DTOs/StudentRegistrationData.php

<?php

namespace App\DTOs;

final readonly class StudentRegistrationData
{
    public function __construct(
        public string $name,
        public string $email,
        public int $age,
        public int $courseId,
    ) {}

    public static function fromArray(array $data): self
    {
        return new self(
            name: $data['name'],
            email: $data['email'],
            age: (int) $data['age'],
            courseId: (int) $data['course_id'],
        );
    }

    public function toArray(): array
    {
        return [
            'name' => $this->name,
            'email' => $this->email,
            'age' => $this->age,
            'course_id' => $this->courseId,
        ];
    }
}

Let’s understand the important parts.

final prevents the class from being extended.

readonly prevents the properties from being reassigned after initialization. This syntax requires PHP 8.2 or later.

__construct() defines the data the DTO requires.

fromArray() converts an associative array into a DTO.

toArray() converts the DTO into an array when needed.

Notice that the DTO contains no database queries or registration workflow. Its responsibility is to represent the registration data.

Also, the type casts in fromArray() are not validation. We will validate incoming values before creating the DTO.

Step 2: Create a Form Request for validation

Run the following command:

php artisan make:request StudentRegistrationRequest

Update app/Http/Requests/StudentRegistrationRequest.php:

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StudentRegistrationRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'name' => [
                'required',
                'string',
                'max:255',
            ],
            'email' => [
                'required',
                'email',
                'max:255',
                'unique:students,email',
            ],
            'age' => [
                'required',
                'integer',
                'min:16',
                'max:100',
            ],
            'course_id' => [
                'required',
                'integer',
                'exists:courses,id',
            ],
        ];
    }
}

The Form Request validates incoming data before the controller action executes.

For this example:

• name must be a non-empty string.

• email must be valid and unique in the students table.

• age must be between 16 and 100.

• course_id must reference an existing course.

These age limits are example business rules and should be adjusted to suit the application.

In a real application, also implement the necessary authorization checks to ensure that the student is permitted to register for the selected course.

Step 3: Create the registration service

Create app/Services/StudentRegistrationService.php:

<?php

namespace App\Services;

use App\DTOs\StudentRegistrationData;
use App\Models\Student;

class StudentRegistrationService
{
    public function register(
        StudentRegistrationData $data
    ): Student {
        return Student::create(
            $data->toArray()
        );
    }
}

The service accepts a StudentRegistrationData object rather than an HTTP request.

This makes it independent of the HTTP layer.

For example, a queued job could construct the same DTO and call this service without creating an HTTP request.

In a larger registration system, the service might also coordinate enrollment rules, seat availability, and notifications.

Step 4: Use the DTO in the controller

Create the controller if it doesn’t already exist:

php artisan make:controller StudentController

Update app/Http/Controllers/StudentController.php:

<?php

namespace App\Http\Controllers;

use App\DTOs\StudentRegistrationData;
use App\Http\Requests\StudentRegistrationRequest;
use App\Services\StudentRegistrationService;
use Illuminate\Http\JsonResponse;

class StudentController extends Controller
{
    public function store(
        StudentRegistrationRequest $request,
        StudentRegistrationService $service
    ): JsonResponse {
        $data = StudentRegistrationData::fromArray(
            $request->validated()
        );

        $student = $service->register($data);

        return response()->json([
            'message' => 'Student registered successfully',
            'data' => $student,
        ], 201);
    }
}

The controller now coordinates the process without containing the database operation itself.

Its responsibilities are straightforward:

1. Receive validated input.

2. Convert the input into a DTO.

3. Pass the DTO to the service.

4. Return an HTTP response.

Laravel’s service container automatically resolves the service dependency.

Step 5: Register the API route

Add this to routes/api.php:

use App\Http\Controllers\StudentController;
use Illuminate\Support\Facades\Route;

Route::post('/students', [
    StudentController::class,
    'store',
]);

Make sure the Student model, database migration, and Course model exist.

The Student model should permit the intended fields through its $fillable property:

protected $fillable = [
    'name',
    'email',
    'age',
    'course_id',
];

Step 6: Test the endpoint

Send a POST request to /api/students with the following JSON body:

{
    "name": "Rahul Sharma",
    "email": "rahul@example.com",
    "age": 21,
    "course_id": 1
}

If validation passes and the database operation succeeds, the endpoint returns a 201 Created response.

If the email is invalid, the age is outside the configured range, or the course does not exist, Laravel rejects the request during validation.

We now have a registration workflow in which the request, DTO, service, and database responsibilities are clearly separated.

⚖️ DTOs vs. Arrays vs. Eloquent Models

🔌 Using Spatie Laravel Data: Taking DTOs to the Next Level

So far, we’ve implemented a DTO using plain PHP. This approach is straightforward, but we had to write our own fromArray() and toArray() methods and define validation rules separately.

As an application grows, this mapping code can become repetitive.

What if we could reduce some of that boilerplate and gain additional functionality?

This is where Spatie Laravel Data comes in.

Spatie Laravel Data is a package that builds on the DTO concept and provides functionality for data transformation, validation, casting, and serialization. It also supports features such as nested data objects and TypeScript generation.

✅ Install Spatie Laravel Data

Install the package with Composer:

composer require spatie/laravel-data

The following example uses the package’s version 4 API.

✅ Create a Student Registration Data object

Create app/Data/StudentRegistrationData.php:

<?php

namespace App\Data;

use Spatie\LaravelData\Data;

class StudentRegistrationData extends Data
{
    public function __construct(
        public string $name,
        public string $email,
        public int $age,
        public int $course_id,
    ) {}

    public static function rules(): array
    {
        return [
            'name' => [
                'required',
                'string',
                'max:255',
            ],
            'email' => [
                'required',
                'email',
                'max:255',
                'unique:students,email',
            ],
            'age' => [
                'required',
                'integer',
                'min:16',
                'max:100',
            ],
            'course_id' => [
                'required',
                'integer',
                'exists:courses,id',
            ],
        ];
    }
}

The data structure and its validation rules are now defined in the same class.

The package can infer basic validation rules from property types, while custom rules let us express requirements such as email uniqueness and course existence.

✅ Use the Data object in the controller

With Spatie Laravel Data, you can inject the data object directly into a controller action.

<?php

namespace App\Http\Controllers;

use App\Data\StudentRegistrationData;
use App\Models\Student;
use Illuminate\Http\JsonResponse;

class StudentController extends Controller
{
    public function store(
        StudentRegistrationData $data
    ): JsonResponse {
        $student = Student::create(
            $data->toArray()
        );

        return response()->json([
            'message' => 'Student registered successfully',
            'data' => $student,
        ], 201);
    }
}

When the data object is resolved from the request, the package can validate the incoming data and create the object before the controller action executes.

In this version of the example, Spatie Laravel Data handles the request validation, so a separate Form Request is not needed for the same validation rules.

If you require more complex authorization or already have a Form Request, you can retain that approach and construct the data object from validated input instead.

As before, ensure the model’s $fillable configuration and database schema match the fields being persisted.

⭐ What are the benefits of Spatie Laravel Data?

1. Less boilerplate code

The package reduces the need to manually implement common data conversion and transformation methods.

2. Built-in validation support

You can define validation rules alongside your data structure and use the package’s request integration.

3. Automatic data transformation

Data objects can be created from supported input sources and transformed into arrays or JSON.

4. Type casting

The package supports casting values into appropriate types, including configured or supported date-related casts.

5. Consistent data contracts

A data object can be reused across controllers, services, and API responses, reducing duplicated definitions.

6. API response transformation

The package supports transforming data objects for output and controlling which properties are included.

7. TypeScript integration

You can generate TypeScript definitions from data objects, which is particularly useful when working with React or other TypeScript-based frontends.

⚖️ Plain PHP DTO vs. Spatie Laravel Data

🤔 Should you always use Spatie Laravel Data?

Not necessarily.

Plain PHP DTOs are a good choice when you need a simple data structure and want to avoid additional dependencies.

Spatie Laravel Data becomes particularly useful when an application has complex request payloads, nested objects, multiple API response structures, and repeated data transformation requirements.

The package does not replace the DTO concept. It provides a more feature-rich way to implement data objects in Laravel.

⭐ DTO Best Practices

👉 Keep DTOs focused

Create DTOs around meaningful operations, such as StudentRegistrationData, rather than creating a generic object that contains every possible student field.

👉 Keep business logic out of DTOs

A DTO should carry data, not perform database queries, register students, or send notifications.

Those responsibilities belong in services or other appropriate application components.

👉 Validate data at the appropriate boundary

Typed properties do not automatically validate untrusted input. Use Laravel validation or suitable domain-level validation where required.

👉 Use immutable DTOs where appropriate

PHP’s readonly classes can prevent accidental reassignment of properties after initialization.

👉 Avoid coupling services to HTTP requests

Prefer passing the data a service actually needs rather than the entire request object.

👉 Don’t introduce DTOs unnecessarily

For a small CRUD operation, a validated array may be enough. Introduce a DTO when its explicit structure and separation of concerns provide real value.

🚫 Common DTO Mistakes to Avoid

Mistake 1: Assuming a DTO validates data automatically

A plain PHP DTO does not enforce Laravel validation rules.

Mistake 2: Treating DTOs as Eloquent models

DTOs carry data; Eloquent models handle database persistence and ORM functionality.

Mistake 3: Putting business logic inside DTOs

Keep the data structure separate from registration workflows, database operations, and external integrations.

Mistake 4: Passing every request field into a DTO

Map only the fields required for the operation. Use validated input and deliberate field selection.

Mistake 5: Creating DTOs for every method

A DTO should solve a real design problem rather than add unnecessary classes and mapping code.

🏁 Conclusion

DTOs are a practical design technique for building maintainable Laravel applications.

They provide a structured way to transfer data between controllers, services, queued jobs, and other application components. By making data contracts explicit, DTOs can improve readability, reduce coupling, and simplify testing.

In our student registration example, we used a DTO to separate validated registration data from the HTTP request and the database operation.

We also explored Spatie Laravel Data, which can reduce repetitive code and provide additional functionality for validation, transformation, and serialization.

Start with plain PHP DTOs to understand the underlying concept. Introduce them where your application benefits from explicit data contracts, and consider Spatie Laravel Data when your requirements become more complex.

Remember these three principles:

• Validation determines whether incoming data is acceptable.

• DTOs define the structure of the data being transferred.

• Services coordinate the business operation.

Used appropriately, DTOs can help your Laravel applications remain easier to understand, test, and maintain as they grow.

As an application grows, the difficult part isn’t adding another feature. The difficult part is adding that feature without breaking the existing system.

A payment provider changes.

A new notification channel is introduced.

A business rule becomes more complicated.

A report needs another output format.

A third-party API is replaced.

Suddenly, a class that started as 100 lines has become 800 lines, filled with if/else statements, external API calls, database queries, and business rules.

This is where SOLID principles become useful.

SOLID is a collection of five object-oriented design principles:

• S - Single Responsibility Principle

• O - Open/Closed Principle

• L - Liskov Substitution Principle

• I - Interface Segregation Principle

• D - Dependency Inversion Principle

But there is an important misconception:

SOLID is not about creating more classes. It’s about making change safer and cheaper.

In this article, we’ll explore each principle using realistic Laravel and PHP examples.

🎯 What Problem Does SOLID Actually Solve?

Imagine an order-processing system.

Initially, you have:

OrderController
      |
      v
OrderService
      |
      +-- Validate order
      +-- Calculate price
      +-- Charge payment
      +-- Generate invoice
      +-- Send email
      +-- Send SMS
      +-- Write audit log

This might work perfectly when the application is small.

But eventually:

• Stripe becomes PayPal

• Email becomes WhatsApp

• Invoice generation changes

• Pricing rules become more complicated

• Multiple payment gateways are required

• Different tenants need different providers

Now every change requires modifying the same large class.

SOLID helps us move toward:

Each component has a clear responsibility and dependencies can be replaced without rewriting the business logic.

1. S - Single Responsibility Principle

A class should have one reason to change.

SRP doesn’t mean a class can have only one method.

It means a class should have one cohesive responsibility.

If a class handles payment, invoices, notifications, validation, and reporting, it has too many reasons to change.

👉 Before: One class doing everything

Consider an order-processing service:

class OrderService
{
    public function process(Order $order): void
    {
        // Validate order
        if ($order->items->isEmpty()) {
            throw new Exception('Order has no items.');
        }

        // Calculate total
        $total = $order->items->sum(
            fn ($item) => $item->price * $item->quantity
        );

        // Charge payment
        $payment = Http::post(
            'https://payment.example.com/charge',
            [
                'amount' => $total,
                'currency' => 'USD',
                'customer_id' => $order->customer_id,
            ]
        );

        if (!$payment->successful()) {
            throw new Exception('Payment failed.');
        }

        // Create invoice
        Invoice::create([
            'order_id' => $order->id,
            'amount' => $total,
        ]);

        // Send email
        Mail::to($order->customer->email)
            ->send(new OrderConfirmationMail($order));

        // Write audit log
        Log::info('Order processed', [
            'order_id' => $order->id,
            'amount' => $total,
        ]);
    }
}

This class is responsible for:

• validation

• pricing

• payment

• invoice generation

• email

• logging

That’s too much.

Why is this a problem?

Suppose the payment provider changes.

You modify OrderService.

Suppose invoice generation changes.

You modify OrderService again.

Suppose the notification system changes.

Again, OrderService.

The class becomes a change hotspot.

The bigger it becomes, the higher the risk that a small change breaks unrelated functionality.

👉 After: Separate responsibilities

Extract cohesive responsibilities.

Order validator

class OrderValidator
{
    public function validate(Order $order): void
    {
        if ($order->items->isEmpty()) {
            throw new Exception('Order has no items.');
        }
    }
}

Price calculator

class OrderTotalCalculator
{
    public function calculate(Order $order): float
    {
        return $order->items->sum(
            fn ($item) => $item->price * $item->quantity
        );
    }
}

Invoice service

class InvoiceService
{
    public function create(
        Order $order,
        float $amount
    ): Invoice {
        return Invoice::create([
            'order_id' => $order->id,
            'amount' => $amount,
        ]);
    }
}

Notification service

class OrderNotificationService
{
    public function sendConfirmation(
        Order $order
    ): void {
        Mail::to($order->customer->email)
            ->send(new OrderConfirmationMail($order));
    }
}

Now OrderService coordinates the workflow:

class OrderService
{
    public function __construct(
        private OrderValidator $validator,
        private OrderTotalCalculator $calculator,
        private PaymentService $paymentService,
        private InvoiceService $invoiceService,
        private OrderNotificationService $notificationService,
    ) {}

    public function process(Order $order): void
    {
        $this->validator->validate($order);

        $total = $this->calculator->calculate($order);

        $this->paymentService->charge(
            $order,
            $total
        );

        $this->invoiceService->create(
            $order,
            $total
        );

        $this->notificationService
            ->sendConfirmation($order);
    }
}

Now each class has a clearer responsibility.

A practical SRP rule

When reviewing a class, ask:

“How many different reasons could cause this class to change?”

If the answer is five, the class probably has five responsibilities.

2. O - Open/Closed Principle

Software should be open for extension but closed for modification.

This means we should be able to introduce new behavior without repeatedly modifying stable business logic.

Payment processing is a good example.

Imagine your application supports multiple payment providers.

👉 Before: Growing conditional logic

class PaymentService
{
    public function charge(
        string $gateway,
        float $amount
    ): void {
        if ($gateway === 'stripe') {

            Http::post(
                'https://stripe.example.com/charge',
                [
                    'amount' => $amount,
                ]
            );

        } elseif ($gateway === 'paypal') {

            Http::post(
                'https://paypal.example.com/payment',
                [
                    'amount' => $amount,
                ]
            );

        } elseif ($gateway === 'razorpay') {

            Http::post(
                'https://razorpay.example.com/payment',
                [
                    'amount' => $amount,
                ]
            );
        }
    }
}

Today you have three providers.

Tomorrow:

Stripe
PayPal
Razorpay
Adyen
Authorize.Net
Apple Pay
Google Pay
...

The if/else chain keeps growing.

Every new provider requires modifying PaymentService.

That’s exactly the kind of change OCP tries to avoid.

👉 After: Use an abstraction

Define a common contract:

interface PaymentGateway
{
    public function charge(
        float $amount
    ): PaymentResult;
}

Stripe:

class StripeGateway implements PaymentGateway
{
    public function charge(
        float $amount
    ): PaymentResult {
        // Stripe-specific implementation

        return PaymentResult::success();
    }
}

PayPal:

class PayPalGateway implements PaymentGateway
{
    public function charge(
        float $amount
    ): PaymentResult {
        // PayPal-specific implementation

        return PaymentResult::success();
    }
}

Now the service depends on the abstraction:

class PaymentService
{
    public function __construct(
        private PaymentGateway $gateway
    ) {}

    public function charge(
        float $amount
    ): PaymentResult {
        return $this->gateway->charge($amount);
    }
}

Adding another provider doesn’t require modifying PaymentService.

class AdyenGateway implements PaymentGateway
{
    public function charge(
        float $amount
    ): PaymentResult {
        // Adyen implementation
    }
}

That’s the practical idea behind OCP.

Laravel makes this easier

Laravel’s service container can bind the interface:

$this->app->bind(
    PaymentGateway::class,
    StripeGateway::class
);

Now Laravel can inject the correct implementation automatically.

3. L - Liskov Substitution Principle

If a class claims to implement an abstraction, it should be safely usable wherever that abstraction is expected.

LSP is essentially about behavioral compatibility.

Inheritance or interface implementation isn’t enough.

The implementation must actually honor the contract.

Consider a reporting system.

👉 Before: Incorrect abstraction

abstract class ReportGenerator
{
    abstract public function generate(
        array $data
    ): string;

    public function exportToPdf(
        string $content
    ): string {
        return "PDF: " . $content;
    }
}

Now we create a CSV report:

class CsvReportGenerator extends ReportGenerator
{
    public function generate(
        array $data
    ): string {
        return 'CSV report';
    }

    public function exportToPdf(
        string $content
    ): string {
        throw new Exception(
            'CSV cannot be exported to PDF.'
        );
    }
}

Now this code is dangerous:

function generateReport(
    ReportGenerator $report
): string {
    $content = $report->generate([]);

    return $report->exportToPdf($content);
}

A caller expects ReportGenerator to support PDF export.

But CsvReportGenerator doesn’t.

The subclass cannot safely substitute the parent abstraction.

That’s an LSP violation.

👉 After: Model capabilities correctly

Separate report generation from PDF export.

interface ReportGenerator
{
    public function generate(
        array $data
    ): string;
}

interface PdfExporter
{
    public function exportToPdf(
        string $content
    ): string;
}

A PDF-capable report can implement both:

class SalesReportGenerator
    implements ReportGenerator, PdfExporter
{
    public function generate(
        array $data
    ): string {
        return 'Sales report';
    }

    public function exportToPdf(
        string $content
    ): string {
        return "PDF: " . $content;
    }
}

A CSV report only implements what it actually supports:

class CustomerCsvReportGenerator
    implements ReportGenerator
{
    public function generate(
        array $data
    ): string {
        return 'Customer CSV report';
    }
}

Now the abstraction accurately represents the capabilities of the implementation.

A useful LSP smell

If an implementation frequently contains:

throw new Exception('Not supported');

for methods it inherited or implemented, stop and reconsider the abstraction.

You may have an LSP or interface-design problem.

👉 Composition Over Inheritance

LSP also leads to an important architectural lesson:

Prefer composition when behavior needs to vary independently.

Instead of building complicated inheritance trees:

Payment
   |
   +-- OnlinePayment
         |
         +-- CreditCardPayment
                |
                +-- StripeCreditCardPayment

you can compose behavior:

PaymentService
      |
      +-- PaymentGateway
      +-- PaymentValidator
      +-- PaymentLogger

Composition often makes business systems easier to evolve because behavior can be replaced independently.

4. I - Interface Segregation Principle

Clients should not be forced to depend on methods they don’t use.

In other words:

Prefer small, focused interfaces over large, “do everything” interfaces.

Consider a notification system.

👉 Before: A fat interface

interface NotificationService
{
    public function sendEmail(
        string $to,
        string $message
    ): void;

    public function sendSms(
        string $phone,
        string $message
    ): void;

    public function sendPush(
        string $deviceToken,
        string $message
    ): void;

    public function sendSlack(
        string $channel,
        string $message
    ): void;
}

Now an SMS implementation must implement everything:

class SmsNotification implements NotificationService
{
    public function sendEmail(
        string $to,
        string $message
    ): void {
        throw new Exception('Not supported');
    }

    public function sendSms(
        string $phone,
        string $message
    ): void {
        // Send SMS
    }

    public function sendPush(
        string $deviceToken,
        string $message
    ): void {
        throw new Exception('Not supported');
    }

    public function sendSlack(
        string $channel,
        string $message
    ): void {
        throw new Exception('Not supported');
    }
}

This interface is too large.

👉 After: Smaller interfaces

interface EmailNotifier
{
    public function sendEmail(
        string $to,
        string $message
    ): void;
}

interface SmsNotifier
{
    public function sendSms(
        string $phone,
        string $message
    ): void;
}

interface PushNotifier
{
    public function sendPush(
        string $deviceToken,
        string $message
    ): void;
}

Now an SMS provider only needs to implement:

class TwilioSmsNotifier implements SmsNotifier
{
    public function sendSms(
        string $phone,
        string $message
    ): void {
        // Send SMS
    }
}

This reduces coupling and makes implementations easier to understand.

A practical question

Don’t ask:

“How can I create one interface for everything?”

Ask:

“What capability does this consumer actually need?”

5. D - Dependency Inversion Principle

High-level business logic should not depend directly on low-level implementation details. Both should depend on abstractions.

This is one of the most valuable SOLID principles for Laravel applications.

Consider an order service that directly creates a Stripe client.

👉 Before: Business logic coupled to Stripe

class OrderService
{
    public function process(Order $order): void
    {
        $stripe = new \Stripe\StripeClient(
            config('services.stripe.secret')
        );

        $stripe->paymentIntents->create([
            'amount' => $order->total * 100,
            'currency' => 'usd',
        ]);

        $order->update([
            'status' => 'paid',
        ]);
    }
}

Now OrderService knows:

• Stripe exists

• Stripe’s SDK exists

• how Stripe authentication works

• how Stripe represents payments

If the business moves from Stripe to another provider, the business service must change.

👉 After: Depend on an abstraction

Create a contract:

interface PaymentGateway
{
    public function charge(
        float $amount,
        string $currency
    ): PaymentResult;
}

Stripe becomes an implementation detail:

class StripePaymentGateway
    implements PaymentGateway
{
    public function __construct(
        private \Stripe\StripeClient $stripe
    ) {}

    public function charge(
        float $amount,
        string $currency
    ): PaymentResult {
        $payment = $this->stripe
            ->paymentIntents
            ->create([
                'amount' => (int) ($amount * 100),
                'currency' => $currency,
            ]);

        return PaymentResult::success(
            $payment->id
        );
    }
}

The business service now depends only on the contract:

class OrderService
{
    public function __construct(
        private PaymentGateway $paymentGateway
    ) {}

    public function process(Order $order): void
    {
        $result = $this->paymentGateway->charge(
            $order->total,
            'USD'
        );

        if (!$result->successful()) {
            throw new PaymentFailedException();
        }

        $order->update([
            'status' => 'paid',
        ]);
    }
}

Laravel connects the abstraction with the implementation:

$this->app->bind(
    PaymentGateway::class,
    StripePaymentGateway::class
);

The architecture becomes:

The important part:

OrderService doesn’t depend on Stripe. It depends on the concept of a payment gateway.

⚠️ Code Smells That Often Point Toward SOLID

You don’t need to memorize every SOLID definition.

Instead, learn to recognize the symptoms.

🛑 When NOT to Over-Engineer

Before introducing an abstraction, ask:

1. Is this behavior actually expected to vary?

If not, keep it simple.

2. Is there a real architectural boundary?

External payment providers, messaging providers, storage systems, and third-party APIs often justify abstractions.

3. Does the abstraction make testing easier?

If yes, that’s a strong reason.

4. Is the code difficult to change today?

SOLID is especially valuable around areas that change frequently.

5. Are you solving a real problem?

Don’t build an elaborate architecture for a hypothetical requirement that may never happen.

✨ Final Takeaway

SOLID isn’t a checklist you apply mechanically.

It’s a set of design heuristics for managing change.

The goal isn’t to create the most abstract architecture possible.

The goal is to create software where:

Business Logic
      ↓
Stable Abstractions
      ↓
Replaceable Implementations

When a payment provider changes, you shouldn’t need to rewrite order processing.

When a notification channel changes, you shouldn’t need to rewrite business logic.

When a new report format is introduced, existing report generation shouldn’t break.

And when you write tests, you shouldn’t need to call every external service.

That’s where SOLID provides real value.

Good architecture isn’t about writing more code.

It’s about making change cheaper.

And that’s ultimately what SOLID is about.

Initially, everything works perfectly.

Then your application starts getting users from:

• Mumbai

• London

• New York

• Singapore

• Sydney

Now every user request has to travel back to your origin server.

As traffic increases, your server starts experiencing:

• Higher latency

• Increased bandwidth consumption

• More CPU and network pressure

• Slower response times

• Increased infrastructure costs

• Potential downtime

So, how do large-scale applications deliver content quickly to users around the world?

The answer is CDN - Content Delivery Network.

🗣️ What Is a CDN?

A Content Delivery Network is a geographically distributed network of servers that delivers content from locations closer to users.

Instead of every user requesting content directly from your origin server:

a CDN places edge servers between users and your origin:

The CDN stores frequently requested content at these edge locations.

When a user requests content, the CDN tries to serve it from the closest suitable edge location.

The core idea is simple:

Bring content closer to the user.

🤔 Why Do We Need a CDN?

Let’s take a simple example.

Your application is hosted in Mumbai.

A user in Mumbai might have relatively low network latency:

Mumbai User
     |
     | Shorter distance
     v
Mumbai Server

But a user in New York has to communicate with infrastructure thousands of kilometers away:

New York User
     |
     | Long network distance
     v
Mumbai Server

Now imagine millions of requests.

Your origin server has to repeatedly send the same files:

app.js
style.css
logo.png
product-image.jpg
font.woff2
video.mp4

Most of these files don’t change frequently.

So instead of making the origin serve the same content repeatedly, a CDN can cache that content closer to users.

🤖 How Does a CDN Work?

Let’s take an image:

https://example.com/images/product-101.jpg

A user requests the image.

The request reaches the CDN.

The CDN checks:

“Do I already have this file in my cache?”

There are two possibilities.

🟢 Cache Hit

The content already exists at the edge.

The CDN immediately returns the image.

The origin isn’t contacted.

🔴 Cache Miss

The content doesn’t exist at the edge.

The CDN retrieves the content from the origin.

It can then store the content in its cache.

The next user requesting the same content can receive it directly from the CDN.

💡Understanding Cache Hit and Cache Miss

This is one of the most important concepts when working with CDNs.

Suppose 10,000 users request:

/logo.png

Without caching:

10,000 Requests
       |
       v
    Origin

With CDN caching:

10,000 Requests
       |
       v
      CDN
       |
       +---- 9,999 Cache Hits
       |
       +---- 1 Cache Miss
                 |
                 v
               Origin

The exact number of origin requests depends on timing, cache behavior, configuration, and revalidation, but the important idea is that repeated requests can be served from the edge.

💾 What Does a CDN Cache?

CDNs are commonly used for content that is requested frequently and doesn’t change every second.

Typical examples include:

Images

.jpg
.png
.webp
.svg

JavaScript

app.js
vendor.js
main.js

CSS

app.css
style.css

Fonts

.woff
.woff2
.ttf

Videos

.mp4
.webm

Documents

.pdf
.zip

Static HTML

Depending on the application architecture, HTML pages can also be cached.

🌐 CDN Architecture

A simplified CDN architecture looks like this:

The origin contains the original content.

The edge servers cache frequently requested content.

The user ideally receives the content from an edge location instead of going all the way back to the origin every time.

🧩 What Is an Origin Server?

The origin is the original source of the content.

For example, your origin could be:

Application Server

or:

Object Storage

or:

A dedicated media server

For a web application, you might have:

Origin
   |
   +── HTML
   +── JavaScript
   +── CSS
   +── Images
   +── Videos

The CDN retrieves content from the origin when it doesn’t already have a valid cached copy.

📈 CDN Caching Strategy

Caching is where CDN architecture becomes interesting.

You need to decide:

What should be cached?

How long should it be cached?

When should it expire?

How should updated content reach users?

These decisions are usually controlled through HTTP caching headers and CDN configuration.

For example:

Cache-Control: public, max-age=3600

This means the response can be cached and considered fresh for 3600 seconds.

Cache-Control

Some commonly used directives are:

public

Cache-Control: public

Allows shared caches to store the response.

max-age

Cache-Control: max-age=3600

Specifies how long the response can be considered fresh.

no-store

Cache-Control: no-store

Tells caches not to store the response.

immutable

Cache-Control: public, max-age=31536000, immutable

This can be useful for versioned static assets that never change at the same URL.

❓The Cache Invalidation Problem

Caching gives us performance.

But caching introduces another problem:

What happens when the original content changes?

Suppose your CDN cached:

logo-v1.png

You update the logo.

But users still receive the cached version.

Why?

Because the CDN still considers the cached object valid.

There are several ways to solve this.

Strategy 1: TTL

Set an expiration time.

Cache-Control: max-age=3600

After the specified period, the cached object can become stale and the CDN may retrieve a newer version.

Strategy 2: Cache Purging

When you deploy new content:

Deploy
  |
  v
Purge CDN Cache
  |
  v
New Content

The CDN removes the selected cached objects.

Strategy 3: Versioned Assets

Instead of:

app.js

use:

app.v1.js

After deployment:

app.v2.js

The URL changes, so the CDN treats it as a new resource.

This is a very common strategy for JavaScript, CSS, images, and other static assets.

🚨 Common CDN Mistakes

1. Caching Everything

Not every response should be cached.

2. Ignoring Cache Invalidation

Users may continue receiving stale content.

3. Using Long TTLs Without Versioning

Content updates can take too long to propagate.

4. Caching Personalized Data

This can create serious security and privacy issues.

5. Ignoring Cache Keys

Different requests can require different cached responses.

6. Not Monitoring Cache Performance

Without metrics, you don’t know whether your CDN configuration is effective.

🏢 Popular CDN Providers

Some widely used CDN platforms include:

• Cloudflare

• Amazon CloudFront

• Akamai

• Fastly

• Google Cloud CDN

The right choice depends on your geographic requirements, traffic volume, caching needs, security requirements, cloud environment, and cost.

⭐ CDN Best Practices

If you’re designing a CDN strategy for production, keep these principles in mind:

1. Cache What Changes Slowly

Good candidates include:

Images
CSS
JavaScript
Fonts
Videos
Documents

2. Use Long TTLs for Versioned Assets

For example:

app.a81f92.js

can have a long cache lifetime because the filename changes when the content changes.

3. Keep Cache Keys Simple

Only include request attributes that actually change the response.

4. Protect Sensitive Data

Never make private or personalized content publicly cacheable by accident.

5. Plan Cache Invalidation

Have a clear strategy for handling content updates.

6. Monitor Cache Hit Ratio

Your CDN configuration should be driven by real traffic data.

7. Test Globally

Test performance from different geographic regions, not just from your development machine.

🎯 Final Takeaway

If you remember only five things about CDN, remember these:

1. CDN reduces latency
Content is delivered from locations closer to users.

2. CDN reduces origin traffic
Repeated requests can be served from the edge.

3. Cache strategy is critical
TTL, cache keys, and invalidation determine how effectively your CDN works.

4. Not everything should be cached
Personalized and sensitive content requires special care.

5. Measure the results
Cache hit ratio, latency, origin traffic, and geographic performance tell you whether your CDN strategy is working.

A CDN doesn’t make your content disappear from the origin. It makes your content available closer to the people who need it.

At first, everything works perfectly.

Then your application becomes popular.

Suddenly, thousands of users are sending requests simultaneously.

Your server starts experiencing:

• High CPU usage

• Increased response time

• Memory pressure

• Connection limits

• Eventually, downtime

The obvious solution is to add more application servers.

But this creates another problem:

Who decides which server should handle each request?

This is where a Load Balancer comes in.

🏗️ What Is a Load Balancer?

A Load Balancer is a component that sits between clients and backend servers and distributes incoming traffic across multiple servers.

Instead of:

we introduce a load balancer:

The client doesn’t need to know which application server processes the request.

The load balancer handles that decision.

💡Why Do We Need a Load Balancer?

A load balancer primarily helps solve four major problems.

Scalability

Instead of continuously increasing the capacity of one server, we can add more servers.

This is known as horizontal scaling.

High Availability

What happens if Server B crashes?

A good load balancer detects that Server B is unhealthy and stops sending traffic to it.

Users can continue using the application.

Fault Tolerance

A failure in one server should not necessarily become a failure of the entire application.

The load balancer acts as a layer that isolates individual server failures.

Performance

Traffic can be distributed across multiple servers instead of allowing one server to become overloaded.

⚖️ Load Balancing Algorithms

Choosing the correct backend server is one of the most important responsibilities of a load balancer.

There are several common algorithms.

Round Robin

Requests are distributed sequentially.

Simple and effective when servers have similar capacity.

Weighted Round Robin

Not all servers need to have equal capacity.

Server A receives more traffic.

This is useful when your infrastructure contains servers with different CPU, memory, or instance sizes.

Least Connections

The load balancer sends traffic to the server with the fewest active connections. The next request can be sent to Server B:

This can be useful when requests have significantly different processing times.

IP Hash

The load balancer calculates a hash based on the client's IP address.

The same client can therefore tend to reach the same backend server.

This can be useful when applications have session-related requirements, although modern systems often prefer shared session storage instead of relying on server affinity.

🌐 Layer 4 Load Balancer (Network Level)

Layer 4 operates primarily with:

• TCP

• UDP

• IP

• Port

It doesn’t need to understand the HTTP request itself.

Advantages

• Fast

• Low overhead

• Suitable for TCP/UDP workloads

• Protocol agnostic

🖥️ Layer 7 Load Balancer(Application Level)

Layer 7 understands application-level protocols such as HTTP/HTTPS.

Therefore, it can make routing decisions based on:

• URL path

• HTTP method

• Headers

• Cookies

• Hostname

For example:

/api/users/*    → User Service

/api/orders/*   → Order Service

/api/payments/* → Payment Service

Architecture:

This makes Layer 7 load balancing particularly useful for microservices and API-based architectures.

🎯 Final Takeaway

When designing a distributed application, don’t ask only:

“How many servers do I need?”

Ask:

“How will traffic enter the system, how will it be distributed, how will failures be detected, and how will the system continue operating when individual components fail?”

That’s where the load balancer becomes an important architectural building block.

A well-designed load-balancing layer helps transform a single-server application into a scalable, resilient, and highly available distributed system.

• 👤 User Service

• 🛒 Order Service

• 💳 Payment Service

• 📦 Inventory Service

• 🔔 Notification Service

Should the frontend communicate directly with every service?

Usually, no.

This is where an API Gateway comes into the picture.

What is an API Gateway?

An API Gateway is a single entry point between clients and backend services.

Instead of:

we use:

The client communicates with the gateway, and the gateway routes the request to the appropriate backend service.

Why Do We Need an API Gateway?

As your system grows, several common requirements appear:

1. Request Routing

The gateway determines where a request should go.

GET /api/users   → User Service
GET /api/orders  → Order Service
POST /api/payment → Payment Service

2. Authentication & Authorization 🔐

Instead of implementing authentication logic independently in every service, the gateway can validate:

• JWT tokens

• API keys

• OAuth tokens

• Access permissions

Client
  ↓
API Gateway
  ↓ Validate Token
  ↓
Backend Service

However, services should still enforce authorization for sensitive operations rather than blindly trusting the gateway.

3. Rate Limiting 🚦

The gateway can prevent clients from sending too many requests.

For example:

100 requests / minute / user

If the limit is exceeded:

HTTP 429 Too Many Requests

This helps protect backend services from accidental or abusive traffic.

4. Logging & Monitoring 📊

A gateway provides a centralized place to capture:

• Request/response metrics

• Latency

• Error rates

• Request IDs

• Traffic patterns

This makes troubleshooting distributed systems easier.

5. Response Aggregation

Sometimes a frontend needs data from multiple services.

Instead of making multiple requests:

Client → User Service
Client → Order Service
Client → Payment Service

the gateway can orchestrate the calls:

Client
  ↓
API Gateway
  ├──→ User Service
  ├──→ Order Service
  └──→ Payment Service
        ↓
   Combined Response

This can reduce client-side complexity and network round trips, although excessive aggregation can make the gateway harder to maintain.

🛠️ Popular API Gateway Solutions

Some commonly used options are:

• Kong

• NGINX

• AWS API Gateway

• Azure API Management

• Google Cloud API Gateway

The right choice depends on your infrastructure, traffic requirements, cloud platform, and operational needs.

🆚 API Gateway vs Load Balancer

These two are often confused.

A Load Balancer primarily distributes traffic across healthy backend instances.

An API Gateway generally operates at a higher application/API layer and can provide capabilities such as authentication, rate limiting, routing, transformation, and API policies.

In many architectures, you can have both:

Client
  ↓
Load Balancer
  ↓
API Gateway
  ↓
Microservices

Or the gateway itself may incorporate load-balancing capabilities.

⚖️ The Trade-off

API Gateway provides many benefits, but it also introduces another component.

Potential challenges include:

• Additional latency

• Gateway becoming a bottleneck

• More operational complexity

• Configuration management

• Failure handling

• Overloading the gateway with business logic

A good API Gateway should handle cross-cutting concerns not become your entire application.

🎯 Final Thought

In a microservices architecture, the API Gateway acts as the front door to your backend.

It can simplify:

Routing + Security + Rate Limiting + Observability + Traffic Management

But the goal isn’t to put everything inside the gateway.

Keep the gateway focused on managing API traffic, while business logic remains inside the appropriate services.

That’s the key to building a scalable and maintainable API architecture.

A customer in Mumbai clicks “Pay Now.”

The request reaches your India region:

Everything has worked perfectly for months.

Then, during a massive sale, something goes wrong.

The network connection between Mumbai and Singapore breaks.

Now suppose the customer tries to purchase the last available item.

Mumbai says:

“Inventory = 1. I’ll sell it.”

Singapore simultaneously says:

“Inventory = 1. I’ll sell it.”

You now potentially have:

You now potentially have:

Mumbai:    inventory = 0
Singapore: inventory = 0

But:

Orders created = 2
Actual items  = 1

Congratulations.

You’ve just encountered one of the fundamental problems of distributed systems.

This is where CAP Theorem becomes practical.

And this is also where one of the most commonly repeated explanations of CAP becomes misleading:

❌ “You can pick any two of Consistency, Availability, and Partition Tolerance.”

That’s not really how CAP should be understood.

The useful mental model is:

When a network partition happens, a distributed system must trade off strong consistency against availability.

Let’s unpack why.

What is CAP Theorem?

CAP stands for:

• C — Consistency

• A — Availability

• P — Partition Tolerance

The theorem says that a distributed system cannot guarantee strong consistency and availability simultaneously when a network partition occurs.

The common explanation:

❌ “Pick any 2 out of 3.”

is misleading.

The more useful mental model is:

          Network Partition
                  |
             +----+----+
             |         |
             v         v
        Consistency  Availability
             CP          AP

When a partition happens, you have to make a trade-off between C and A.

1. Consistency

CAP consistency generally means linearizability.

After a successful write, subsequent reads should see that value or a newer value.

WRITE balance = ₹500
        |
        v
READ balance
        |
        v
     ₹500

Important:

CAP Consistency is not the same as the C in ACID.

2. Availability

Availability means that every request sent to a non-failing node receives a non-error response.

During a network failure, an available system continues serving requests.

The trade-off is that the response may not reflect the latest global state.

3. Partition Tolerance

A partition occurs when distributed nodes cannot reliably communicate.

Node A                  Node B

  DB                      DB
   |                       |
   XXXXXXXXXXXXXXXXXXXXXXXX
          Network
          Partition

Network failures, packet loss, latency spikes, cloud outages, and routing problems make partitions a reality.

Therefore:

Partition tolerance is not really an optional configuration in a distributed system.

CP vs AP

CP — Consistency + Partition Tolerance

During a partition, the system may reject or block some requests rather than risk inconsistent data.

Client
  |
  v
Node A
  |
  X ---- Node B
  |
 ERROR

Typical use cases:

• Financial transactions

• Distributed locks

• Leader election

• Inventory reservation

• Configuration/coordination

Examples include ZooKeeper, etcd, and appropriately configured MongoDB deployments.

AP — Availability + Partition Tolerance

During a partition, the system continues serving requests even if replicas temporarily disagree.

Node A                 Node B

stock = 0              stock = 1
   |                       |
   XXXXXXXXXXXXXXXXXXXXXXXX
          Partition

When the network recovers, the system reconciles the differences.

Typical use cases:

• Social feeds

• Shopping carts

• Large-scale analytics

• Highly available applications

Examples include Apache Cassandra and systems using eventual-consistency patterns such as DynamoDB’s eventually consistent reads.

How Should Engineers Think About CAP?

Don’t simply ask:

“Is this database CP or AP?”

Instead ask:

1. What happens if the network fails?

2. Can stale data cause business damage?

3. Can two nodes safely make independent decisions?

4. Can conflicting updates be merged?

5. How much latency is acceptable?

For example:

Payment authorization → Strong consistency

Inventory reservation → Strong consistency

Social feed           → Eventual consistency

Analytics dashboard   → Eventual consistency

Shopping cart         → Often eventual/tunable

3 Key Takeaways

1. CAP does NOT mean “pick any 2 of 3.”

The important trade-off happens when a network partition occurs: Consistency vs Availability.

2. Partition tolerance is a reality.

If your application is distributed across machines or regions, network failures must be part of your design.

3. Choose consistency per business requirement.

Don’t make your entire architecture “CP” or “AP” blindly. Determine which data requires strong consistency and which data can tolerate temporary staleness.

The real question isn’t “CP or AP?”

It’s “What must remain correct when the network fails?”

But adding Cache::remember() to a database query is not a complete caching strategy.

As an application grows, caching introduces important questions:

• What data should be cached?

• When should the cache be invalidated?

• What happens when the database changes?

• What if multiple users update the same data?

• How do we prevent stale data?

• What happens when Redis goes down?

• How do we avoid a cache stampede?

• Should we update the cache before or after updating the database?

These questions are where caching patterns become important.

In this article, we’ll explore the most common caching patterns and see how they can be implemented in Laravel using real-world scenarios.

.

🚀 What Is Caching?

Caching is the process of temporarily storing frequently accessed data in a faster storage layer so that future requests can retrieve it without repeating an expensive operation.

Avoid doing expensive work repeatedly when the result can be reused safely.

🧠 Why Do We Need Caching Patterns?

Caching sounds simple:

Cache::remember('users', 3600, function () {
    return User::all();
});

But real applications are more complicated.

Imagine an insurance platform where thousands of users frequently request:

• Product configuration

• State tax rates

• Policy rules

• Producer information

• Permission configuration

Some of this data changes frequently, while some changes only once a day or once a month.

Using the same caching strategy for everything can create problems.

This is why we need different caching patterns.

📚 Common Caching Patterns

The most useful caching patterns for Laravel applications are:

1. Cache-Aside

2. Read-Through

3. Write-Through

4. Write-Behind / Write-Back

5. Refresh-Ahead

6. Stale-While-Revalidate

7. Cache-Through for External APIs

8. Cache-Aside with Event-Based Invalidation

1️⃣ Cache-Aside Pattern

The Most Common Pattern in Laravel

The Cache-Aside pattern is also called Lazy Loading.

The application is responsible for checking the cache first.

If the data exists:

Cache HIT
   ↓
Return cached data

If the data does not exist:

Cache MISS
   ↓
Query Database
   ↓
Store Result in Cache
   ↓
Return Result

Example

$products = Cache::remember(
    'products',
    now()->addHour(),
    function () {
        return Product::where('active', true)->get();
    }
);

Laravel will:

1. Check the cache.

2. Return the cached value if available.

3. Execute the callback on a cache miss.

4. Store the result in the cache.

5. Return the result.

When Should You Use Cache-Aside?

Cache-Aside is a good choice when:

• Data is read frequently.

• Data changes relatively infrequently.

• You can tolerate a small amount of staleness.

• The application controls cache invalidation.

Examples:

• Product catalog

• Application configuration

• User permissions

• Tax rates

• Country/state lists

• Dashboard statistics

2️⃣ Read-Through Cache

Read-Through caching moves the responsibility of loading missing data closer to the caching layer.

Conceptually:

Application
     ↓
   Cache
     ↓
Cache MISS
     ↓
Data Store
     ↓
Cache
     ↓
Application

The application doesn’t explicitly manage the cache-miss loading logic.

Instead, the caching abstraction handles it.

Conceptual Example

$product = $cache->get(
    'product:1001',
    fn () => Product::find(1001)
);

The cache abstraction decides what to do when the value isn’t available.

Example

Laravel applications commonly implement this behavior using service classes around Laravel’s cache abstraction.

For example:

class ProductService
{
    public function find(int $id): ?Product
    {
        return Cache::remember(
            "product:{$id}",
            now()->addMinutes(30),
            fn () => Product::find($id)
        );
    }
}

Although Laravel’s Cache::remember() is often described as Cache-Aside, a service layer can encapsulate that behavior so callers don’t need to know how the cache is populated.

3️⃣ Write-Through Cache

With Write-Through caching, data is written to the cache and persistent storage as part of the write operation.

The general flow is:

Application
     ↓
   Cache
     ↓
 Database

The cache is updated immediately when the data changes.

Example

Suppose an administrator updates a product price.

$product->update([
    'price' => $price,
]);

Cache::put(
    "product:{$product->id}",
    $product->fresh(),
    now()->addHour()
);

Now both the database and cache contain the latest value.

Important Consideration

Write-through caching increases write complexity.

You need to think about:

• What happens if the database update succeeds but cache update fails?

• What happens if cache update succeeds but database update fails?

• Which system is considered the source of truth?

In most business applications:

The database should remain the source of truth.

The cache should be treated as a performance optimization, not the authoritative data store.

4️⃣ Write-Behind / Write-Back Cache

Write-Behind caching takes the idea further.

The application writes to the cache first, while the persistent database update happens asynchronously.

Application
     ↓
   Cache
     ↓
Queue
     ↓
Worker
     ↓
Database

This can make write-heavy systems faster because the user doesn’t always need to wait for the database operation.

Example

A simplified implementation might look like:

Cache::put(
    "counter:{$userId}",
    $newValue,
    now()->addHours(1)
);

UpdateCounter::dispatch($userId, $newValue);

The queue worker later persists the value.

Real-World Scenario

Consider a website tracking:

Page Views
Product Views
Video Views
Click Events

Writing every event synchronously to MySQL can create significant database load.

Instead:

User Activity
     ↓
Redis
     ↓
Queue
     ↓
Batch Processing
     ↓
MySQL

This approach can dramatically reduce database write pressure.

⚠️ The Risk

Write-behind caching introduces eventual consistency.

For example:

Redis = 10,500 views
Database = 10,200 views

The database may temporarily lag behind the cache.

Therefore, this pattern is more appropriate for data where eventual consistency is acceptable.

It should generally not be used casually for critical financial transactions, account balances, or other data where every write must be durably committed before success is reported.

5️⃣ Refresh-Ahead Pattern

Refresh-Ahead caching attempts to refresh cached data before it expires.

Without Refresh-Ahead:

Cache expires
     ↓
First user gets Cache MISS
     ↓
Database query
     ↓
Cache recreated

The first request after expiration can become slower.

With Refresh-Ahead:

Cache nearly expires
       ↓
Background refresh
       ↓
New cache value
       ↓
Users continue receiving cached data

Real-World Scenario

Imagine a dashboard showing:

Daily Revenue
Active Policies
Open Claims
Pending Payments

Suppose the dashboard is requested heavily between:

9:00 AM - 6:00 PM

You don’t necessarily want the first user at 9:00 AM to trigger a large aggregation query.

Instead, a scheduled job can refresh the cache before users need it.

Laravel scheduler:

Schedule::job(RefreshDashboardCache::class)
    ->everyTenMinutes();

The job could calculate the latest dashboard metrics and update the cache.

6️⃣ Stale-While-Revalidate

One of the most useful patterns for high-traffic applications is:

Stale-While-Revalidate

The idea is simple:

Fresh Data
   ↓
Return immediately

Stale but usable
   ↓
Return stale data
   +
Refresh in background

Expired
   ↓
Generate fresh data

This avoids making users wait for expensive cache regeneration.

Laravel Example

Laravel provides support for stale-while-revalidate behavior through Cache::flexible().

$data = Cache::flexible(
    'dashboard',
    [300, 600],
    function () {
        return $this->generateDashboard();
    }
);

The two values represent the fresh and stale periods.

Why Is This Powerful?

Imagine generating a report takes:

2 seconds

And 500 users request the same report.

Without stale-while-revalidate:

Cache expires
     ↓
Users wait for regeneration

With stale-while-revalidate:

Existing stale result
     ↓
Return immediately
     ↓
Refresh asynchronously

Users get a much smoother experience.

7️⃣ Cache External API Responses

Caching isn’t limited to databases.

External APIs can also be expensive and slow.

Consider:

Laravel
   ↓
Tax API
   ↓
External Service

If the same tax information is requested repeatedly, calling the external API for every request is unnecessary.

Instead:

$taxRate = Cache::remember(
    "tax-rate:{$state}:{$year}",
    now()->addDay(),
    function () use ($state, $year) {
        return $this->taxApi->getRate($state, $year);
    }
);

Now:

Request 1 → API
Request 2 → Cache
Request 3 → Cache
Request 4 → Cache

Real-World Scenario

Suppose an application needs:

Currency Exchange Rates
Tax Rates
Shipping Rates
Weather Information
Third-Party Configuration

These values may not need to be fetched from the external provider on every request.

Caching can:

• Reduce API usage

• Reduce latency

• Reduce external dependency

• Protect against temporary API failures

8️⃣ Event-Based Cache Invalidation

One of the hardest problems in caching is:

When should the cache be invalidated?

Consider:

$product = Cache::remember(
    "product:{$id}",
    3600,
    fn () => Product::find($id)
);

Now the product changes.

If you don’t remove the cache:

Database
Price = ₹999

Cache
Price = ₹799

The application may return incorrect information until the TTL expires.

Use Events

Laravel events can help coordinate cache invalidation.

For example:

class ProductUpdated
{
    public function __construct(
        public Product $product
    ) {}
}

Listener:

class ClearProductCache
{
    public function handle(ProductUpdated $event): void
    {
        Cache::forget(
            "product:{$event->product->id}"
        );
    }
}

Now:

Product Updated
      ↓
Event
      ↓
Invalidate Cache
      ↓
Next request
      ↓
Database
      ↓
Repopulate Cache

This is a clean implementation of Cache-Aside with event-driven invalidation.

Building an API is easy.

Building an API that continues to work well as your application grows, your frontend requirements change, and multiple clients consume the same backend—that’s where things become interesting.

Imagine you’re building an e-commerce platform with three different clients:

• A React web application

• A Flutter mobile application

• An admin dashboard

All three applications use the same Laravel backend, but they don’t necessarily need the same data.

For example, the mobile application might only need a product’s basic information:

Product
├── id
├── name
├── price
└── image

The product listing page might need:

Product
├── id
├── name
├── price
├── image
├── rating
└── stock

While the admin dashboard might need considerably more:

Product
├── id
├── name
├── description
├── price
├── stock
├── categories
├── reviews
├── supplier
├── sales
└── inventory

This creates an interesting API design problem.

With a traditional REST approach, you might start with an endpoint such as:

GET /api/products/100

But as different clients require different representations of the same resource, you may eventually find yourself adding more endpoints, query parameters, response transformations, or specialized APIs.

You can also run into two common problems.

⭐ Over-fetching

The API returns more data than the client needs.

{
    "id": 100,
    "name": "MacBook Pro",
    "price": 1999,
    "description": "...",
    "stock": 25,
    "supplier": "...",
    "created_at": "...",
    "updated_at": "..."
}

The mobile application might only need:

{
    "id": 100,
    "name": "MacBook Pro",
    "price": 1999
}

The remaining fields are unnecessary for that particular screen.

⭐ Under-fetching

The opposite problem can also occur.

Suppose a customer details page needs:

Customer
 ├── Profile
 ├── Orders
 │    └── Order Items
 │          └── Products
 └── Payments

With REST, this might require several API calls:

GET /api/customers/10
GET /api/customers/10/orders
GET /api/orders/100/items
GET /api/customers/10/payments

The frontend now has to make multiple requests and combine the results.

This is where GraphQL becomes interesting.

Instead of defining the response entirely on the server, GraphQL allows the client to describe exactly what data it needs.

For example:

query {
    customer(id: 10) {
        id
        name

        orders {
            id
            orderNumber

            items {
                quantity
                product {
                    id
                    name
                    price
                }
            }
        }

        payments {
            amount
            status
        }
    }
}

The server returns a response that follows the exact structure requested by the client.

{
    "data": {
        "customer": {
            "id": "10",
            "name": "John Doe",
            "orders": [
                {
                    "id": "100",
                    "orderNumber": "ORD-1001",
                    "items": [
                        {
                            "quantity": 2,
                            "product": {
                                "id": "50",
                                "name": "MacBook Pro",
                                "price": 1999
                            }
                        }
                    ]
                }
            ],
            "payments": [
                {
                    "amount": 3998,
                    "status": "PAID"
                }
            ]
        }
    }
}

The important idea is not simply that GraphQL can retrieve data through a single endpoint.

The bigger idea is this:

GraphQL allows the client to describe the shape of the data it needs, while the server controls what data and operations are actually available.

This makes GraphQL particularly interesting for applications with multiple clients, complex relationships, and rapidly changing frontend requirements.

But GraphQL is not a replacement for REST in every situation.

It introduces its own challenges, including:

• Schema design

• Authorization

• N+1 database queries

• Query complexity

• Query depth

• Pagination

• Caching

• Security

• Schema evolution

So the real question isn’t:

“Is GraphQL better than REST?”

⚡ Why Was GraphQL Created ?

Traditional REST APIs generally expose resources through URLs.

For example:

GET /users/1
GET /users/1/orders
GET /users/1/orders/10/items

As applications become more complex, clients can end up making many requests to construct a single screen.

Consider an order details page.

The page needs:

Customer
Order
Order Items
Products
Shipping Address
Payment

A REST implementation might require:

GET /customers/10
GET /customers/10/orders/100
GET /orders/100/items
GET /orders/100/shipping-address
GET /orders/100/payment

GraphQL allows the client to describe this relationship as a single query:

query {
    order(id: 100) {
        id
        orderNumber
        status

        customer {
            id
            name
            email
        }

        items {
            quantity
            price

            product {
                id
                name
            }
        }

        shippingAddress {
            city
            state
            country
        }

        payment {
            status
            amount
        }
    }
}

This is one of the most powerful ideas behind GraphQL.

🔷 GraphQL Core Concepts

Before implementing GraphQL in Laravel, you need to understand a few fundamental concepts.

The most important ones are:

Schema
Type
Query
Mutation
Field
Argument
Input
Resolver
Scalar
Enum
Interface
Union
Subscription

Let’s understand them one by one.

👉 Schema

The schema defines what your GraphQL API supports.

For example:

type Product {
    id: ID!
    name: String!
    price: Float!
}

This tells GraphQL that a Product has:

id
name
price

The schema is effectively the contract between the frontend and backend.

If a client requests a field that doesn’t exist:

query {
    product(id: 1) {
        id
        unknownField
    }
}

GraphQL can reject the query because unknownField isn’t part of the schema.

👉 GraphQL Types

A type describes the structure of an object.

For example:

type User {
    id: ID!
    name: String!
    email: String!
}

Here:

User

is a GraphQL object type.

It contains three fields:

id
name
email

👉 GraphQL Scalar Types

GraphQL provides several built-in scalar types.

String
Int
Float
Boolean
ID

Example:

type Product {
    id: ID!
    name: String!
    quantity: Int!
    price: Float!
    isActive: Boolean!
}

The exclamation mark is important.

name: String!

means:

name cannot be null.

While:

description: String

means:

description may be null.

👉 Query

A query is used to read data.

For example:

query {
    products {
        id
        name
        price
    }
}

Conceptually:

GraphQL Query = REST GET

But GraphQL gives the client much more control over the requested response shape.

👉 Mutation

A mutation is used to modify data.

Typical mutation operations include:

Create
Update
Delete

For example:

mutation {
    createProduct(
        name: "MacBook Pro"
        price: 1999
    ) {
        id
        name
        price
    }
}

Conceptually:

Query     → Read
Mutation  → Write

👉 Arguments

Fields can accept arguments.

For example:

type Query {
    product(id: ID!): Product
}

The client can call:

query {
    product(id: 10) {
        id
        name
        price
    }
}

Here:

id

is an argument.

👉 Input Types

When mutations become more complex, use input types.

Instead of:

createProduct(
    name: String!
    description: String
    price: Float!
)

define:

input CreateProductInput {
    name: String!
    description: String
    price: Float!
}

Then:

type Mutation {
    createProduct(
        input: CreateProductInput!
    ): Product!
}

The client can send:

mutation {
    createProduct(
        input: {
            name: "MacBook Pro"
            description: "Apple laptop"
            price: 1999
        }
    ) {
        id
        name
        price
    }
}

Input types become especially useful as mutations evolve.

👉 Resolver

Resolver is the piece of code that tells GraphQL:

“When the client asks for this field, where should I get the data from?”

Think of a resolver as a bridge between the GraphQL query and your actual application/database.

Simple example

Suppose the client sends:

query {
    user(id: 10) {
        id
        name
        email
    }
}

GraphQL knows that there is a user field, but it doesn’t automatically know how to find user 10.

The resolver handles that:

public function user($root, array $args)
{
    return User::find($args['id']);
}

An important point

You don’t necessarily need to write a resolver for every field.

If Laravel’s Eloquent relationship already provides the data, your GraphQL library may automatically resolve it.

For example:

class Order extends Model
{
    public function customer()
    {
        return $this->belongsTo(Customer::class);
    }

    public function items()
    {
        return $this->hasMany(OrderItem::class);
    }
}

GraphQL can use these relationships to resolve:

order {
    customer {
        name
    }

    items {
        quantity
    }
}

👉 Enum

An Enum (Enumeration) is a GraphQL type that defines a fixed list of allowed values.

In simple words:

Enum means: “You can choose only from these predefined values.”

Suppose an order can have only these statuses:

pending
processing
shipped
delivered
cancelled

Instead of allowing the client to send any random string:

status: "hello"
status: "something"
status: "abc"

we define an Enum:

enum OrderStatus {
    PENDING
    PROCESSING
    SHIPPED
    DELIVERED
    CANCELLED
}

Now GraphQL knows:

OrderStatus can contain only these five values.

👉 Interface

A GraphQL Interface is a way to define a common set of fields that multiple types must have.

In simple words:

Interface = a common contract shared by multiple GraphQL types.

If different types have some common fields, instead of repeating those fields, you can define them once in an interface.

We can create an interface:

interface User {
    id: ID!
    name: String!
    email: String!
}

Then tell GraphQL that these types implement the interface:

type Customer implements User {
    id: ID!
    name: String!
    email: String!
    orders: [Order!]!
}

type Admin implements User {
    id: ID!
    name: String!
    email: String!
    permissions: [String!]!
}

type Seller implements User {
    id: ID!
    name: String!
    email: String!
    products: [Product!]!
}

Now Customer, Admin, and Seller must provide:

id
name
email

because those fields are defined by the User interface.

⚙️ Setting Up GraphQL in Laravel

Laravel doesn’t provide GraphQL functionality in the same way it provides Eloquent or routing, so you normally install a GraphQL package.

A popular Laravel option is Lighthouse.

Install it with Composer:

composer require nuwave/lighthouse

Then publish its configuration:

php artisan vendor:publish --tag=lighthouse-config

You should then have:

config/
└── lighthouse.php

⭐ GraphQL Best Practices

Design Your Schema Around the Business Domain

Keep Resolvers Thin

Use Input Types for Mutations

Use Enums for Fixed Values

Validate Mutation Input

📌 Conclusion

GraphQL provides a flexible and efficient way to build modern APIs by allowing clients to request exactly the data they need.
When combined with Laravel, it works well with Eloquent, authentication, validation, and Laravel's existing application architecture.
Understanding Queries, Mutations, Resolvers, Types, Enums, Interfaces, and Subscriptions gives you a strong foundation for GraphQL development.
With proper schema design, authorization, pagination, and performance optimization, you can build scalable and maintainable GraphQL APIs.

A seemingly simple “Place Order” action might actually involve:

• 🔍 Validating the order

• 💰 Calculating discounts

• 🧮 Calculating tax

• 📦 Reserving inventory

• 💳 Charging the customer

• 💾 Persisting the order

• 📢 Publishing events

• 📧 Sending notifications

When all of this logic lives inside one service method, the code can quickly become difficult to understand and maintain.

That’s where the Pipeline Design Pattern can help.

Laravel already provides an excellent implementation through:

Illuminate\Pipeline\Pipeline

In this article, we’ll use one example throughout the entire article: an e-commerce order-processing workflow.

🧩 What Is the Pipeline Design Pattern?

The Pipeline Design Pattern allows us to divide a large workflow into a sequence of smaller processing steps.

Each step is called a pipe.

Imagine our order-processing workflow:

Instead of one large method containing everything, each operation gets its own class.

The fundamental idea is:

A pipeline passes a payload through a sequence of processing steps, where each step performs one responsibility and passes the payload to the next step.

This gives us three important properties:

• 🎯 Separation of concerns

• 🧪 Better testability

• 🧱 Composable workflows

😰 The Problem: A Growing Service Class

Let’s start with our order-processing example.

A traditional implementation might look something like this:

public function processOrder(Order $order)
{
    $this->validateOrder($order);

    $discount = $this->calculateDiscount($order);

    $tax = $this->calculateTax($order, $discount);

    $this->inventoryService->reserve($order);

    $paymentId = $this->paymentService->charge($order);

    $this->orderRepository->save(
        $order,
        $discount,
        $tax,
        $paymentId
    );
}

At first, this isn’t bad.

But requirements rarely stay simple.

Soon we might need:

Validate order
Validate customer
Apply coupon
Calculate discount
Calculate tax
Check inventory
Reserve inventory
Check payment limit
Charge payment
Create invoice
Persist order
Publish event
Send notification

Our service starts growing.

Eventually:

public function processOrder(...)
{
    // 300+ lines of business logic
}

Now we have a problem.

Adding one new business rule requires modifying the same large service.

Testing one operation may require setting up the entire workflow.

Understanding the workflow requires reading a large amount of code.

This is a good candidate for a Pipeline.

🏗️ Introducing Laravel Pipeline

Laravel gives us:

use Illuminate\Pipeline\Pipeline;

We can define our workflow like this:

app(Pipeline::class)
    ->send($context)
    ->through([
        ValidateOrder::class,
        CalculateDiscount::class,
        CalculateTax::class,
        ReserveInventory::class,
        ChargePayment::class,
        PersistOrder::class,
    ])
    ->thenReturn();

At first glance, this looks simple.

But there are three important methods here.

📦 send()

->send($context)

This defines the object that enters the pipeline.

In our example, that object represents the current order-processing state.

🔗 through()

->through([
    ValidateOrder::class,
    CalculateDiscount::class,
    CalculateTax::class,
    ReserveInventory::class,
    ChargePayment::class,
    PersistOrder::class,
])

This defines the sequence of pipes.

The order matters.

For example:

Validate
   ↓
Discount
   ↓
Tax
   ↓
Inventory
   ↓
Payment
   ↓
Persist

is different from:

Payment
   ↓
Validate
   ↓
Persist

The pipeline makes this order explicit.

🏁 thenReturn()

->thenReturn();

This executes the pipeline and returns the final payload.

Laravel also provides then() when you want to define a final destination manually.

📦 What Should We Pass Through the Pipeline?

Our order workflow needs to carry information between pipes.

For example:

Order
Discount
Tax
Inventory status
Payment ID
Payment status
Metadata

We could pass these around individually, but that quickly becomes messy.

Instead, create an OrderContext.

final class OrderContext
{
    public function __construct(
        public Order $order,
        public float $discount = 0,
        public float $tax = 0,
        public bool $inventoryReserved = false,
        public bool $paymentCharged = false,
        public ?string $paymentId = null,
    ) {}
}

Now every pipe receives the same object:

public function handle(
    OrderContext $context,
    Closure $next
): OrderContext

This gives the pipeline a clear contract.

🔄 How Does a Pipe Work?

A typical Laravel pipe looks like this:

class CalculateDiscount
{
    public function handle(
        OrderContext $context,
        Closure $next
    ): OrderContext {

        // Process current step

        return $next($context);
    }
}

There are two important things here:

$context

and:

$next

The context is our data.

The $next callback represents the remaining pipeline.

When we write:

return $next($context);

we are saying:

“My work is complete. Pass this context to the next pipe.”

This is the most important line to understand when learning Laravel Pipeline.

🛠️ Building Our Order Pipeline

Now let’s implement our workflow.

Our pipeline will contain six pipes:

1️⃣ ValidateOrder
2️⃣ CalculateDiscount
3️⃣ CalculateTax
4️⃣ ReserveInventory
5️⃣ ChargePayment
6️⃣ PersistOrder

The final configuration becomes:

app(Pipeline::class)
    ->send($context)
    ->through([
        ValidateOrder::class,
        CalculateDiscount::class,
        CalculateTax::class,
        ReserveInventory::class,
        ChargePayment::class,
        PersistOrder::class,
    ])
    ->thenReturn();

Notice how easy the workflow is to read.

A developer can understand the high-level business process without reading every implementation.

That’s one of the biggest advantages of Pipeline.

🔍 Pipe #1: Validate Order

The first pipe validates the order.

class ValidateOrder
{
    public function handle(
        OrderContext $context,
        Closure $next
    ): OrderContext {

        if ($context->order->items->isEmpty()) {
            throw new ValidationException(
                'Order must contain at least one item.'
            );
        }

        return $next($context);
    }
}

This pipe has one job:

Validate the order.

It doesn’t calculate tax.

It doesn’t charge payment.

It doesn’t reserve inventory.

That separation is intentional.

🏷️ Pipe #2: Calculate Discount

Suppose our business rule is:

Order >= $1,000 → 10% discount
Order >= $500   → 5% discount
Otherwise       → No discount

The pipe can implement that rule:

class CalculateDiscount
{
    public function handle(
        OrderContext $context,
        Closure $next
    ): OrderContext {

        $subtotal = $context->order->subtotal;

        if ($subtotal >= 1000) {
            $context->discount = $subtotal * 0.10;
        } elseif ($subtotal >= 500) {
            $context->discount = $subtotal * 0.05;
        }

        return $next($context);
    }
}

Again, one responsibility.

🧮 Pipe #3: Calculate Tax

Now the tax pipe uses the values calculated by the previous pipe.

class CalculateTax
{
    public function handle(
        OrderContext $context,
        Closure $next
    ): OrderContext {

        $taxableAmount =
            $context->order->subtotal
            - $context->discount;

        $context->tax = $taxableAmount * 0.18;

        return $next($context);
    }
}

Notice something important.

The pipeline allows one pipe to prepare information for the next pipe.

Discount Pipe
      │
      ▼
context->discount
      │
      ▼
Tax Pipe

This is why the shared context is useful.

📦 Pipe #4: Reserve Inventory

Now we have a side effect.

The inventory service reserves the products.

class ReserveInventory
{
    public function __construct(
        private InventoryService $inventory
    ) {}

    public function handle(
        OrderContext $context,
        Closure $next
    ): OrderContext {

        $this->inventory->reserve(
            $context->order
        );

        $context->inventoryReserved = true;

        return $next($context);
    }
}

Laravel’s service container resolves InventoryService automatically.

This is another advantage of using Laravel Pipeline rather than manually creating every pipe.

💳 Pipe #5: Charge Payment

Now we charge the customer.

class ChargePayment
{
    public function __construct(
        private PaymentService $payment
    ) {}

    public function handle(
        OrderContext $context,
        Closure $next
    ): OrderContext {

        $paymentId = $this->payment->charge(
            $context->order->id,
            $context->order->total
        );

        $context->paymentId = $paymentId;
        $context->paymentCharged = true;

        return $next($context);
    }
}

This operation is different from calculating tax.

It interacts with an external system.

That difference becomes very important when we discuss failure handling.

💾 Pipe #6: Persist the Order

Finally, we save the order.

class PersistOrder
{
    public function handle(
        OrderContext $context,
        Closure $next
    ): OrderContext {

        $context->order->update([
            'discount' => $context->discount,
            'tax' => $context->tax,
            'total' =>
                $context->order->subtotal
                - $context->discount
                + $context->tax,
            'payment_id' => $context->paymentId,
            'status' => 'completed',
        ]);

        return $next($context);
    }
}

❌ What Happens When a Pipe Fails?

Now let’s look at the most important production question:

What happens when something goes wrong?

Suppose payment fails:

🔍 Validate       ✅
🏷️ Discount       ✅
🧮 Tax            ✅
📦 Inventory      ✅
💳 Payment        ❌
💾 Persist        ⛔

The payment pipe throws an exception:

throw new PaymentException(
    'Payment provider rejected the payment.'
);

The pipeline stops normal forward execution.

PersistOrder doesn’t execute.

This behavior is useful because later operations don’t run after a failure.

But we now have another problem.

Inventory was already reserved.

⚠️ Pipeline Does NOT Automatically Roll Back

This is one of the biggest misconceptions about Pipeline.

You might think:

“If payment fails, Laravel will automatically undo inventory reservation.”

It won’t.

Pipeline controls execution flow.

It doesn’t know how to reverse your business operations.

So we have:

📦 Inventory Reserved
        ↓
💳 Payment Failed
        ↓
❓ Inventory is still reserved

We need an explicit strategy.

🎯 Best Practices

1. Give Every Pipe One Responsibility

Good:

ValidateOrder
CalculateDiscount
CalculateTax

Avoid:

ProcessEntireOrder

2. Keep the Pipeline Declaration Easy to Read

This is good:

->through([
    ValidateOrder::class,
    CalculateDiscount::class,
    CalculateTax::class,
    ReserveInventory::class,
    ChargePayment::class,
    PersistOrder::class,
])

The code itself documents the workflow.

3. Keep Side Effects Explicit

A pipe called:

CalculateTax

shouldn’t secretly charge a payment.

Predictability is important.

4. Make Failure Behavior Explicit

Every pipe should have a clear answer to:

What happens if this operation fails?

For example:

Validation
   → Stop

Inventory
   → Stop

Payment
   → Stop + release inventory

Persistence
   → Stop + refund payment + release inventory

5. Don’t Make Everything a Pipe

This is important.

If a method contains two simple operations and is already easy to understand, introducing five pipe classes may make the design worse.

Use abstraction when it provides value.

6. Keep External Side Effects in Mind

Before introducing:

Payment
Email
External API
Message Queue

ask:

“How will I handle this if a later step fails?”

That question can prevent many production problems.

⚖️ Pipeline Trade-offs

Pipeline has significant benefits.

✅ Separation of Concerns

Each pipe focuses on one task.

✅ Readability

The workflow becomes explicit.

✅ Testability

Pipes can be tested independently.

✅ Extensibility

New steps can be added without turning one service into a giant method.

✅ Reusability

Pipes can potentially be reused across workflows.

But there are trade-offs.

❌ More Classes

A six-step workflow may require six pipe classes.

❌ More Indirection

Developers need to jump between classes to understand the implementation.

❌ Shared State Can Become Complicated

A large context object can eventually become difficult to manage.

❌ Rollback Isn’t Automatic

Pipeline doesn’t provide transaction semantics.

❌ Distributed Workflows Need More Architecture

🚦 When Should You Use Pipeline?

Pipeline is a good fit when:

🔹 You have a sequential workflow

A → B → C → D

🔹 Each step has a clear responsibility

Validate
Transform
Calculate
Persist

🔹 The workflow changes frequently

Pipes can be added, removed, or reordered.

🔹 Steps need to be tested independently

Each pipe can have focused tests.

🔹 The processing sequence is important

The pipeline makes the sequence explicit.

🛑 When Should You NOT Use Pipeline?

Don’t use Pipeline just because Laravel provides it.

For example, this would be unnecessary:

app(Pipeline::class)
    ->send($user)
    ->through([
        LoadUser::class,
        UpdateUser::class,
    ])
    ->thenReturn();

if all you really need is:

$user->update([
    'name' => $name,
]);

The goal of a design pattern is not to make code more sophisticated.

The goal is to make the system easier to understand, change, and maintain.

🏁 Final Conclusion

The Laravel Pipeline Pattern is much more than a convenient way to divide a large method into several smaller classes. Its real value is in making the flow of a business process explicit, predictable, and easier to evolve.

The Pipeline Design Pattern isn’t about creating more classes.

It’s about giving a complex workflow a clear structure.

Imagine you’re running a restaurant.

Your chef shouldn’t have to leave the kitchen every time they need a fresh ingredient. They shouldn’t care whether the ingredient comes from Supplier A, Supplier B, or a local farmer.

They simply say:

“I need tomatoes.”

The restaurant’s supply system figures out where those tomatoes should come from.

Dependency Injection works the same way.

Instead of a class creating everything it needs by itself, you give it the dependencies it needs from the outside.

In Laravel, the Service Container takes this idea even further. It can automatically figure out which classes your application needs and resolve them for you.

This becomes especially useful when working with external API clients, payment gateways, repositories, database services, and other application services.

For example, this controller looks innocent:

class PaymentController extends Controller
{
    public function pay()
    {
        $paymentService = new StripePaymentService();
        return $paymentService->charge();
    }
}

But now the controller is tightly coupled to StripePaymentService.

Want to switch to PayPal?

You have to modify the controller.

Want to mock the payment service in a test?

You have another problem.

Want to reuse the controller with a different implementation?

Things get messy quickly.

That’s where Dependency Injection (DI) comes in.

In simple terms:

Dependency Injection means giving a class the objects it needs instead of making the class create those objects itself.

And Laravel’s Service Container does most of the heavy lifting for you.

❌ The Problem: Without DI and Tight Coupling

Let’s start with a typical Laravel payment controller.

Suppose we have this service:

namespace App\Services;
class StripePaymentService
{
    public function charge(): string
    {
        return "Payment processed through Stripe.";
    }
}

Now our controller directly creates that service:

namespace App\Http\Controllers;
use App\Services\StripePaymentService;
class PaymentController extends Controller
{
    public function pay()
    {
        $paymentService = new StripePaymentService();
        return $paymentService->charge();
    }
}

At first glance, this works perfectly.

So what’s the problem?

The controller knows too much.

It knows that:

• Stripe is being used.

• StripePaymentService is the implementation.

• The service must be created using new.

• Stripe is the payment provider.

The controller is now tightly coupled to a concrete implementation.

👉 Problem #1: Testing Becomes Difficult

Imagine writing a PHPUnit or Pest test.

You don’t actually want to call Stripe while running your unit tests.

You want to replace the real payment service with a mock.

But the controller does this:

$paymentService = new StripePaymentService();

The controller creates the dependency itself.

That makes replacing it much harder.

You can’t simply tell the controller:

"Use this mock instead."

because the controller has already decided which concrete class to instantiate.

👉 Problem #2: Switching Payment Providers

Suppose your business decides to move from Stripe to PayPal.

You might end up changing:

$paymentService = new StripePaymentService();

to:

$paymentService = new PayPalPaymentService();

Now the controller contains payment-provider-specific logic.

And imagine having this dependency in ten different controllers.

You now have ten places to update.

That’s a maintenance problem.

👉 Problem #3: Controllers Become Responsible for Object Creation

A controller should primarily coordinate application behavior.

It shouldn’t be responsible for figuring out how every dependency should be constructed.

This:

public function pay()
{
    $paymentService = new StripePaymentService();

    return $paymentService->charge();
}

mixes two responsibilities:

1. Creating the dependency.

2. Using the dependency.

DI separates those responsibilities.

✅ The Solution: Dependency Injection

Let’s refactor the same controller.

Instead of creating StripePaymentService ourselves, we inject it through the constructor.

namespace App\Http\Controllers;
use App\Services\StripePaymentService;
class PaymentController extends Controller
{
    public function __construct(private StripePaymentService $paymentService) {}
    public function pay()
    {
        return $this->paymentService->charge();
    }
}

Notice what’s gone:

new StripePaymentService();

The controller no longer creates the service.

Instead, we tell Laravel:

“This controller needs a StripePaymentService.”

Laravel figures out how to provide it.

That’s Constructor Injection.

🎯 How Laravel Automatically Resolves Dependencies

This is where Laravel’s Service Container becomes powerful.

When Laravel needs to create:

PaymentController

it sees:

private StripePaymentService $paymentService

Laravel inspects the constructor and understands:

If StripePaymentService doesn’t have any complicated dependencies, Laravel can automatically instantiate it.

This is called automatic resolution or auto-wiring.

For example:

class StripePaymentService
{
    public function charge(): string
    {
        return "Payment processed through Stripe.";
    }
}

Laravel can resolve this automatically because it is a concrete class that doesn’t require any unresolved dependencies.

So you don’t need to manually write:

app()->make(StripePaymentService::class);

and you don’t need:

new StripePaymentService();

Laravel’s container handles it.

⚖️ Constructor Injection vs. Manual Instantiation

Without DI:

class PaymentController extends Controller
{
    public function pay()
    {
        $service = new StripePaymentService();
        return $service->charge();
    }
}

With DI:

class PaymentController extends Controller
{
    public function __construct(private StripePaymentService $service) {}
    public function pay()
    {
        return $this->service->charge();
    }
}

The second version is cleaner because the controller doesn’t care how the service is created.

It only cares that it has a service it can use.

🔌 Dependency Injection with Interfaces

Constructor injection is already useful.

But we can make our application even more flexible.

Instead of making the controller depend on:

StripePaymentService

we can make it depend on an interface:

PaymentGatewayInterface

This is where DI becomes really powerful.

Let’s create the interface.

namespace App\Contracts;

interface PaymentGatewayInterface
{
    public function charge(): string;
}

Now Stripe implements that interface:

namespace App\Services;
use App\Contracts\PaymentGatewayInterface;
class StripePaymentService implements PaymentGatewayInterface
{
    public function charge(): string
    {
        return "Payment processed through Stripe.";
    }
}

Our controller no longer needs to know about Stripe.

It only knows about the contract.

namespace App\Http\Controllers;

use App\Contracts\PaymentGatewayInterface;

class PaymentController extends Controller
{
    public function __construct(
        private PaymentGatewayInterface $paymentGateway
    ) {
    }

    public function pay()
    {
        return $this->paymentGateway->charge();
    }
}

But there’s one problem.

Laravel knows how to automatically resolve concrete classes.

It doesn’t automatically know which implementation should be used for:

PaymentGatewayInterface

There could be several implementations.

For example:

StripePaymentService
PayPalPaymentService
RazorpayPaymentService

So we need to tell Laravel:

“Whenever someone asks for PaymentGatewayInterface, give them StripePaymentService.”

🔧 Binding the Interface to an Implementation

The natural place for this binding is a service provider.

For example:

namespace App\Providers;
use App\Contracts\PaymentGatewayInterface;
use App\Services\StripePaymentService;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(
            PaymentGatewayInterface::class,
            StripePaymentService::class,
        );
    }
}

Now Laravel has a mapping:

PaymentGatewayInterface
          ↓
StripePaymentService

Whenever Laravel sees:

PaymentGatewayInterface

it knows to resolve:

StripePaymentService

Our controller remains completely unaware of Stripe.

class PaymentController extends Controller
{
    public function __construct(
        private PaymentGatewayInterface $paymentGateway
    ) {
    }

    public function pay()
    {
        return $this->paymentGateway->charge();
    }
}

This is a major architectural improvement.

🔄 Switching from Stripe to PayPal

Now imagine the business decides to use PayPal.

Create another implementation:

namespace App\Services;
use App\Contracts\PaymentGatewayInterface;
class PayPalPaymentService implements PaymentGatewayInterface
{
    public function charge(): string
    {
        return "Payment processed through PayPal.";
    }
}

Then change the container binding:

$this->app->bind(
    PaymentGatewayInterface::class,
    PayPalPaymentService::class
);

That’s it.

The controller doesn’t change.

class PaymentController extends Controller
{
    public function __construct(
        private PaymentGatewayInterface $paymentGateway,
    ) {}
    public function pay()
    {
        return $this->paymentGateway->charge();
    }
}

The controller doesn’t know whether it’s using:

Stripe
PayPal
Razorpay
Adyen
MockPaymentGateway

It only knows:

PaymentGatewayInterface

That’s true decoupling.

🎯 Key Benefits of Dependency Injection in Laravel

1. Painless Unit Testing

One of the biggest advantages of DI is testability.

Because the dependency is injected, you can replace the real implementation with a mock.

For example, Laravel’s container can bind a mock:

$this->mock(PaymentGatewayInterface::class, function ($mock) {
    $mock->shouldReceive('charge')
        ->once()
        ->andReturn('Payment successful.');
});

Now your test doesn’t need to call a real payment provider.

You can also use Mockery directly:

$gateway = Mockery::mock(PaymentGatewayInterface::class);

$gateway->shouldReceive('charge')
    ->once()
    ->andReturn('Payment successful.');

This makes unit tests faster, deterministic, and safer.

You don’t want your PHPUnit test suite accidentally charging a real credit card.

2. True Decoupling and Flexibility

Without DI:

class PaymentController
{
    public function pay()
    {
        $service = new StripePaymentService();
    }
}

The controller depends directly on Stripe.

With DI:

class PaymentController
{
    public function __construct(
        private PaymentGatewayInterface $paymentGateway
    ) {
    }
}

The controller depends on an abstraction.

That’s the important difference.

You can change the implementation without rewriting the controller.

3. Simpler, Cleaner Controllers

A controller shouldn’t be responsible for constructing a dependency graph.

Avoid this:

public function pay()
{
    $client = new StripeClient();
    $logger = new PaymentLogger();
    $repository = new PaymentRepository();
    $service = new PaymentService(
        $client,
        $logger,
        $repository
    );

    return $service->process();
}

Instead, let Laravel resolve the dependency graph:

public function __construct(
    private PaymentService $paymentService
) {
}

Your controller becomes easier to read.

And more importantly, it becomes easier to change.

🚀 Conclusion: Let Laravel Handle the Heavy Lifting

Dependency Injection can sound like a complicated architectural concept.

In practice, the idea is simple:

Don’t make a class create the things it needs. Give it those things instead.

Laravel makes this especially powerful through its Service Container.

You can start with simple constructor injection:

public function __construct(
    private PaymentService $paymentService
) {
}

And when you need more flexibility, introduce an interface:

public function __construct(
    private PaymentGatewayInterface $paymentGateway
) {
}

Then bind the implementation:

$this->app->bind(
    PaymentGatewayInterface::class,
    StripePaymentService::class
);

Now your controllers don’t care about concrete implementations.

They care about contracts.

That’s the real value of Dependency Injection.

It gives you:

• Cleaner controllers

• Easier testing

• Looser coupling

• Swappable implementations

• More maintainable architecture

And the best part?

Laravel’s Service Container handles most of the heavy lifting for you.

At first, everything feels manageable.

Your application only needs to save data to the database.

Later, product requirements evolve.

Marketing wants an email.

Finance wants an invoice.

Operations wants analytics.

Customer Support wants notifications.

The Product team wants reward points.

Engineering wants audit logs.

Before long, your once-simple controller has become responsible for half of your application’s business logic.

If you’ve ever opened a controller and found hundreds of lines of code performing unrelated tasks, you’re not alone.

This is exactly the problem Laravel’s Event-Driven Architecture solves.

Instead of placing every responsibility inside your controller, Laravel allows you to announce that something happened, while independent components react to that event.

In this article, we’ll build a complete Uber Ride Booking workflow using Laravel Events and Listeners and learn why this design pattern is used in production applications.

🚨 The Problem We’re Trying to Solve

Imagine we’re building an Uber-like ride booking platform.

When a rider completes a trip, several things need to happen.

• Save ride information

• Charge the customer

• Send an email receipt

• Generate an invoice

• Update the driver’s earnings

• Award loyalty points

• Notify the accounting team

• Store analytics data

• Trigger a webhook for third-party integrations

Most developers initially write everything inside the controller.

public function completeRide(Request $request)
{
    $ride = Ride::create([
        'driver_id' => $request->driver_id,
        'rider_id'  => $request->rider_id,
        'fare'      => $request->fare,
        'status'    => 'completed',
    ]);

    PaymentService::charge($ride);

    Mail::to($ride->rider)->send(new RideReceiptMail($ride));

    InvoiceService::generate($ride);

    DriverService::updateEarnings($ride);

    RewardPointService::addPoints($ride);

    AnalyticsService::trackRide($ride);

    Notification::send(
        User::accountingTeam(),
        new RideCompletedNotification($ride)
    );

    return response()->json([
        'message' => 'Ride Completed'
    ]);
}

At first glance, this code looks perfectly fine.

Everything works.

So what’s wrong?

The problem isn’t functionality.

The problem is architecture.

⛔ Why This Controller Is a Problem

Look carefully.

Our controller now knows about:

• Payment Service

• Mail Service

• Invoice Service

• Driver Service

• Reward Service

• Analytics

• Notifications

That’s seven different dependencies.

Now imagine six months later.

Management asks for:

• Send SMS

• Push Notification

• Slack Notification

• Webhook Integration

• Fraud Detection

• AI Recommendation Engine

Guess what happens?

We open the same controller again.

And again.

And again.

Eventually, the controller grows into something like this:

RideController

↓

Create Ride

↓

Charge Customer

↓

Send Email

↓

Generate Invoice

↓

Update Driver Wallet

↓

Update Driver Rating

↓

Reward Rider

↓

Send SMS

↓

Push Notification

↓

Slack Notification

↓

Webhook

↓

Analytics

↓

Audit Logs

↓

Fraud Detection

The controller is no longer responsible for one thing.

It’s responsible for everything.

This violates the Single Responsibility Principle (SRP).

🔔 What Is an Event?

Think about a fire alarm in a building.

When someone pulls the alarm:

• The alarm doesn’t call the fire department.

• It doesn’t contact security.

• It doesn’t evacuate people.

It simply announces:

A fire has occurred.

Different departments react independently.

Fire Alarm

↓

Fire Department Responds

↓

Security Responds

↓

Medical Team Responds

↓

Building Evacuates

Laravel Events work exactly the same way.

An Event simply says:

Something important happened.

Nothing more.

👉 In Our Ride Booking System

When a ride finishes successfully, our application doesn’t need to know who is interested.

It simply announces:

RideCompleted

That’s it.

👂What Is a Listener?

A Listener waits for an event.

When the event occurs, it performs exactly one responsibility.

For our application, we might have these listeners:

RideCompleted

├── ChargeCustomer

├── SendReceiptEmail

├── GenerateInvoice

├── UpdateDriverWallet

├── RewardRider

├── NotifyAccounting

├── StoreAnalytics

Notice something interesting.

Each listener has one job.

Nothing more.

Nothing less.

🎯 Understanding Laravel's Event Flow

Here’s what actually happens internally.

The controller has no idea who receives the event.

Laravel’s Event Dispatcher takes care of everything.

This is called Loose Coupling.

⚡ Why Is This Better?

Imagine tomorrow the business says:

“Whenever a ride completes, also notify our CRM system.”

Without Events:

You modify the controller.

Again.

With Events:

You simply create another listener.

RideCompleted

↓

SyncWithCRM Listener

No controller changes.

No service modifications.

No risk of breaking existing logic.

This follows the Open/Closed Principle (OCP):

Software should be open for extension but closed for modification.

⚖️ Event vs Listener

🖥️ Create the Event

php artisan make:event RideCompleted

Laravel creates:

app/Events/RideCompleted.php

<?php

namespace App\Events;

use App\Models\Ride;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class RideCompleted
{
    use Dispatchable, SerializesModels;

    public function __construct(
        public Ride $ride
    ) {}
}

The Event contains only the data.

It does not

• Send emails

• Charge payment

• Generate invoices

It simply announces

A ride has been completed.

✔️ Controller

<?php

namespace App\Http\Controllers;

use App\Events\RideCompleted;
use App\Models\Ride;
use Illuminate\Http\Request;

class RideController extends Controller
{
    public function completeRide(Request $request)
    {
        $ride = Ride::create([
            'driver_id' => $request->driver_id,
            'rider_id'  => $request->rider_id,
            'fare'      => $request->fare,
            'status'    => 'completed',
        ]);

        RideCompleted::dispatch($ride);

        return response()->json([
            'message' => 'Ride completed successfully.'
        ]);
    }
}

Notice how the controller has only two responsibilities:

• Save the ride

• Dispatch the event

✔️ Charge Customer Listener

php artisan make:listener ChargeCustomer

<?php

namespace App\Listeners;

use App\Events\RideCompleted;
use App\Services\PaymentService;

class ChargeCustomer
{
    public function __construct(
        protected PaymentService $paymentService
    ) {}

    public function handle(RideCompleted $event)
    {
        $this->paymentService->charge(
            $event->ride
        );
    }
}

Responsibility

Only charge payment.

Nothing else.

✔️ Send Receipt Email

php artisan make:listener SendRideReceipt

<?php

namespace App\Listeners;

use App\Events\RideCompleted;
use App\Mail\RideReceiptMail;
use Illuminate\Support\Facades\Mail;

class SendRideReceipt
{
    public function handle(RideCompleted $event)
    {
        Mail::to($event->ride->rider->email)
            ->send(
                new RideReceiptMail($event->ride)
            );
    }
}

we need to create a GenerateInvoice, UpdateDriverWallet, RewardRider, and StoreRideAnalytics all this listeners.

✔️ Register Listeners

In your event registration (such as an event service provider), associate the event with its listeners.

protected $listen = [

    RideCompleted::class => [

        ChargeCustomer::class,

        SendRideReceipt::class,

        GenerateInvoice::class,

        UpdateDriverWallet::class,

        RewardRider::class,

        StoreRideAnalytics::class,

    ],

];

🏆 Conclusion

Laravel Events and Listeners provide a clean and elegant way to build scalable, maintainable applications by separating business logic into independent, reusable components. Instead of overloading controllers with multiple responsibilities, you can simply dispatch an event and let dedicated listeners handle the tasks that follow. This approach promotes loose coupling, improves code organization, and makes it easier to extend your application as new business requirements arise.

Batch processing is one of the most common tasks in Laravel applications. Whether you’re sending emails, generating reports, syncing data, or processing millions of records, chances are you’ve used the chunk() method.

It looks simple, performs well, and is recommended throughout the Laravel documentation.

But there’s a hidden problem.

If you’re updating records while processing them, chunk() can silently skip rows, causing incomplete processing without throwing a single exception.

I first encountered this issue while working on a large-scale document import project for one of our enterprise clients. The system was responsible for importing and processing millions of documents, so we built the solution using Laravel Queues, Artisan commands, and chunk() to process the data efficiently in batches.

The implementation appeared to work perfectly during development and testing. However, in production, we discovered that some documents were never processed. There were no exceptions, no failed jobs, and no obvious signs of failure yet a portion of the data remained unprocessed.

After a detailed investigation, we traced the root cause to our use of Laravel’s chunk() method while updating the same records being processed. This experience reinforced an important lesson: choosing the right batching strategy is just as critical as writing the business logic itself, especially when working with large-scale data processing systems.

Let’s understand why this happens and how to avoid it.

📂 The Document Processing Workflow

Imagine you have a table that stores imported documents.

Each document goes through the following steps:

1. Upload it to cloud storage.

2. Update its status to processed.

To avoid loading millions of records into memory, we used Laravel's chunk() method.

Document::where('status', 'pending')
    ->chunk(1000, function ($documents) {
        foreach ($documents as $document) {
            
            // Upload to storage
            
            $document->update([
                'status' => 'processed'
            ]);
        }
    });

At first glance, this looks like the perfect solution.

But there’s a hidden problem.

🗄️ What Happens Behind the Scenes?

Laravel internally executes queries similar to:

SELECT *
FROM documents
WHERE status = 'pending'
LIMIT 1000 OFFSET 0;

The first chunk returns:

1
2
3
...
1000

Each document is processed successfully.

Its status changes from:

Pending

to

Processed

Everything still looks correct.

🔄 The Dataset Changes

After processing the first batch, those records no longer satisfy:

WHERE status = 'pending'

The pending dataset now starts from the next unprocessed documents.

For simplicity, imagine our table contains only ten documents.

The remaining pending documents are now:

4
5
6
7
8
9
10

Notice that documents 1, 2, and 3 have disappeared from the result because their status changed.

⚠️ Here’s Where the Problem Begins

Laravel now executes the next query using OFFSET.

LIMIT 3 OFFSET 3

The current pending dataset is:

Index    Document ID

0  ---> 4
1  ---> 5
2  ---> 6
3  ---> 7
4  ---> 8
5  ---> 9
6  ---> 10

OFFSET skips the first three rows.

❌ 4
❌ 5
❌ 6

Laravel processes only:

✅ 7
✅ 8
✅ 9

Documents 4, 5, and 6 are never processed.

Document 10 also remains pending because no further chunk includes it in this small example.

The Artisan command completes successfully.

The queue reports success.

No exception is thrown.

But several documents remain unprocessed.

📊 Visualizing the Problem

Initial Pending Documents

1 2 3 4 5 6 7 8 9 10

        │
        ▼

Process First Chunk

[1 2 3]

        │
        ▼

Update Status = Processed

Remaining Pending

4 5 6 7 8 9 10

        │
        ▼

Laravel Executes

OFFSET 3

        │
        ▼

❌ Skip

4 5 6

        │
        ▼

Process Next Chunk

7 8 9

This is exactly why some documents never get processed.

🤔 Why Does This Happen?

The issue isn’t with Laravel.

It’s with OFFSET-based pagination.

When your code updates the same records that your query depends on, the result set changes after every batch.

However, OFFSET continues counting based on the old position.

As a result, some rows are skipped entirely.

✅ The Correct Solution: chunkById()

Instead of relying on OFFSET, Laravel provides chunkById().

Document::where('status', 'pending')
    ->chunkById(1000, function ($documents) {

        foreach ($documents as $document) {

            // Process document

            $document->update([
                'status' => 'processed'
            ]);

        }

    });

Rather than using OFFSET, Laravel keeps track of the last processed primary key.

The queries become:

WHERE id > 0
LIMIT 1000

↓

WHERE id > 1000
LIMIT 1000

↓

WHERE id > 2000
LIMIT 1000

Since primary keys don’t change when the status is updated, every document is processed exactly once.

No skipped records.

No incomplete imports.

⚡ An Additional Performance Benefit

chunkById() isn’t just safer it also performs better on large datasets.

With chunk(), MySQL must scan and discard rows to satisfy large OFFSET values.

For example:

LIMIT 1000 OFFSET 500000

The database still has to read the first 500,000 rows before returning the next 1,000.

With chunkById():

WHERE id > 500000
LIMIT 1000

MySQL can efficiently use the primary key index, making queries much faster for millions of records.

📝 Best Practices

When building document processing pipelines:

• ✅ Use chunk() only for read-only operations.

• ✅ Use chunkById() if you’re updating or deleting records.

• ✅ Keep processing jobs idempotent so they can be retried safely.

• ✅ Test batch-processing logic with production-sized datasets.

• ✅ Monitor processed vs. pending record counts after every batch.

🎯 Key Takeaways

• 🚫 chunk() uses OFFSET pagination.

• 🚫 Updating the records being processed changes the result set.

• 🚫 OFFSET can silently skip records.

• ✅ chunkById() navigates using the primary key instead of OFFSET.

• ✅ Every document is processed exactly once.

• ✅ It also scales better for millions of records.

🎉 Final Thoughts

This wasn’t a Laravel bug it was a subtle behavior of OFFSET-based pagination that surfaced in a real production workload.

Because the job completed successfully, the issue was difficult to detect. We only discovered it after reconciling the number of imported documents against the number of processed documents.

That experience taught our team an important lesson:

Whenever your batch job modifies the same records it is reading, chunkById() should be your default choice.

It’s a small change in code, but it can prevent missing records, incomplete imports, and long hours of production debugging especially when processing millions of documents.

Laravel solves this problem elegantly using Database Seeders.

🔰What Is Database Seeding in Laravel?

Database seeding is the process of populating your database with predefined or fake data using PHP classes.

Laravel seeders allow you to:

• Insert default records (roles, permissions, admin users)

• Generate dummy data for testing

• Maintain consistent data across environments

• Avoid repetitive manual database setup

Seeders are especially useful in local, testing, and staging environments.

⚙️How to Create a Database Seeder in Laravel

Creating a database seeder in Laravel is straightforward and follows a clear, standardized workflow. Seeders allow you to define database data using PHP code, making your setup repeatable and version-controlled.

🛠️ Laravel provides an Artisan command to generate a seeder.

php artisan make:seeder TransactionStatusSeeder

This command creates a new seeder file inside the database/seeders directory.

database/seeders/TransactionStatusSeeder.php

🧩 Understand the Seeder Structure

A basic seeder class looks like this:

use Illuminate\Database\Seeder;

class TransactionStatusSeeder extends Seeder
{
    public function run()
    {
        // Seeding logic goes here
    }
}

• Every seeder extends the Seeder class

• The run() method is executed when the seeder runs

• All database insert logic lives inside this method

🧪Add Data to the Seeder

Assume you have a table called transaction_statuses with columns:

• code

• label

• is_active

Now define the seeding logic:

use Illuminate\Database\Seeder;
use App\Models\TransactionStatus;

class TransactionStatusSeeder extends Seeder
{
    public function run()
    {
        $statuses = [
            ['code' => 'PENDING',   'label' => 'Pending',   'is_active' => true],
            ['code' => 'POSTED',    'label' => 'Posted',    'is_active' => true],
            ['code' => 'REVERSED',  'label' => 'Reversed',  'is_active' => true],
            ['code' => 'VOIDED',    'label' => 'Voided',    'is_active' => false],
        ];

        foreach ($statuses as $status) {
            TransactionStatus::updateOrCreate(
                ['code' => $status['code']],
                $status
            );
        }
    }
}

Why updateOrCreate()?

• Prevents duplicate records

• Allows controlled updates to labels or flags

• Safe to run in production

• Ideal for master data

This pattern is widely used in finance, insurance, and accounting systems.

✍️ Register the Seeder

class DatabaseSeeder extends Seeder
{
    public function run()
    {
        $this->call([
            TransactionStatusSeeder::class,
        ]);
    }
}

The DatabaseSeeder class is the central entry point for all database seeders in a Laravel application. Whenever you run a seeding command, Laravel starts execution from this class and then calls all registered seeders in the defined order.

Understanding DatabaseSeeder is essential because it controls what data gets seeded, when it gets seeded, and in which environment.

📁 Where Is DatabaseSeeder Located?

Laravel automatically creates this file at:

database/seeders/DatabaseSeeder.php

database/seeders/
 ├── DatabaseSeeder.php
 ├── TransactionStatusSeeder.php
 └── RoleSeeder.php

This file exists by default in every Laravel project and acts as the orchestrator for all other seeders.

📄 Basic Structure of DatabaseSeeder

use Illuminate\Database\Seeder;

class DatabaseSeeder extends Seeder
{
    public function run()
    {
        // Call individual seeders here
    }
}

Key Points

• DatabaseSeeder extends the base Seeder class

• The run() method is the starting point

• All child seeders are invoked from here

▶️ How DatabaseSeeder Works

When you run:

php artisan db:seed

Laravel performs the following steps:

1. Bootstraps the application

2. Loads DatabaseSeeder

3. Executes the run() method

4. Calls all registered seeders in sequence

5. Executes each seeder’s run() method

This makes DatabaseSeeder the single source of truth for seeding.

🔹Registering Seeders in DatabaseSeeder

To execute a seeder, it must be registered using the call() method.

class DatabaseSeeder extends Seeder
{
    public function run()
    {
        $this->call([
            RoleSeeder::class,
            PermissionSeeder::class,
            UserSeeder::class,
        ]);
    }
}

Why Order Matters

• Roles must exist before permissions are assigned

• Permissions must exist before user-role mapping

• Prevents foreign key constraint errors

🔹Calling Seeders Conditionally

You can control which seeders run based on the environment.

public function run()
{
    $this->call([
        RoleSeeder::class,
        PermissionSeeder::class,
    ]);

    if (app()->environment(['local', 'staging'])) {
        $this->call(UserSeeder::class);
    }
}

This ensures:

• Production stays clean

• Test users are not created in live systems

🗂️ Grouping Seeders for Better Organization

In large applications, it’s a good practice to group related seeders.

public function run()
{
    $this->call([
        MasterDataSeeder::class,
        AuthorizationSeeder::class,
        ConfigurationSeeder::class,
    ]);
}

Each group seeder can internally call smaller seeders.

class AuthorizationSeeder extends Seeder
{
    public function run()
    {
        $this->call([
            RoleSeeder::class,
            PermissionSeeder::class,
            RolePermissionSeeder::class,
        ]);
    }
}

This improves:

• Readability

• Maintainability

• Scalability

▶️ Running the Seeder Explicitly via Artisan

php artisan db:seed --class=TransactionStatusSeeder

Running DatabaseSeeder Explicitly

Although DatabaseSeeder runs by default, you can explicitly call it:

php artisan db:seed --class=DatabaseSeeder

This is useful in:

• CI/CD pipelines

• Controlled production deployments

• Multi-tenant seeding workflows

🗄️Database Seeders: A Game-Changer for Multi-Tenant Applications

In a multi-tenant architecture, a single application serves multiple tenants, but each tenant’s data must remain isolated.
This makes database seeding fundamentally different from a single-database application.

Laravel seeders play a critical role in initializing and maintaining consistent data across all tenants.

🔹 The Core Challenge in Multi-Tenant Seeding

In a normal Laravel app:

• One database

• One DatabaseSeeder

• Seed once → done

In a multi-tenant system:

• Multiple tenant databases or schemas

• Each tenant requires the same base data

• Seeding must happen per tenant, not globally

📌 Examples of tenant-specific data:

• Roles & permissions

• Default users

• Configuration settings

• Accounting rules

• Commission slabs

• Feature flags

The Tenancy for Laravel package, along with the Spatie package, helps manage tenant isolation and provides tenant-aware features for Laravel applications.

Tenant-aware Artisan Commands

• You can run migrations or seeders per tenant.

• Example:

php artisan tenants:migrate
php artisan tenants:seed --class=SomeSeeder

Without this, running php artisan db:seed would only affect the central database.

• The package automatically switches the database connection and context based on the current tenant.

• This makes queries “tenant-aware” without changing your code everywhere.

📝 Seed all tenants with default DatabaseSeeder:

php artisan tenants:seed

📝 Seed a specific tenant seeder:

php artisan tenants:seed --class=TransactionStatusSeeder

📝 Seed a specific tenant (if supported by package):

php artisan tenants:seed --tenant=1 --class=TransactionStatusSeeder

📝Best Practices for Laravel Seeders

✅ Keep seeders small and focused
✅ Use factories for large datasets
✅ Separate master data (roles, permissions)
✅ Use environment checks
❌ Never seed sensitive production data
❌ Avoid running destructive commands in production

⚠️Common Mistakes and Troubleshooting

Seeder not running?

• Ensure it is registered in DatabaseSeeder

Foreign key constraint errors?

• Disable foreign key checks temporarily

• Ensure correct seeding order

Duplicate records?

• Add existence checks before inserting

🌐Real-World Use Cases

• Creating default admin users

• Seeding roles and permissions

• Generating transactions for QA testing

• Preparing demo data for stakeholders

• Speeding up onboarding for new developers

🧵 Wrapping Up

Laravel Database Seeders are a powerful yet simple tool that can save hours of manual setup and ensure consistency across environments.

When used correctly—with factories, best practices, and environment awareness—seeders become an essential part of any professional Laravel project.

A well-designed seeding strategy is not just about dummy data—it’s about predictable, repeatable, and reliable development environments.

Every Laravel developer works with sensitive data.

Passwords.
API keys.
Bank accounts.
Personal identifiers.

Yet one mistake is shockingly common:

Treating encryption, hashing, and encoding as the same thing.

They’re not.

Using the wrong technique doesn’t just cause bugs — it can lead to security breaches, failed audits, compliance violations, and irreversible data loss.

In this guide, we’ll clearly break down:

• 🔍 What Encryption, Hashing, and Encoding really are

• 🧠 When you should use each one (and when you absolutely shouldn’t)

• 🛠️ Real Laravel examples you can copy-paste today

• 🚫 Costly mistakes even experienced developers make

This isn’t theory — it’s written for real Laravel applications: APIs, SaaS platforms, fintech products, and multi-tenant systems.

1️⃣ Encryption: Lock It, Unlock It (When You Must)

🔐 What Is Encryption?

Encryption transforms readable data (plaintext) into unreadable data (ciphertext) using a secret key.

👉 It is reversible — if (and only if) you have the correct key.

Think of encryption as a secure locker:

• You lock the data

• You unlock it only when truly necessary

✅ When Should You Use Encryption?

Use encryption only when the original value must be retrieved later.

✔ Bank account numbers
✔ API tokens & secrets
✔ OAuth credentials
✔ Personally Identifiable Information (PII)

🛠️ Laravel Encryption (Built-In & Battle-Tested)

Laravel ships with strong encryption using AES-256-CBC — no setup required.

Encrypting Data

use Illuminate\Support\Facades\Crypt;

$encrypted = Crypt::encryptString(’1234-5678-9012-3456’);

Decrypting Data

$decrypted = Crypt::decryptString($encrypted);

✔ Key-based
✔ Secure
✔ Fully reversible

🌍 Real-World Example: Storing Bank Details Securely

Schema::create(’client_bank_accounts’, function (Blueprint $table) {
    $table->id();
    $table->string(’account_holder_name’);
    $table->text(’account_number’); // encrypted
    $table->text(’ifsc_code’);       // encrypted
    $table->timestamps();
});

$bank->account_number = Crypt::encryptString($request->account_number);
$bank->ifsc_code = Crypt::encryptString($request->ifsc_code);
$bank->save();

🔒 Even if your database is leaked, the data remains useless without APP_KEY.

2️⃣ Hashing: Verify Without Ever Knowing

🔑 What Is Hashing?

Hashing converts data into a fixed-length string using a mathematical algorithm.

👉 It is irreversible — forever.

You don’t unlock hashed data.
You compare against it.

✅ When Should You Use Hashing?

Use hashing when you never need the original value again.

✔ Passwords
✔ PINs
✔ Security answers

🛠️ Laravel Hashing Example

Laravel uses bcrypt or Argon2, both industry-approved.

Hashing a Password

use Illuminate\Support\Facades\Hash;

$hashed = Hash::make(’my-secret-password’);

Verifying a Password

Hash::check(’my-secret-password’, $hashed); // true

✔ One-way
✔ Automatically salted
✔ Resistant to brute-force attacks

🚫 The Biggest Security Mistake: Encrypting Passwords

❌ Never do this:

Crypt::encryptString(’password123’);

Why this is dangerous:

• Anyone with APP_KEY can decrypt every password

• Violates OWASP standards

• Fails security audits instantly

✅ Passwords must always be hashed — never encrypted.

3️⃣ Encoding: Data Travel, Not Data Protection

🔄 What Is Encoding?

Encoding transforms data into another format so it can be safely transmitted or stored.

👉 It provides ZERO security.

Encoding is about compatibility, not protection.

✅ When Should You Use Encoding?

✔ Sending data over APIs
✔ URLs
✔ JSON responses
✔ File uploads

🛠️ Common Encoding Examples

Base64 Encoding

$encoded = base64_encode(’Hello World’);
$decoded = base64_decode($encoded);

JSON Encoding

$data = [’name’ => ‘John’, ‘role’ => ‘admin’];

$json  = json_encode($data);
$array = json_decode($json, true);

⚠️ Anyone can decode encoded data in seconds.

🔍 Encryption vs Hashing vs Encoding (At a Glance)

🚫 Costly Mistakes Developers Still Make

❌ Treating encoding as security
❌ Encrypting passwords
❌ Logging decrypted sensitive data
❌ Sharing APP_KEY across environments
❌ Skipping key rotation policies

✅ Laravel Security Best Practices

✔ Hash all passwords with Hash::make()
✔ Encrypt sensitive data with Crypt
✔ Protect your APP_KEY like production credentials
✔ Restrict access to decrypted data
✔ Rotate keys if compromised

🧠 Final Thoughts: Choose Wisely or Pay Later

These three concepts are not interchangeable — and confusing them is expensive.

• 🔐 Encryption → for data you must retrieve

• 🔑 Hashing → for secrets you must never see again

• 🔄 Encoding → for data movement, not protection

If you’re building fintech, healthcare, SaaS, or multi-tenant systems, this knowledge isn’t optional — it’s foundational.

Secure code is not about more tools.
It’s about using the right one.

Happy coding — and stay secure 🔐

This guide will help you understand:

• What encryption is

• How Laravel handles encryption

• When you should use it

• Best practices every developer must follow

• Real-world use cases to apply in your projects

Let’s dive in! 🧠

🧩 1. What Is Encryption?

Encryption is the process of converting readable data (plaintext) into unreadable data (ciphertext) using a key.
Only someone with the correct key can decrypt the data.

Why We Need Encryption?

• To protect sensitive data

• To comply with security standards

• To secure database-stored information

• To prevent identity theft, fraud, or data leaks

Laravel’s Encryption

Laravel uses OpenSSL and the industry-standard AES-256-CBC or AES-128-CBC encryption.

It is:

• Secure

• Fast

• Easy to use

• Opinionated (removes complexity)

⚙️ 2. How Laravel Encryption Works

Laravel uses a secret key stored in .env → APP_KEY.

APP_KEY=base64:JQ1XC77tVRa1Tt56Zl................

This key is used to encrypt/decrypt values.

✔️ Encrypting Data

use Illuminate\Support\Facades\Crypt;

$encrypted = Crypt::encryptString(’Hello Pritesh’);

✔️ Decrypting Data

use Illuminate\Support\Facades\Crypt;

$decrypted = Crypt::decryptString($encrypted);

🕒 3. When Should You Use Encryption?

You should NOT encrypt everything.

Use encryption when storing or transmitting highly sensitive information such as:

✔️ Personally identifiable information (PII)

• Aadhaar / SSN

• Phone numbers

• Government IDs

• Passport numbers

✔️ Financial data

• Bank account details

• Credit card numbers

• Transaction tokens

✔️ Authentication-related data

• API keys

• Access tokens

• Refresh tokens

• OAuth secrets

✔️ Business confidential data

• Internal notes

• Private documents

• Signed agreements

❌ When NOT to Use Encryption

• Fields used for search or filtering (LIKE, WHERE)

• Sorting fields

• Non-sensitive fields

Because encrypted data is unreadable, database-level queries become impossible.

⭐ 4. Best Practices for Using Encryption in Laravel

✅ 1. Always protect your APP_KEY

Never share your .env file
Never commit it to GitHub
Rotate keys during breaches
Use server-level secrets management (AWS/GCP/Vault)

✅ 2. Use model encryption casts

Cleaner, automatically applied, and standardized.

protected $casts = [
   ‘pan_number’ => ‘encrypted’,
];

✅ 3. Encrypt only what is necessary

Avoid performance overhead and indexing problems.

✅ 4. Store hash values for searchable encrypted fields

Example: store hashed email for lookup.

email_encrypted
email_hash (for searching)

✅ 5. Use Queue Encryption for Queued Jobs

Never put raw sensitive data in queues.

$job->data = Crypt::encrypt($sensitive);

✅ 6. Secure backups

Encrypted data must remain encrypted even in backups.

✅ 7. Don’t log sensitive information

Disable logging for encrypted sensitive data.

🏦 Real-World Scenario: Storing Client Bank Details (EFT)

Imagine you’re building an insurance or loan management system where clients can set up their bank account for EFT payouts.

You want to store:

• Account holder name

• Bank name

• Account number (Sensitive 🚨)

• Routing number (Sensitive 🚨)

• Bank identifiers (IFSC / SWIFT / Branch code)

This must be safe.

Let’s build it the secure way.

🧩 Step 1: Create the Migration

Here’s the migration you’ll use:

Schema::create(’client_bank_details’, function (Blueprint $table) {
    $table->id();
    $table->unsignedBigInteger(’client_id’);

    $table->string(’account_holder_name’);
    $table->string(’bank_name’);

    // Sensitive fields - stored encrypted
    $table->text(’account_number’);
    $table->text(’routing_number’);

    $table->enum(’account_type’, [’checking’, ‘savings’, ‘business’]);
    $table->boolean(’is_primary’)->default(false);
    $table->boolean(’is_verified’)->default(false);
    $table->enum(’status’, [’active’, ‘inactive’])->default(’active’);

    $table->string(’branch_code’)->nullable();
    $table->string(’swift_code’)->nullable();
    $table->string(’country’)->nullable();
    $table->string(’currency’)->nullable();

    $table->json(’metadata’)->nullable();

    $table->timestamps();
});

🛡️ Step 2: Apply Laravel Encryption Using Model Casts

This is the secret sauce.

Laravel provides a beautiful, painless way to automatically encrypt/decrypt model attributes.

Just add:

protected $casts = [
    ‘account_number’ => ‘encrypted’,
    ‘routing_number’ => ‘encrypted’,
];

Your model becomes:

class ClientBankDetail extends Model
{
    protected $fillable = [
        ‘client_id’,
        ‘account_holder_name’,
        ‘bank_name’,
        ‘account_number’,
        ‘routing_number’,
        ‘account_type’,
        ‘is_primary’,
        ‘is_verified’,
        ‘status’,
        ‘branch_code’,
        ‘swift_code’,
        ‘country’,
        ‘currency’,
        ‘metadata’,
    ];

    protected $casts = [
        ‘account_number’ => ‘encrypted’,
        ‘routing_number’ => ‘encrypted’,
        ‘metadata’ => ‘array’,
        ‘is_primary’ => ‘boolean’,
        ‘is_verified’ => ‘boolean’,
    ];
}

🚀 Step 3: Storing Encrypted Bank Information

ClientBankDetail::create([
    ‘client_id’ => 101,
    ‘account_holder_name’ => ‘John Doe’,
    ‘bank_name’ => ‘Wells Fargo’,
    ‘account_number’ => ‘9876543210’,
    ‘routing_number’ => ‘021000021’,
    ‘account_type’ => ‘checking’,
    ‘country’ => ‘USA’,
    ‘currency’ => ‘USD’
]);

Laravel will:

• Encrypt the data before storing it

• Decrypt it when you retrieve it

• Protect it using application key (APP_KEY)

All automatically.

🔍 Step 4: Reading Decrypted Values

$bank = ClientBankDetail::find(1);
echo $bank->account_number;

You get a clean value like:

9876543210

But if you open the database, you see unreadable encrypted content — exactly what we want.

📜 Compliance & Legal Benefits

Encryption helps meet:

• PCI-DSS

• GDPR

• SOC 2

Encryption ≠ compliance
But compliance is impossible without encryption.

📌 Conclusion

Laravel makes encryption incredibly simple without compromising security.

If you’re dealing with sensitive data, encryption is non-negotiable.

This blog covered:

✔️ What encryption is

✔️ How Laravel handles it

✔️ When to use it

✔️ Best practices

✔️ Real-world examples

✔️ Practical code snippets

This is where Database Migrations become a game-changer.

Laravel provides one of the most elegant migration systems in the industry, turning database changes into version-controlled, repeatable, trackable code.

In this article, you’ll learn:

• What a database migration is

• How migrations work in Laravel

• Advantages & disadvantages

• Best practices (with real examples)

• Why migrations are essential for long-term project health

📌 What Is a Database Migration?

A Database Migration is simply a version control system for your database schema.

Just like Git tracks code changes, migrations track database structure changes such as:

• Creating tables

• Adding or removing columns

• Adding indexes or foreign keys

• Changing data types

• Renaming tables

Each migration is a small PHP file that modifies the database in a controlled and reversible way.

📁 What Does a Migration File Look Like?

When you run:

php artisan make:migration create_users_table

Laravel generates a file like this:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create(’users’, function (Blueprint $table) {
            $table->id();
            $table->string(’name’);
            $table->string(’email’)->unique();
            $table->string(’password’);
            $table->boolean(’is_active’)->default(true);
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists(’users’);
    }
};

🟦 up()

Describes what to do — create/modify tables.

🟥 down()

Describes how to roll back the changes.

Simple. Clean. Powerful.

⚙️ How Do Migrations Work in Laravel?

Laravel stores the history of executed migrations in a special table called migrations.

When you run:

php artisan migrate

Laravel:

1. Reads all migration files

2. Checks which ones are not executed yet

3. Runs them in order

4. Records them in the migrations table

When you run:

php artisan migrate:rollback

Laravel executes the down() method of recent migrations.

This makes migrations safe, reversible, and manageable across environments like:

• local

• staging

• production

Create Migration with Table:

You can create a new migration by defining the table name.

php artisan make:migration add_columns_to_orders_table --table=orders

✅ Generated Migration File

File Name (Laravel will create something like)

2025_11_23_000000_add_columns_to_orders_table.php
(The timestamp will match the moment you run the command.)

Full Migration File Content

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::table(’orders’, function (Blueprint $table) {
            //
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::table(’orders’, function (Blueprint $table) {
            //
        });
    }
};

📝 What this means

• Laravel will NOT guess which columns you want to add.

• It simply creates an empty Schema::table(’orders’) migration.

• You need to fill in the columns manually.

Example (you will add this yourself):

$table->string(’status’)->default(’pending’);
$table->date(’delivery_date’)->nullable();

✅ Advantages of Using Migrations

1. Version Control for Your Database

Every schema change is stored as code.
No more “Did you update your DB?” chaos.

2. Team Collaboration Becomes Easy

Developers simply pull the latest code and run:

php artisan migrate

Boom — database synced.

3. Automated Deployment

CI/CD pipelines can apply migrations automatically.

4. Rollback Support

Accidentally deployed a breaking change?
Rollback with one command.

5. No More Manual SQL

You define schema changes in PHP, not raw SQL.

6. Infrastructure Consistency

Same database structure across all environments.

❌ Disadvantages (Yes, They Exist)

1. Bad Migrations Can Break Production

If not tested properly, migrations can cause downtime.

2. Large Tables Can Lock During Alter Operations

Adding indexes or columns to big tables may cause slowdowns.

3. Migrations Require Discipline

Everyone in the team needs to follow the migration workflow.

4. Rollback May Fail for Complex Logic

Some operations (like data migrations) aren’t perfectly reversible.

.🧠 Best Practices for Laravel Migrations

✔️ 1. Never Edit a Migration That Has Already Been Run

Wrong ❌
Editing old migrations breaks other developers.

Right ✔️
Create a new migration:

php artisan make:migration add_status_to_users_table

✔️ 2. Use Meaningful Migration Names

Good:

2025_11_20_101010_add_status_column_to_users_table.php

Bad:

xyz_migration.php

✔️ 3. Keep Migrations Small and Focused

One responsibility per migration.

✔️ 4. Always Provide a Rollback Method

A down() method should undo changes cleanly.

✔️ 5. Use Database Indexes Wisely

Example:

$table->index(’email’);

They improve performance significantly.

✔️ 6. Use php artisan migrate:fresh Only in Local Development

Never run it on staging/production — it will drop all tables.

✔️ 7. Run Migrations in Transactions (If Supported)

Laravel can wrap migrations in a transaction:

public $withinTransaction = true;

This keeps migrations atomic.

🎯 Benefits of Using Migrations in Real Projects

• Faster onboarding of new developers

• Zero manual DB setup

• Consistent schema across all servers

• Easy recovery in case of issues

• Better CI/CD automation

• Database and code stay in sync

• Change history is preserved forever

🔥 Conclusion

Database migrations are one of the most powerful features in Laravel. They turn database management into a predictable, trackable, and reversible process.

Whether you’re working solo or on a large team, migrations help ensure your application remains stable, scalable, and easier to maintain.

If you’re still editing databases manually — it’s time to level up.
Let your database evolve with confidence using Laravel migrations. 🚀

🔍What Is the N+1 Problem?

Imagine you have a list of blog posts, and each post has multiple comments. This is a classic one-to-many relationship because one post can have many comments.

Now, let’s say you need to fetch all posts along with their comments.
If your application isn’t optimized, it might do something like this:

1. First, fetch all posts:

$posts = Post::all();

2. Then, for each post, fetch its comments one by one:

foreach ($posts as $post) {
    // Query for each post: SELECT * FROM comments WHERE post_id = ?
    $comments = Comment::where(’post_id’, $post->id)->get();
}

If you have 100 posts, this results in 101 queries
(1 query for posts + 100 queries for comments).

That’s why it’s called the N+1 problem —
you run N queries (one for each post) + 1 main query.

⚠️Why Is This a Problem?

The N+1 problem can seriously slow down your application for several reasons:

• Too many database queries overload your database server.
  Fetching each post’s comments separately forces the database to run the same query again and again.

• Increased network traffic between your Laravel app and the database.
  Instead of sending 2 queries (posts + all comments), your app may send 101 queries or more.

• Slower response times because the application waits for multiple comment queries to finish.
  Each post triggers its own query, adding delay for every request.

• Performance gets worse as the dataset grows.
  For example, if you have 1,000 posts, Laravel may execute 1,001 queries
  (1 for posts + 1 for each post’s comments).

In short, the more posts you have, the slower your page becomes.

🧭How to Fix the N+1 Problem

1. Use Joins to Fetch Data in One Query

Instead of making a separate query for each post’s comments, you can fetch everything in a single database query using a JOIN.

SELECT posts.*, comments.*
FROM posts
LEFT JOIN comments ON posts.id = comments.post_id;

This way, you avoid running 101 queries (1 for posts + 100 for comments).
Everything is retrieved in one efficient request.

Laravel Query Builder Equivalent:

$posts = DB::table(’posts’)
    ->leftJoin(’comments’, ‘posts.id’, ‘=’, ‘comments.post_id’)
    ->select(’posts.*’, ‘comments.*’)
    ->get();

2. Batch Queries Instead of Fetching One by One

If you prefer not to use a JOIN, another solution is batch querying—fetching all comments for multiple posts in one call.

SQL Example:

SELECT * FROM comments WHERE post_id IN (1, 2, 3, 4, 5);

This allows you to:

• First fetch all posts

• Then fetch all comments for those posts in a single batch query

Instead of 100 separate queries, you now perform:

• 1 query → posts

• 1 query → all their comments

Total = 2 queries instead of 101.

Laravel Eloquent Equivalent:

$posts = Post::all(); // Query 1

$comments = Comment::whereIn(’post_id’, $posts->pluck(’id’))->get(); // Query 2

✅ The Laravel fix: Eager loading (with())

Laravel’s built-in solution is to eager-load relations before looping:

// Controller (fixed)
$posts = Post::with(’comments’)->get(); // Query #1 (posts) + Query #2 (comments for all posts)

// Now in the view, no extra queries:
@foreach($posts as $post)
  @foreach($post->comments as $comment)
    {{ $comment->body }}
  @endforeach
@endforeach

Result: 2 queries total no matter how many posts.

🔎 Detect N+1 in Laravel

• Laravel Debugbar (dev): shows each query and count.

• Laravel Telescope: records queries for requests.

• DB::listen(): log queries in tests or a temporary debug route.

• Add assertions in tests to monitor query count (use sparingly).

Quick example using DB::listen:

DB::listen(function ($query) {
    logger($query->sql, $query->bindings);
});

🛠 Handling large datasets

Eager-loading everything for massive datasets can blow memory. Use chunking or cursors:

Post::chunkById(100, function ($posts) {
    $posts->load(’comments’); // eager-load per chunk
    foreach ($posts as $post) {
        // process
    }
});

cursor() streams models but you can only eager-load per batch (collect ids, then load in batches).

👀 Common gotchas & pitfalls

If you select() custom columns on a relation, include the foreign key so Eloquent can map relations:

$posts = Post::with([’comments’ => function ($q) {
    $q->select(’id’, ‘post_id’, ‘body’, ‘created_at’);
}])->select(’id’, ‘title’)->get();

• limit() inside eager load is not the same as “limit per parent” in every DB. Use latestOfMany() or subquery patterns for latest-N-per-parent.

• Polymorphic relations require careful eager-loading; Laravel groups by type and runs efficient queries, but always test.

• Over-eager-loading deep relations (with(’a.b.c.d’)) can increase memory and do too much work — load only what’s required.

✅ Best practices checklist (senior devs use this)

Before merging a PR, ask:

• Am I accessing a relation inside a loop? If yes, ensure that relation is eager-loaded.

• Do I only need aggregates (count, sum)? Use withCount(), withSum().

• Am I selecting only the columns needed for the view/API? (Use select()).

• Is this endpoint high-traffic? Consider caching or denormalized read models.

• For large datasets, did I use chunking or streaming?

• Did I profile queries with Debugbar or Telescope?

• Are there joins/subqueries that could replace heavy eager-loading?

🏁 Final thoughts

The N+1 problem is simple to understand and easy to fix once you know where to look. In Laravel, with(), withCount(), constrained eager loading, and smart use of joins/subqueries give you a powerful toolbox to fetch data efficiently.

If you:

• identify relations used in views,

• eager-load what’s required,

• prefer aggregates when possible,

• and profile query counts regularly,

you’ll keep your app fast and scalable as data grows.

Every modern web application from eCommerce platforms to financial systems relies on data integrity.
When users transfer money, create orders, or update profiles, they expect one thing: the data should be accurate, consistent, and safe, no matter what happens in the backend.

This is where ACID properties come in.

In relational databases like MySQL, ACID ensures that each database transaction behaves predictably, even in the face of power failures, concurrency issues, or application crashes.

Laravel, with its expressive Eloquent ORM and database abstractions, gives developers easy access to these principles without needing to write low-level SQL.

⚙️ What Does ACID Stand For?

ACID is an acronym for four key properties that define reliable database transactions:

A — Atomicity A transaction is all or nothing. Either all operations succeed, or none do.

C — Consistency The database must remain in a valid state before and after a transaction.

I — Isolation Concurrent transactions should not interfere with each other. D — Durability Once committed, data remains safe even after failures.

Let’s explore each property in detail with Laravel and MySQL examples.

🔹 1. Atomicity — All or Nothing

Atomicity ensures that either all steps of a transaction succeed or none do.

💬 Example: Transferring Money Between Accounts

Imagine a banking system where we transfer ₹100 from Account A to Account B.
We must decrease the balance of A and increase the balance of B in a single atomic transaction.

If the system crashes after debiting A but before crediting B — the transaction must roll back.

✅ Laravel Example

use Illuminate\Support\Facades\DB;

try {
    DB::beginTransaction();

    // Debit from Account A
    DB::table(’accounts’)->where(’id’, 1)->decrement(’balance’, 100);

    // Credit to Account B
    DB::table(’accounts’)->where(’id’, 2)->increment(’balance’, 100);

    DB::commit();
} catch (\Exception $e) {
    DB::rollBack();
    Log::error(’Transaction failed: ‘ . $e->getMessage());
}

Or more elegantly:

DB::transaction(function () {
    DB::table(’accounts’)->where(’id’, 1)->decrement(’balance’, 100);
    DB::table(’accounts’)->where(’id’, 2)->increment(’balance’, 100);
});

💡 Best Practice:
Use DB::transaction() whenever you perform multiple related writes that must succeed or fail together.

🔹 2. Consistency — Maintaining Data Integrity

Consistency ensures that the database transitions from one valid state to another.

This is often maintained using constraints, foreign keys, validation, and business logic.

💬 Example: Creating an Order and Order Items

If you create an order but fail to insert the related order items, your database becomes inconsistent.

✅ Laravel Example

DB::transaction(function () {
    $order = Order::create([
        ‘user_id’ => 1,
        ‘total’ => 500,
    ]);

    OrderItem::create([
        ‘order_id’ => $order->id,
        ‘product_id’ => 42,
        ‘quantity’ => 2,
        ‘price’ => 250,
    ]);
});

💡 Database-Level Consistency

At the schema level, we ensure consistency with foreign key constraints and unique indexes:

Schema::create(’order_items’, function (Blueprint $table) {
    $table->id();
    $table->foreignId(’order_id’)->constrained()->onDelete(’cascade’);
    $table->foreignId(’product_id’)->constrained();
    $table->integer(’quantity’);
    $table->decimal(’price’, 10, 2);
});

If someone tries to insert an order item with an invalid order_id, MySQL will reject it maintaining consistency.

🔹 3. Isolation — Safe Concurrent Transactions

Isolation means that concurrent transactions don’t affect each other’s results.

MySQL supports multiple isolation levels:

READ UNCOMMITTED Can read uncommitted data (dirty reads).

READ COMMITTED Reads only committed data.

REPEATABLE READ (default in MySQL) Same result for repeated reads within a transaction.

SERIALIZABLE Highest isolation; transactions run one after another.

💬 Example: Preventing Double Spending

Two users try to withdraw from the same account simultaneously.
Isolation ensures that one transaction waits until the other completes.

✅ Laravel Example

DB::transaction(function () {
    $account = DB::table(’accounts’)
        ->where(’id’, 1)
        ->lockForUpdate()
        ->first();

    if ($account->balance >= 100) {
        DB::table(’accounts’)->where(’id’, 1)->decrement(’balance’, 100);
    } else {
        throw new \Exception(’Insufficient balance.’);
    }
});

lockForUpdate() prevents other transactions from reading or updating the same row until this one finishes ensuring isolation.

🔹 4. Durability — Data That Stays

Durability ensures that once a transaction is committed, it will remain saved even if a power failure or crash occurs.

In MySQL’s InnoDB engine, durability is maintained using:

• Redo logs (write-ahead logs)

• Automatic crash recovery

• fsync() writes to disk after commit

💬 Laravel’s Role

Laravel delegates durability to MySQL — but you can ensure safer commits by:

• Using DB::transaction() to avoid half-committed writes

• Configuring InnoDB as the storage engine

• Setting proper innodb_flush_log_at_trx_commit (default 1 ensures maximum durability)

🧩 Putting It All Together: A Real-World Scenario

Scenario: Order Creation with Payment Logging

DB::transaction(function () use ($request) {
    $order = Order::create([
        ‘user_id’ => $request->user_id,
        ‘total’ => $request->total,
    ]);

    foreach ($request->items as $item) {
        OrderItem::create([
            ‘order_id’ => $order->id,
            ‘product_id’ => $item[’product_id’],
            ‘quantity’ => $item[’qty’],
            ‘price’ => $item[’price’],
        ]);
    }

    Payment::create([
        ‘order_id’ => $order->id,
        ‘amount’ => $order->total,
        ‘status’ => ‘SUCCESS’,
    ]);
});

If any insert fails, Laravel automatically rolls back ensuring Atomicity, Consistency, and Durability.
MySQL’s transaction isolation ensures that other users see consistent data while this operation is in progress.

🧭 Best Practices for Handling Transactions in Laravel

1. ✅ Use DB::transaction() for multi-step operations.

2. 🔁 Handle Exceptions Gracefully - rollback on failure and log errors.

3. 🧱 Leverage Database Constraints (foreign keys, unique keys).

4. ⚙️ Tune Isolation Levels - use REPEATABLE READ for safety, or READ COMMITTED for performance.

5. 🧩 Keep Transactions Short - long-running transactions can cause locks and deadlocks.

6. 💾 Always Use InnoDB - for full ACID compliance.

🧾 Summary & Key Takeaways

• Atomicity ensures operations succeed together.

• Consistency keeps your data valid and rules enforced.

• Isolation prevents race conditions in concurrent access.

• Durability guarantees data safety after commits.

When combined, these principles make your Laravel + MySQL applications reliable, predictable, and production-safe.

Building with ACID in mind means your users can trust your app - every time they hit “Submit”.

In this post, we’ll explore:

• What each of them is

• How they differ

• Practical SQL examples

• When to use which one

🔹 1. What is a Subquery?

A subquery (or nested query) is a query inside another query.
It can appear in the SELECT, FROM, or WHERE clause and is used when you need to use the result of one query inside another.

🧩 Example:

Let’s say you want to fetch all employees who work in the IT department.

SELECT first_name, last_name
FROM employees
WHERE department_id = (
    SELECT department_id
    FROM departments
    WHERE department_name = ‘IT’
);

Here, the inner query:

SELECT department_id FROM departments WHERE department_name = ‘IT’;

runs first, and its result is used by the outer query.

✅ When to Use:

• For simple filtering or lookups.

• When you need the result only once.

⚠️ Be Careful:

• Can become slow if used inside loops or complex joins.

• Not ideal for reusing results.

🔹 2. What is a CTE (Common Table Expression)?

A CTE is a temporary named result set that exists only during the execution of a single SQL statement.
Think of it as a named subquery that improves readability and maintainability.

It starts with the WITH keyword.

🧩 Example:

WITH IT_Employees AS (
    SELECT employee_id, first_name, last_name, department_id
    FROM employees
    WHERE department_id = (
        SELECT department_id FROM departments WHERE department_name = ‘IT’
    )
)
SELECT first_name, last_name
FROM IT_Employees
WHERE last_name LIKE ‘S%’;

Here, the CTE IT_Employees holds the intermediate result which we later query again.

✅ Benefits:

• Readable and modular — perfect for long, multi-step queries.

• Can be recursive, great for hierarchical data (like org charts).

⚠️ Limitations:

• Exists only within that query.

• Cannot be indexed or reused across multiple queries.

🔹 3. What is a Temporary Table?

A Temporary Table is like a normal table, but it’s stored temporarily in your database (e.g., in tempdb in SQL Server).
You can create, index, update, and reuse it across multiple queries within the same session.

🧩 Example:

CREATE TEMPORARY TABLE temp_it_employees AS
SELECT employee_id, first_name, last_name, department_id
FROM employees
WHERE department_id = (
    SELECT department_id FROM departments WHERE department_name = ‘IT’
);

SELECT * FROM temp_it_employees WHERE last_name LIKE ‘S%’;

You can even index it for faster performance:

CREATE INDEX idx_lastname ON temp_it_employees(last_name);

✅ Benefits:

• Can be reused multiple times.

• Supports indexing — improves performance on large datasets.

• Ideal for complex transformations or multi-step logic.

⚠️ Limitations:

• Needs manual creation and cleanup.

• Slight overhead for disk/memory usage.

🔸 4. Comparison Summary

🧠 5. Real-World Analogy

🔹 6. Practical Performance Example

Let’s consider a real-world scenario:

You need to find all employees who worked more than 200 hours in the past 3 months and belong to departments with average salary > 80,000.

You can do it in three ways:

🔸 Subquery:

SELECT e.employee_id, e.first_name, e.last_name
FROM employees e
WHERE e.department_id IN (
    SELECT department_id FROM departments WHERE avg_salary > 80000
)
AND e.employee_id IN (
    SELECT employee_id FROM work_hours
    WHERE total_hours > 200
);

🔸 CTE:

WITH HighSalaryDepartments AS (
    SELECT department_id FROM departments WHERE avg_salary > 80000
),
ActiveEmployees AS (
    SELECT employee_id FROM work_hours WHERE total_hours > 200
)
SELECT e.employee_id, e.first_name, e.last_name
FROM employees e
JOIN HighSalaryDepartments d ON e.department_id = d.department_id
JOIN ActiveEmployees a ON e.employee_id = a.employee_id;

🔸 Temporary Table:

CREATE TEMPORARY TABLE high_salary_departments AS
SELECT department_id FROM departments WHERE avg_salary > 80000;

CREATE TEMPORARY TABLE active_employees AS
SELECT employee_id FROM work_hours WHERE total_hours > 200;

SELECT e.employee_id, e.first_name, e.last_name
FROM employees e
JOIN high_salary_departments d ON e.department_id = d.department_id
JOIN active_employees a ON e.employee_id = a.employee_id;

👉 In this example:

• Subquery works fine for small datasets.

• CTE is cleaner and easier to maintain.

• Temporary Table gives the best performance for large datasets or repeated queries.

🔹 7. Best Practices

✅ Use Subqueries for quick and simple conditions.
✅ Use CTEs for readable, modular logic and recursive problems.
✅ Use Temporary Tables for large or reusable intermediate data sets.
✅ Always test performance with EXPLAIN or query plans.
✅ Clean up temporary tables if not automatically dropped.

💡 Final Thoughts

Choosing between a Subquery, CTE, and Temporary Table depends on what you value most — readability, performance, or reusability.

Remember — clean SQL is not just about running faster, but also about being maintainable.
Start small, measure performance, and evolve your query structure as your data grows.

Although they look similar, they behave differently under the hood and have performance implications that every developer should understand.

⚙️ What is UNION?

The UNION operator combines the results of two or more SELECT statements and removes duplicate rows from the final result set.

✅ Syntax:

SELECT column_list FROM table1
UNION
SELECT column_list FROM table2;

🔍 Example:

Let’s say we have two tables — employees_2024 and employees_2025.

Now, if we run:

SELECT name FROM employees_2024
UNION
SELECT name FROM employees_2025;

🧾 Output:

➡️ Notice how “Alice” appears only once — duplicates are removed automatically.

⚡ What is UNION ALL?

The UNION ALL operator also combines the results of multiple SELECT statements —
but it does not remove duplicates.

✅ Syntax:

SELECT column_list FROM table1
UNION ALL
SELECT column_list FROM table2;

🔍 Example:

Using the same tables:

SELECT name FROM employees_2024
UNION ALL
SELECT name FROM employees_2025;

🧾 Output:

➡️ Here, “Alice” appears twice — once from each table.

⚖️ Key Differences Between UNION and UNION ALL

🚀 Performance Example

Let’s run a quick comparison with a large dataset.

-- UNION
SELECT name FROM sales_2023
UNION
SELECT name FROM sales_2024;

-- UNION ALL
SELECT name FROM sales_2023
UNION ALL
SELECT name FROM sales_2024;

⚙️ Behind the scenes:

• UNION performs an implicit DISTINCT operation — MySQL creates a temporary table, sorts results, and removes duplicates.

• UNION ALL simply concatenates results, making it much faster for large data sets.

Rule of thumb:
If you don’t need to eliminate duplicates → always prefer UNION ALL for better performance.

🌍 Real-World Examples

🏢 Example 1: Combining Customer Lists from Multiple Branches

Let’s say you have separate databases or tables for different store branches:

• customers_mumbai

• customers_delhi

Each table stores customer names. Some customers shop in both branches.

✅ Using UNION (to get unique customers)

SELECT customer_name FROM customers_mumbai
UNION
SELECT customer_name FROM customers_delhi;

Output:

➡️ This gives you a unique list of customers across both branches — useful for CRM or marketing campaigns where duplicates are not needed.

⚡ Using UNION ALL (to track total visits)

SELECT customer_name FROM customers_mumbai
UNION ALL
SELECT customer_name FROM customers_delhi;

Output:

➡️ This shows each occurrence, meaning Priya visited both branches — helpful when you want to count total visits or analyze activity.

💡 When to Use Which?

✅ Use UNION When:

• You need unique results only.
  Example: Combining customer lists from multiple regions.

✅ Use UNION ALL When:

• You’re sure data won’t overlap or duplicates are acceptable.
  Example: Merging monthly logs or combining partitions.

⚠️ Common Mistakes to Avoid

1. Mismatched columns:
   Each SELECT must return the same number of columns with compatible data types.

-- ❌ This will fail
SELECT id, name FROM table1
UNION
SELECT name FROM table2;

2. Expecting automatic sorting:
   The result of UNION or UNION ALL is not guaranteed to be ordered.
   Use ORDER BY after the last query:

SELECT name FROM table1
UNION ALL
SELECT name FROM table2
ORDER BY name;

🧠 Pro Tip

If you need to count duplicates or analyze overlaps, you can simulate both behaviors:

SELECT name, COUNT(*) AS occurrence
FROM (
  SELECT name FROM employees_2024
  UNION ALL
  SELECT name FROM employees_2025
) AS combined
GROUP BY name;

This helps detect duplicates even when using UNION ALL.

🏁 Conclusion

Both UNION and UNION ALL are powerful tools in MySQL for combining data from multiple queries — but understanding their differences is essential for writing efficient SQL.

• UNION gives you a clean, unique result set by removing duplicates — ideal for cases where you care about distinct data (like unique customers, leads, or products).

• UNION ALL, on the other hand, is faster and lighter because it doesn’t check for duplicates — making it perfect for analytics, reporting, and log data where every record matters.

In short:

Think of it this way —

Use UNION for accuracy, and UNION ALL for speed.

The best SQL developers know when to choose between the two, balancing data correctness and query performance based on the context.

So next time you merge data across tables, pause for a second and ask yourself —
Do I really need to remove duplicates?
If not, give UNION ALL the green light. 🚦