Fast forward eighteen months. That same Order Eloquent model is now a 1,400-line monolith. Nestled between event listeners, accessor mutations, and custom attribute cast methods sit dozens of local query scopes: scopeWhereActive(), scopeWhereEligibleForDiscount(), scopePendingExport(), scopeWithRecentTransactions().

We call this Query Scope Bloat. On paper, query scopes are advertised as the standard Laravel way to encapsulate reusable query logic. In practice, when applied indiscriminately to complex domain models, they turn your database interactions into an unmaintainable, tightly coupled mess.

In this post, we’re going to walk through why query scopes break down at scale and how to refactor them into crisp, single-purpose Query Objects (and where traditional Repositories fit into the picture).

Last article in this category: https://codecraftdiary.com/2026/07/31/laravel-models-business-logic-hidden-workflows/

The Fallacy of the “Convenient” Model Scope

Let’s look at how query scope bloat sneaks into a codebase. Imagine an e-commerce platform where marketing wants to identify high-value B2B customers who haven’t placed an order in the last 90 days but have active subscriptions.

The path of least resistance is usually adding a scope directly to the Customer model:

// App\Models\Customer.php

class Customer extends Model
{
    public function scopeDormantHighValueB2b($query, int $daysThreshold = 90)
    {
        return $query->where('type', 'b2b')
            ->whereHas('subscriptions', function ($q) {
                $q->where('status', 'active');
            })
            ->whereDoesntHave('orders', function ($q) use ($daysThreshold) {
                $q->where('created_at', '>=', now()->subDays($daysThreshold));
            })
            ->having('total_lifetime_spend', '>', 10000);
    }
}

// App\Models\Customer.php

class Customer extends Model
{
    public function scopeDormantHighValueB2b($query, int $daysThreshold = 90)
    {
        return $query->where('type', 'b2b')
            ->whereHas('subscriptions', function ($q) {
                $q->where('status', 'active');
            })
            ->whereDoesntHave('orders', function ($q) use ($daysThreshold) {
                $q->where('created_at', '>=', now()->subDays($daysThreshold));
            })
            ->having('total_lifetime_spend', '>', 10000);
    }
}

It works. It’s expressive enough in the controller: Customer::dormantHighValueB2b()->get(). But consider the structural consequences over time:

1. Violation of Single Responsibility Principle (SRP): The Customer model is now responsible for database mapping, attribute casting, relationship definitions, business rules, AND specific reporting analytics filters.
2. Unintended Side Effects & Hidden Joins: Scopes often chain sub-queries or eager loads. When a developer chains three different scopes together in a controller, they frequently create accidental N+1 query patterns or conflicting WHERE clauses that silently override each other.
3. Zero Encapsulation for Complex Returns: Scopes return an Illuminate\Database\Eloquent\Builder instance. This means any caller can keep chaining arbitrary SQL onto the end of your query, leaking implementation details across controller actions or job handlers.
4. Test Rigidity: To test this single query rule, you must instantiate the entire Eloquent model, set up database state for related subscriptions and orders, and run full integration tests every single time.

Enter Query Objects

Before jumping straight to a heavy Repository pattern interface with 20 methods, there is a much cleaner, more idiomatic solution for complex read queries: Query Objects.

A Query Object is a dedicated, invokable class whose sole job is to construct and execute a single database query. It isolates query construction from your domain models and controllers, making your database layer modular and trivially testable.

Step 1: Extracting the Query to a Dedicated Object

Let’s refactor our dormant B2B customer query into an invokable Query Object:

namespace App\Queries;

use App\Models\Customer;
use Illuminate\Contracts\Pagination\LengthAwarePaginator;
use Illuminate\Database\Eloquent\Builder;

final class GetDormantHighValueB2bCustomersQuery
{
    public function __construct(
        private readonly int $daysThreshold = 90,
        private readonly int $minimumSpend = 10000
    ) {}

    public function handle(int $perPage = 25): LengthAwarePaginator
    {
        return $this->getBaseQuery()
            ->paginate($perPage);
    }

    public function getBaseQuery(): Builder
    {
        return Customer::query()
            ->where('type', 'b2b')
            ->whereHas('subscriptions', fn (Builder $q) => $q->where('status', 'active'))
            ->whereDoesntHave('orders', fn (Builder $q) => 
                $q->where('created_at', '>=', now()->subDays($this->daysThreshold))
            )
            ->where('total_lifetime_spend', '>=', $this->minimumSpend);
    }
}

namespace App\Queries;

use App\Models\Customer;
use Illuminate\Contracts\Pagination\LengthAwarePaginator;
use Illuminate\Database\Eloquent\Builder;

final class GetDormantHighValueB2bCustomersQuery
{
    public function __construct(
        private readonly int $daysThreshold = 90,
        private readonly int $minimumSpend = 10000
    ) {}

    public function handle(int $perPage = 25): LengthAwarePaginator
    {
        return $this->getBaseQuery()
            ->paginate($perPage);
    }

    public function getBaseQuery(): Builder
    {
        return Customer::query()
            ->where('type', 'b2b')
            ->whereHas('subscriptions', fn (Builder $q) => $q->where('status', 'active'))
            ->whereDoesntHave('orders', fn (Builder $q) => 
                $q->where('created_at', '>=', now()->subDays($this->daysThreshold))
            )
            ->where('total_lifetime_spend', '>=', $this->minimumSpend);
    }
}

Notice what changed here:

• The query constraints live in an explicit file inside App\Queries.
• Parameters like threshold days or minimum spend are strongly typed in the constructor.
• The model class remains lightweight, focusing purely on schema definition and relationships.

Step 2: Consuming Query Objects in Action Classes or Controllers

Now, inside your controller, job, or CLI command, you simply inject or instantiate the Query Object:

namespace App\Http\Controllers;

use App\Queries\GetDormantHighValueB2bCustomersQuery;
use Illuminate\Http\JsonResponse;

class MarketingTargetController extends Controller
{
    public function index(): JsonResponse
    {
        $query = new GetDormantHighValueB2bCustomersQuery(
            daysThreshold: 60,
            minimumSpend: 15000
        );

        $customers = $query->handle(perPage: 50);

        return response()->json($customers);
    }
}

namespace App\Http\Controllers;

use App\Queries\GetDormantHighValueB2bCustomersQuery;
use Illuminate\Http\JsonResponse;

class MarketingTargetController extends Controller
{
    public function index(): JsonResponse
    {
        $query = new GetDormantHighValueB2bCustomersQuery(
            daysThreshold: 60,
            minimumSpend: 15000
        );

        $customers = $query->handle(perPage: 50);

        return response()->json($customers);
    }
}

Repositories vs. Query Objects: Clearing the Confusion

In the PHP community, the “Repository Pattern” was heavily pushed years ago as the ultimate solution to Eloquent coupling. Many developers created interface-heavy structures like CustomerRepositoryInterface with methods like find(), save(), getDormant(), getRecent(), getVip().

In 90% of Laravel projects, generic repositories turn into God Interfaces. They become a dump for every custom query the app will ever run.

Architectural Rule of Thumb:

Repositories should be used for write operations or domain-entity hydration where you need to completely decouple from ORM storage details.

Query Objects should be used for read operations, complex filtering, reports, and search queries.

By separating reads into Query Objects, you respect CQRS (Command Query Responsibility Segregation) light principles without adding overwhelming boilerplate.

When SHOULD You Still Use Local Query Scopes?

Refactoring doesn’t mean deleting every single query scope from your application. Scopes are still fantastic for atomic, single-column boolean conditions that are ubiquitous across the domain.

Good candidates for query scopes:

• scopePublished($query) -> $query->whereNotNull('published_at')
• scopeWhereActive($query) -> $query->where('is_active', true)

Rule of thumb: If a scope requires joining multiple tables, complex grouping, or specific business analytics logic, pull it out into a Query Object immediately.

Key Takeaways for Your Codebase Today

1. Keep Models Lean: Your Eloquent models should describe data structure, relationships, and basic mutations—not multi-table analytical queries.
2. One Query, One Class: When a query spans multiple relationships or complex conditionals, create a dedicated class under App\Queries.
3. Avoid Mega-Repositories: Don’t trade Fat Models for Fat Repositories. Use invokable, single-purpose Query Objects for complex reads.
4. Test in Isolation: Query Objects allow you to test complex query constraints with dedicated database factories without clogging your primary model test suites.

Tidying up your database layer isn’t about dogmatic architectural purity—it’s about making sure that six months from now, when marketing changes the criteria for “dormant customers,” you only have to edit a single 30-line file without breaking three other features.

The post Refactoring the Database Layer: Replacing Query Scope Bloat with Repository/Query Objects appeared first on CodeCraft Diary.

Every software engineer has lived through this exact Thursday afternoon nightmare: The feature was thoroughly tested on the testing server. The CI/CD pipeline was a sea of reassuring green checkmarks. QA gave their final stamp of approval. With absolute confidence, you clicked “Deploy to Production.”

Ten minutes later, the alert channels started screaming, database connections saturated, and customers began reporting broken checkout flows.

When the post-mortem rolled around, the consensus was predictable: “The testing environment diverged from Production again. We need to sync the databases more often. We need to mirror the production setup exactly.”

So, the team spends two sprints setting up complex data-anonymization pipelines and mirroring server configurations. Yet, three months later, the exact same production incident happens again.

After few years of working on backend systems, debugging production outages, and trying to keep pipelines fast, I’ve come to a realization that many engineering teams refuse to accept: staging environments are lying to you—or, more accurately, long-lived shared staging environments often give teams a false sense of confidence.

Your testing setup isn’t failing because your DevOps team is lazy or because you haven’t automated your database dumps. It is failing because treating a shared testing environment as a safety net is an architectural and process flaw. Staging environments are a deployment problem, not an infrastructure problem.

Here you can find last article of this category: https://codecraftdiary.com/2026/07/26/merge-conflicts-process-problem/

The Four Myths of the “Identical” Staging Environment

We keep clinging to the idea of a pre-production testing environment because it feels safe. It gives us a comfortable illusion of risk mitigation. But when you look at how modern backend systems operate, the concept of a true “pre-production” environment completely falls apart for four main reasons.

1. The Data Drift Reality

You can dump your production database, run anonymization scripts, and seed your testing server every single night. It still won’t matter. Production data is dynamic, unpredictable, and dirty. It contains edge-case state combinations created by real users over years of operating the system.

A staging environment usually contains pristine, synthetic test data or a stripped-down database dump. You are unlikely to catch a bug that only triggers when a user has a legacy account created in 2021, three active subscriptions, and a special character in their billing address—because that specific state combination simply doesn’t exist outside of Production.

2. Third-Party Sandboxes Are Half-Baked

Modern backend architectures rely heavily on third-party APIs: payment processors like Stripe, email providers, or external auth services.

The sandbox environments provided by these services rarely behave like their production counterparts. A test mode won’t simulate exact rate limits, network latency, or edge-case webhook delivery failures. When your staging setup relies on mock services or sandbox APIs, you aren’t testing your application against reality; you are testing it against a simplified toy version of reality.

3. Traffic and Concurrency Don’t Exist on Testing Servers

Unless you are running expensive, continuous load testing against your pre-production environment (which almost nobody actually does), your testing server is dead quiet.

Your service running on Staging handles one or two requests at a time while a developer or QA engineer manually clicks through a flow. In Production, that same service handles thousands of concurrent requests, competing for thread pools, database connections, and cache space. Race conditions, deadlocks, and connection pool exhaustion only happen under real load. A staging server is fundamentally blind to them.

4. The Maintenance Sinkhole

Maintaining a testing server that somewhat resembles Production takes an immense amount of engineering effort. Databases need maintenance, API keys expire, test accounts get corrupted, and environment variables drift.

I’ve seen senior engineers spend 20% of their sprint time debugging issues that turned out to be “just a test server configuration issue.” That is wasted engineering effort spent maintaining an environment that doesn’t generate a single dollar of business value.

What Staging Is Actually Good For

None of this means staging environments are useless.

They still provide value for infrastructure validation, smoke testing after deployments, manual QA of integrated systems, customer demonstrations, and validating deployment pipelines.

The mistake isn’t having a staging environment. The mistake is treating it as the ultimate source of confidence before Production. A shared staging server should support your deployment process—not become the gatekeeper that every change must pass through.

How Staging Bottlenecks Your Entire Workflow

The technical limitations are bad enough, but the cultural impact on your team is worse.

When a team relies on a single shared testing server, it becomes a bottleneck for the entire delivery process. Developer A finishes a feature and deploys it to the testing server. Developer B finishes a completely unrelated bug fix and also deploys it there. Now, QA starts testing Developer B’s fix, but something breaks because Developer A’s feature introduced a bug.

Suddenly, nobody knows whose code broke the build. Deployment to Production gets blocked for everyone. What started as two small, independent changes transforms into a massive, tangled deployment batch.

By trying to make deployment “safer” through a shared testing environment, teams inadvertently recreate the exact problem they tried to avoid: large, high-risk releases.

Shift Your Mindset: From Pre-Production Safety to Production Resilience

If we accept that a testing server can never accurately predict how code will behave in Production, we have to change our approach. The goal shouldn’t be preventing all bugs from reaching Production through pre-production testing. The goal should be minimizing the blast radius of changes and recovering instantly when things go wrong.

High-performing engineering organizations don’t rely on long-lived testing servers. They shift their focus toward modern deployment practices.

Ephemeral (Preview) Environments

If you need an environment to test a feature before merging, don’t use a shared long-lived test server. Use ephemeral environments.

Preview environments solve a completely different problem than staging: they validate isolated changes rather than simulating production.

Whenever a developer opens a Pull Request, your CI pipeline can spin up a temporary, isolated Docker container or preview environment containing only that branch’s changes. The developer or QA can test the specific feature, run integration tests, and once the PR is merged or closed, the environment automatically destroys itself. This completely eliminates queueing, environment pollution, and cross-feature interference.

Progressive Delivery and Feature Flags

Instead of holding code back on a testing server for weeks, deploy code to Production immediately—behind a feature flag.

Feature flags decouple deployment (moving code to servers) from release (making functionality visible to users). You can deploy a new feature to Production on Monday, test it internally in the live environment using your own staff accounts, turn it on for 1% of real users on Wednesday, and gradually scale it to 100% by Friday. If something breaks at 1%, the blast radius is tiny, and turning off the flag takes milliseconds.

Observability and Fast Rollbacks

Your time is much better spent improving your production observability than fixing a testing server. Invest in proper tracing, structured logging, and automated metric alerts.

When you pair strong observability with an automated rollback strategy, catching a micro-bug in Production within 60 seconds of deployment is significantly cheaper and safer than spending three weeks manually validating everything on a test server.

Stop Servicing the Mirage

The next time a release breaks in Production, resist the urge to say, “We need to fix our testing environment.”

Step back and look at your workflow. Ask yourself why your Pull Requests are sitting on a testing server for days. Ask why your deployment process requires a green signal from an environment that doesn’t process real traffic or real data.

Staging environments give us a warm, comfortable feeling of safety, but in practice, they act as a tax on developer productivity and a false security blanket. Shrink your releases, flag your features, test in Production safely, and focus your energy on building resilient systems that recover quickly. Your pipeline—and your team—will thank you. The safest deployment process isn’t the one that spends the most time on staging. It’s the one that makes every production change small, observable, and reversible.

The post Staging Environments Are a Deployment Problem, Not an Infrastructure Problem appeared first on CodeCraft Diary.

CI is green.

Everyone merges their pull requests with confidence.

Then a seemingly harmless refactor breaks production.

If that sounds familiar, the problem isn’t always a lack of tests. Sometimes it’s the quality of those tests.

Just like production code can suffer from code smells, tests can accumulate test smells—patterns that make tests harder to understand, slower to maintain, or less effective at catching real bugs. A passing test suite isn’t automatically a trustworthy one.

After reviewing countless PHP projects over the years, I’ve noticed the same patterns appearing again and again. Whether you’re using PHPUnit, Pest, Laravel, Symfony, or another PHP framework, these smells are surprisingly common.

Let’s look at the ones worth eliminating first.

Last article in this Testing category you can find here: https://codecraftdiary.com/2026/07/13/testing-laravel-events-guide/

1. Assertion Roulette

One of the easiest ways to make a test frustrating is filling it with dozens of unrelated assertions.

public function test_user_profile()
{
    $user = User::factory()->create();

    $this->assertTrue($user->active);
    $this->assertEquals('John', $user->first_name);
    $this->assertEquals('Doe', $user->last_name);
    $this->assertNotNull($user->email_verified_at);
    $this->assertEquals('admin', $user->role);
}

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

When this test fails, the failure message rarely tells the whole story. Another developer has to inspect multiple assertions before understanding what actually broke.

A better approach is giving each test a single responsibility.

Instead of verifying five unrelated things, split them into smaller tests with descriptive names.

Small tests are easier to understand, easier to debug, and much harder to accidentally break.

Run on OnlinePHP.io

Try It Yourself: https://onlinephp.io/c/927b9

2. Mystery Guest

A test should be completely understandable on its own.

Unfortunately, many tests quietly depend on hidden data.

$user = User::find(1);

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

Where did user ID 1 come from?

Was it seeded?

Created by another test?

Imported from a dump?

Nobody knows.

This hidden dependency is known as the Mystery Guest smell.

Modern PHP testing tools make this easy to avoid.

Instead of relying on unknown database state, create exactly what your test needs.

$user = User::factory()->create();

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

Now every developer—and every CI pipeline—knows exactly where that user came from.

Run on OnlinePHP.io

Try It Yourself:https://onlinephp.io/c/42b4d

3. Fragile Assertions

Many tests verify far more than they actually need.

Imagine testing an API response.

$this->assertEquals(
    $expectedJson,
    $response->getContent()
);

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

Everything looks fine until another developer adds a harmless field like avatar_url.

Nothing is broken.

Your test still fails.

That’s not a useful failure—it’s unnecessary maintenance.

Instead, assert the behavior that actually matters.

For example, in Laravel:

$response->assertJsonFragment([
    'email' => 'john@example.com',
]);

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

Your tests should protect business behavior, not formatting details that change every sprint.

Run on OnlinePHP.io

Try It Yourself: https://onlinephp.io/c/78fae

4. Duplicate Setup Everywhere

Open a large test suite and sometimes every test starts with exactly the same setup.

$user = User::factory()->create();
$account = Account::factory()->create();
$order = Order::factory()->create();

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

Repeat that fifty times and your tests become noisy.

When setup dominates the test, readers spend more time understanding the preparation than the actual behavior being tested.

Extract common setup into helper methods, builders, or reusable factory states.

The goal isn’t fewer lines of code.

The goal is making the important part of the test immediately obvious.

5. Testing Implementation Instead of Behavior

This is probably the most expensive mistake teams make.

Imagine changing an internal algorithm.

The application still behaves exactly the same.

Users notice nothing.

Yet twenty tests suddenly fail.

Why?

Because they were testing implementation details rather than observable behavior.

A good test should answer:

“What should the application do?”

Not:

“How is the application currently doing it?”

Implementation changes happen constantly.

Business behavior should remain stable.

The closer your tests are to user-visible behavior, the more valuable they’ll become during refactoring.

6. Hardcoded IDs and Magic Values

Hardcoded values have a habit of surviving far longer than they should.

$user = User::find(42);

$this->assertEquals(5, $invoice->status);

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

Six months later, someone changes the seed data.

Now the test mysteriously fails.

Even worse, nobody remembers why the number 42 was special in the first place.

Prefer meaningful constants, enums, or freshly created models.

Your future self will thank you.

7. Logic Inside Tests

Tests should explain behavior.

They shouldn’t contain business logic themselves.

For example:

if ($user->isPremium()) {
    $expected = 25;
} else {
    $expected = 10;
}

$this->assertEquals($expected, $discount);

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

Now your test contains conditional logic that needs to be understood before anyone can even interpret the assertion.

Instead, create separate test cases.

public function test_premium_users_receive_25_percent_discount()

public function test_regular_users_receive_10_percent_discount()

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

Simple tests communicate intent much better than clever ones.

8. Slow Tests That Don’t Need to Be Slow

A slow test suite is one of the fastest ways to discourage developers from running tests regularly. If executing your test suite takes ten or fifteen minutes, people naturally start skipping it during development and rely solely on CI. That’s when bugs begin slipping through.

The good news is that PHP itself is rarely the bottleneck. More often, the slowdown comes from tests doing work they simply don’t need to do. Calling real third-party APIs, waiting with sleep(), rebuilding large datasets before every test, or repeating expensive setup hundreds of times can quickly turn a fast suite into a painful one.

Modern testing frameworks provide better alternatives for nearly all of these scenarios. Laravel, for example, allows you to fake queues, notifications, mail, events, and storage without sacrificing confidence in your application. Time-dependent code can be tested by freezing or traveling through time instead of waiting in real time, and external services should almost always be replaced with controlled test doubles rather than actual network requests.

The goal isn’t to make every individual test as fast as possible. It’s to eliminate unnecessary work while still testing real application behavior. A test that finishes in 50 milliseconds instead of 5 seconds might not seem important on its own, but multiply that by thousands of tests running on every pull request, and the difference becomes significant.

Fast feedback encourages developers to run tests frequently. And the more often your tests are executed, the more valuable they become.

// ❌ Slow

public function test_export(): void
{
    Storage::disk('s3')->put('report.pdf', '...');
    Mail::send(new ExportFinishedMail());
    Http::get('https://api.example.com');
}

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

// ✅ Faster

public function test_export(): void
{
    Storage::fake('s3');
    Mail::fake();
    Http::fake();

    // Test only your application's behavior
}

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

A short PHP example demonstrating this test smell.

Run on OnlinePHP.io

Try It Yourself: https://onlinephp.io/c/b6f80

9. Giant Tests That Verify Everything

Almost every long-lived project has at least one of these tests. You open the file expecting to understand a single piece of functionality, only to find a test that’s hundreds of lines long. It creates users, seeds multiple database records, processes orders, sends emails, dispatches events, updates the cache, writes logs, and finishes with a long list of assertions. At first glance, it feels comprehensive. In reality, it’s trying to verify far too many responsibilities at once.

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

public function test_complete_checkout_process(): void
{
    $user = User::factory()->create();
    $product = Product::factory()->create();

    $response = $this->postJson('/api/orders', [
        'product_id' => $product->id,
    ]);

    $response->assertCreated();

    Mail::assertSent(OrderConfirmationMail::class);
    Event::assertDispatched(OrderCreated::class);
    Queue::assertPushed(ProcessInvoice::class);

    $this->assertDatabaseHas('orders', [
        'user_id' => $user->id,
    ]);

    $this->assertDatabaseHas('payments', [
        'status' => 'completed',
    ]);

    Cache::has("user:{$user->id}:orders");

    Log::shouldHaveReceived('info');
}

The biggest problem with these “all-in-one” tests is that they become extremely fragile over time. When they fail, it’s often unclear what actually broke. Did the email notification change? Was the database state incorrect? Did an event stop dispatching? Or did a completely unrelated refactor accidentally affect one small part of the workflow? Instead of immediately fixing the issue, developers often spend more time investigating the failure than solving the real problem.

A better approach is to split large scenarios into smaller, focused tests that each verify a single aspect of the workflow. One test can ensure an order is created successfully, another can verify that the correct event is dispatched, and a third can confirm that a notification is sent. Together, these tests provide the same level of confidence while remaining significantly easier to understand, maintain, and debug.

Remember that a test suite is also documentation. When someone new joins the project, they should be able to read your tests and quickly understand how the application behaves. That’s almost impossible when one massive test tries to describe an entire business process. Smaller, focused tests produce clearer failure messages, encourage better design, and make future refactoring much less risky.

10. Tests Nobody Trusts

This is the smell that eventually destroys an entire test suite.

Developers start saying things like:

“Oh, just rerun the pipeline.”

“That test always fails randomly.”

“Ignore that one.”

The moment your team stops trusting the tests, they stop providing value.

Random failures, hidden dependencies, flaky assertions, and inconsistent environments slowly erode confidence until developers treat the test suite as background noise.

A reliable test suite doesn’t have to be enormous.

It has to be predictable.

If a test fails, developers should immediately believe something is actually wrong.

That’s the standard every test suite should aim for.

Final Thoughts

Writing tests is only half the job.

Writing tests that remain useful six months later is where the real challenge begins.

Whenever you create a new test, ask yourself a few simple questions:

• Does this test verify behavior instead of implementation?
• Would another developer understand it without extra context?
• Can it run independently?
• Will it still be valuable after a refactor?
• If this test fails in CI tomorrow, would I trust the failure?

A healthy test suite isn’t measured by the number of tests it contains or by achieving 100% code coverage.

It’s measured by the confidence it gives your team when making changes.

Because the best tests aren’t the ones that simply pass—they’re the ones that catch the bugs that matter.

The post The Most Common Test Smells in PHP (And How to Fix Them) appeared first on CodeCraft Diary.

A controller grows beyond a comfortable size, so part of its logic moves into an Eloquent model. Later, the application needs to send a notification after an order ships. Then inventory must be checked through an external API. Accounting requests an ERP integration, and marketing wants loyalty points awarded after dispatch.

Each change adds only a few lines. Since the Order model is already available wherever the feature is being implemented, adding one more method feels natural:

$order->ship();

$order->ship();

It is concise, expressive, and pleasantly object-oriented. Six months later, however, that innocent method may be updating several tables, calling two APIs, dispatching events, sending notifications, and deciding whether the entire operation is allowed.

The model has quietly become the place where the application runs its business workflows.

That is the real problem. It is not that the model is “fat.” It is that persistence, domain decisions, and application orchestration have been mixed together until nobody can change one without understanding all three.

Previous article in this category: https://codecraftdiary.com/2026/07/06/specification-pattern-in-laravel/

Business Logic in Eloquent Models Is Not Automatically Wrong

The common advice to remove all business logic from Laravel models goes too far.

Eloquent follows the Active Record pattern. Martin Fowler describes Active Record as an object that represents a database row, encapsulates database access, and adds domain logic related to that data. In other words, an object containing both state and behavior is not an architectural mistake by itself.

A model should be allowed to answer questions about itself:

class Order extends Model
{
    protected function casts(): array
    {
        return [
            'paid_at' => 'datetime',
            'expires_at' => 'datetime',
        ];
    }

    public function isPaid(): bool
    {
        return $this->paid_at !== null;
    }

    public function isExpired(): bool
    {
        return $this->expires_at?->isPast() ?? false;
    }

    public function hasShippingAddress(): bool
    {
        return filled($this->shipping_address);
    }
}

class Order extends Model
{
    protected function casts(): array
    {
        return [
            'paid_at' => 'datetime',
            'expires_at' => 'datetime',
        ];
    }

    public function isPaid(): bool
    {
        return $this->paid_at !== null;
    }

    public function isExpired(): bool
    {
        return $this->expires_at?->isPast() ?? false;
    }

    public function hasShippingAddress(): bool
    {
        return filled($this->shipping_address);
    }
}

These methods are cohesive. They depend only on the order’s own state and make that state easier to understand. Relationships, casts, scopes, accessors, mutators, and similar data-oriented behavior are also natural Eloquent responsibilities; Laravel itself defines relationships as model methods and provides casts specifically for transforming model attributes.

The useful distinction is therefore not business logic versus no business logic.

It is describing state versus coordinating work.

When a Model Starts Coordinating the Application

Consider a more ambitious implementation of ship():

class Order extends Model
{
    public function ship(): void
    {
        if (! $this->isPaid() || ! $this->hasShippingAddress()) {
            throw new DomainException('The order cannot be shipped.');
        }

        $inventoryResponse = Http::get(
            "https://inventory.internal/orders/{$this->id}"
        );

        if (! $inventoryResponse->json('available')) {
            throw new DomainException('The items are not available.');
        }

        DB::transaction(function (): void {
            $this->update(['status' => 'shipped']);

            $this->items()->decrement('reserved_quantity');
        });

        Http::post('https://shipping.example.com/dispatch', [
            'order_id' => $this->id,
        ]);

        $this->customer->notify(
            new OrderShippedNotification($this)
        );

        event(new OrderShipped($this));
    }
}

class Order extends Model
{
    public function ship(): void
    {
        if (! $this->isPaid() || ! $this->hasShippingAddress()) {
            throw new DomainException('The order cannot be shipped.');
        }

        $inventoryResponse = Http::get(
            "https://inventory.internal/orders/{$this->id}"
        );

        if (! $inventoryResponse->json('available')) {
            throw new DomainException('The items are not available.');
        }

        DB::transaction(function (): void {
            $this->update(['status' => 'shipped']);

            $this->items()->decrement('reserved_quantity');
        });

        Http::post('https://shipping.example.com/dispatch', [
            'order_id' => $this->id,
        ]);

        $this->customer->notify(
            new OrderShippedNotification($this)
        );

        event(new OrderShipped($this));
    }
}

The public API still looks elegant, but the implementation hides a surprising amount of machinery. Calling one method now performs HTTP requests, changes persistent state, updates inventory, sends a notification, and publishes an event.

That creates several practical problems.

First, its dependencies are invisible. Nothing about $order->ship() tells the caller that a shipping provider and inventory system must be available. Second, testing one business rule requires faking HTTP requests, notifications, events, and probably a database. Third, every future shipping requirement will be attracted to the same method because it already appears to be the official home of the workflow.

The class may still be called Order, but it is acting as an application service.

Give the Workflow an Explicit Home

The solution does not require hexagonal architecture, CQRS, repositories for every model, or an interface in front of every class. For many Laravel applications, one focused workflow class is enough.

Whether your team calls it an action, command, handler, or service matters less than giving it a clear responsibility.

namespace App\Actions;

use App\Models\Order;
use App\Notifications\OrderShippedNotification;
use App\Services\InventoryService;
use App\Services\ShippingGateway;
use Illuminate\Support\Facades\DB;

final class ShipOrder
{
    public function __construct(
        private InventoryService $inventory,
        private ShippingGateway $shipping,
    ) {
    }

    public function handle(Order $order): void
    {
        $this->ensureOrderCanBeShipped($order);

        $shipment = $this->shipping->dispatch($order);

        DB::transaction(function () use ($order, $shipment): void {
            $order->update([
                'status' => 'shipped',
                'shipment_reference' => $shipment->reference,
                'shipped_at' => now(),
            ]);
        });

        $order->customer->notify(
            new OrderShippedNotification($order)
        );
    }

    private function ensureOrderCanBeShipped(Order $order): void
    {
        if (! $order->isPaid()) {
            throw new CannotShipOrder('The order has not been paid.');
        }

        if (! $order->hasShippingAddress()) {
            throw new CannotShipOrder('The shipping address is missing.');
        }

        if (! $this->inventory->isAvailableFor($order)) {
            throw new CannotShipOrder('One or more items are unavailable.');
        }
    }
}

namespace App\Actions;

use App\Models\Order;
use App\Notifications\OrderShippedNotification;
use App\Services\InventoryService;
use App\Services\ShippingGateway;
use Illuminate\Support\Facades\DB;

final class ShipOrder
{
    public function __construct(
        private InventoryService $inventory,
        private ShippingGateway $shipping,
    ) {
    }

    public function handle(Order $order): void
    {
        $this->ensureOrderCanBeShipped($order);

        $shipment = $this->shipping->dispatch($order);

        DB::transaction(function () use ($order, $shipment): void {
            $order->update([
                'status' => 'shipped',
                'shipment_reference' => $shipment->reference,
                'shipped_at' => now(),
            ]);
        });

        $order->customer->notify(
            new OrderShippedNotification($order)
        );
    }

    private function ensureOrderCanBeShipped(Order $order): void
    {
        if (! $order->isPaid()) {
            throw new CannotShipOrder('The order has not been paid.');
        }

        if (! $order->hasShippingAddress()) {
            throw new CannotShipOrder('The shipping address is missing.');
        }

        if (! $this->inventory->isAvailableFor($order)) {
            throw new CannotShipOrder('One or more items are unavailable.');
        }
    }
}

The controller remains small without forcing the workflow into the model:

final class ShipOrderController
{
    public function __invoke(
        Order $order,
        ShipOrder $shipOrder,
    ): JsonResponse {
        $shipOrder->handle($order);

        return response()->json([
            'message' => 'Order shipped successfully.',
        ]);
    }
}

final class ShipOrderController
{
    public function __invoke(
        Order $order,
        ShipOrder $shipOrder,
    ): JsonResponse {
        $shipOrder->handle($order);

        return response()->json([
            'message' => 'Order shipped successfully.',
        ]);
    }
}

This is not better merely because the code lives in another file. It is better because the dependencies and responsibility are now explicit. InventoryService answers an inventory question. ShippingGateway communicates with the shipping provider. ShipOrder coordinates the use case. The Order model describes and persists order state.

Laravel’s transaction helper also gives the persistence portion a clear boundary and automatically rolls it back when an exception is thrown.

Avoid Building a Fat Action Instead

Extracting a workflow does not give it permission to become another dumping ground.

If ShipOrder eventually contains payment processing, PDF generation, ERP payload construction, low-level HTTP calls, and hundreds of lines of unrelated calculations, the architecture has not improved much. The oversized model has simply been replaced by an oversized action.

A workflow class should coordinate collaborators rather than implement every collaborator itself. External API details belong behind focused clients or gateways. Complicated calculations may deserve dedicated domain objects. Slow, retryable work can be handed to queued jobs; Laravel provides queues specifically for deferring work across several supported backends.

Real integrations also introduce failure scenarios that a short example cannot solve completely. A shipping provider might accept a request just before the database update fails. Production systems may therefore need idempotency keys, retry policies, an outbox, or an intermediate status such as shipping_pending. The important point is that these concerns become easier to see once the workflow has an explicit home.

A Rule That Is Actually Useful

When deciding where a new method belongs, ask one question:

Does this method describe the object, or does it coordinate the application?

These methods usually fit naturally on a model:

$order->isPaid();
$order->isExpired();
$product->isDiscontinued();
$user->hasVerifiedEmail();

$order->isPaid();
$order->isExpired();
$product->isDiscontinued();
$user->hasVerifiedEmail();

These operations deserve closer inspection:

$order->ship();
$order->issueRefund();
$invoice->sendToAccounting();
$product->synchronizeWithErp();

$order->ship();
$order->issueRefund();
$invoice->sendToAccounting();
$product->synchronizeWithErp();

Good Laravel architecture is not about producing the largest possible number of small classes. It is about making the next change obvious.

Your Eloquent models can contain meaningful behavior. They should understand their relationships, attributes, and state. What they should not quietly become is the control room for the rest of the application.

When workflows have explicit homes and dependencies have clear boundaries, controllers stay readable, models remain coherent, and future developers do not need to reverse-engineer half the codebase to discover what happens when an order ships.

The models were never the real enemy.

The hidden workflows were.

The post Your Laravel Models Aren’t the Problem. Hidden Workflows Are. appeared first on CodeCraft Diary.

Git tells you that two people changed the same code, highlights the conflicting lines, and leaves you to sort it out. After a few minutes of editing, you commit the resolution and move on.

It feels like Git is the problem.

But after working on enough backend projects, I’ve come to a different conclusion.

Merge conflicts are rarely caused by Git itself.

Git is simply exposing a problem that already exists in your development process.

If your team spends hours every week resolving merge conflicts, the real issue probably isn’t your version control system. It’s how your team works.

Last article in this category: https://codecraftdiary.com/2026/06/28/automated-testing-strategies-for-trunk-based-development-how-to-build-a-10-minute-pipeline/

Git Isn’t Creating the Conflict

One thing that’s easy to forget is that Git doesn’t invent conflicts.

A merge conflict only appears when Git genuinely cannot determine which change should win.

Imagine two developers working on the same controller.

Developer A adds request validation.

Developer B changes the response format.

Both modify the same method.

Git stops and asks someone to make the decision because it simply doesn’t have enough context.

That’s exactly what it’s supposed to do.

The conflict isn’t a Git failure.

The failure happened much earlier—when two developers unknowingly spent days modifying the same piece of code.

The Real Question Is: Why Did This Happen?

Whenever someone tells me:

“Git merge conflicts are driving me crazy.”

I usually ask one question.

How long was your branch open?

More often than not, the answer is:

• four days
• one week
• sometimes even three weeks

That’s usually where the real problem begins.

Every day your branch stays isolated, the main branch keeps moving.

Someone renames classes.

Someone refactors a service.

Someone fixes a production bug.

Someone updates dependencies.

By the time you’re ready to merge, your code is no longer based on today’s project—it’s based on the project from last week.

Git is simply the first tool to point that out.

The Hidden Cost Isn’t the Conflict

People often think merge conflicts are expensive because they take time to resolve.

In reality, editing the conflicting lines usually takes only a few minutes.

Understanding why the conflict exists is what costs time.

Imagine this situation.

You started a feature on Monday.

By Friday:

• six pull requests have been merged
• your service has been partially refactored
• another developer extracted shared logic into a new class
• someone fixed a production bug in the same module

Now Git reports a conflict.

You’re no longer solving one conflict.

You’re rebuilding your mental model of everything that happened while you were working.

That’s the expensive part.

Large Pull Requests Multiply the Problem

One pattern appears almost everywhere.

Large pull requests almost always create larger merge conflicts.

It isn’t surprising.

A pull request with 2,000 changed lines touches dozens of files.

A pull request with 150 lines might touch only two or three.

Which one is more likely to overlap with someone else’s work?

Exactly.

This is one of the biggest reasons I prefer small pull requests.

Smaller changes don’t just make reviews easier.

They dramatically reduce the chance that multiple developers modify the same code at the same time.

Long-Lived Branches Drift Away From Reality

Feature branches aren’t the problem.

Long-lived feature branches are.

I’ve seen teams spend two weeks building a feature before opening their first pull request.

By then, the main branch has evolved so much that merging becomes an entire task on its own.

Developers spend hours:

• fixing conflicts
• updating failing tests
• adapting to refactored services
• resolving dependency changes

Ironically, teams often conclude that merging is painful.

The truth is slightly different.

Merging became painful because they waited too long.

Communication Prevents More Conflicts Than Git Ever Will

Not every conflict can be avoided.

Sometimes two developers genuinely need to work in the same part of the application.

The difference is whether they know about each other.

Imagine this.

One developer is refactoring the authentication service.

Another developer is implementing passwordless login.

Without communication, both spend several days modifying the same code.

The conflict is inevitable.

Now imagine a five-minute conversation before they start.

“I’m working on AuthService this week.”

“Me too.”

“Let’s split the work and merge more often.”

Five minutes of communication can save hours of unnecessary conflict resolution.

Git could never solve that problem.

Trunk-Based Development Changes Everything

This is one of the biggest reasons I’m such a fan of Trunk-Based Development.

The goal isn’t to eliminate merge conflicts completely.

That’s impossible.

The goal is to make them so small that nobody really cares.

Instead of merging once every Friday…

…developers merge several times every day.

Instead of resolving fifty conflicts at once…

…they resolve one tiny overlap before lunch.

Small branches create small pull requests.

Small pull requests create small conflicts.

Small conflicts rarely interrupt development.

The Most Dangerous Conflicts Never Appear in Git

Interestingly, the worst conflicts aren’t merge conflicts at all.

Imagine this scenario.

Developer A changes how discounts are calculated.

Developer B changes invoice generation.

Different files.

No merge conflict.

Everything merges perfectly.

Production breaks because invoice generation still expects the previous discount logic.

Git couldn’t detect that.

The problem wasn’t textual.

It was logical.

These hidden conflicts become much easier to discover when teams integrate continuously instead of waiting days before merging.

How to Reduce Merge Conflicts

No workflow eliminates merge conflicts completely.

But a few simple habits make them significantly less painful.

• Merge into the main branch frequently.
• Keep pull requests small.
• Avoid combining unrelated changes.
• Communicate when multiple developers work in the same area.
• Use feature flags instead of long-lived branches.
• Review pull requests quickly so they don’t sit idle for days.

None of these practices are revolutionary.

Together, however, they change merge conflicts from major interruptions into minor inconveniences.

Stop Blaming Git

Git has become one of the easiest tools to blame.

It reports the conflict.

It highlights the differences.

It forces developers to make a decision.

But Git didn’t create the problem.

It simply revealed it.

The next time your team spends an afternoon resolving merge conflicts, don’t ask:

“How can we get better at Git?”

Ask something much more valuable:

“What in our development process allowed this conflict to grow this large?”

Most of the time, the answer isn’t hidden in a Git command.

It’s hidden in the workflow.

And once the workflow improves, merge conflicts become exactly what they should be: small, occasional interruptions instead of recurring team-wide headaches.

The post Merge Conflicts Are a Process Problem, Not a Git Problem appeared first on CodeCraft Diary.

We’ve all been there. You trigger an OrderPlaced event. It’s supposed to send an email, update the inventory, and notify the warehouse. One day, you realize the email never sent because an exception in the inventory listener swallowed the entire process. If you aren’t testing your events properly, you aren’t just missing code coverage—you are leaving your business workflows to chance.

In this guide, we’ll move beyond basic Event::fake() assertions and explore how to build a robust testing strategy for event-driven Laravel applications.

Previous article in this category: https://codecraftdiary.com/2026/06/22/tdd-in-laravel/

The Problem with “Testing Too Much”

When developers start testing events, the default instinct is to reach for Event::fake(). It’s easy, it’s fast, and it makes the test pass.

public function test_order_is_placed(): void
{
    Event::fake();

    $this->post('/checkout', [...]);

    Event::assertDispatched(OrderPlaced::class);
}

public function test_order_is_placed(): void
{
    Event::fake();

    $this->post('/checkout', [...]);

    Event::assertDispatched(OrderPlaced::class);
}

This test tells us one thing: Did we trigger the event? It tells us absolutely nothing about whether the listeners actually work or if they communicate correctly with each other. If you rely solely on faking, your test suite becomes a “smoke screen” that passes even when your underlying infrastructure is broken.

1. Unit Testing Listeners in Isolation

The best way to ensure reliability is to treat your Listeners like any other service class. A listener should have one job. If it has complex logic, extract it into a dedicated Action or Service class and test that.

// app/Listeners/SendOrderConfirmation.php
public function handle(OrderPlaced $event): void
{
    // Don't put business logic here!
    $this->mailer->sendConfirmation($event->order);
}

// app/Listeners/SendOrderConfirmation.php
public function handle(OrderPlaced $event): void
{
    // Don't put business logic here!
    $this->mailer->sendConfirmation($event->order);
}

By keeping the listener thin, your unit test for SendOrderConfirmation becomes trivial. You can mock the Mailer service and simply verify the handle() method is called correctly. This is fast, deterministic, and catches bugs in the communication layer without overhead.

2. Integration Testing: The “End-to-End” Event Flow

When you want to verify that the OrderPlaced event actually triggers the SendOrderConfirmation listener and writes the correct data to the database, you need an integration test.

Crucially, do not fake the event here. Instead, allow the event to dispatch and verify the side effects.

public function test_order_placed_event_triggers_side_effects(): void
{
    // 1. Arrange: Setup user and cart
    $order = Order::factory()->create();

    // 2. Act: Trigger the event directly
    OrderPlaced::dispatch($order);

    // 3. Assert: Check side effects, not just the dispatch
    $this->assertDatabaseHas('emails', [
        'order_id' => $order->id,
        'status' => 'sent'
    ]);
}

public function test_order_placed_event_triggers_side_effects(): void
{
    // 1. Arrange: Setup user and cart
    $order = Order::factory()->create();

    // 2. Act: Trigger the event directly
    OrderPlaced::dispatch($order);

    // 3. Assert: Check side effects, not just the dispatch
    $this->assertDatabaseHas('emails', [
        'order_id' => $order->id,
        'status' => 'sent'
    ]);
}

This approach proves that your Service Provider is correctly registered and that the binding between the Event and Listener is active.

3. Handling Asynchronous Queues

The biggest trap is the mix of synchronous and asynchronous listeners. If your listener implements ShouldQueue, Event::fake() will prevent the job from ever being pushed to the queue.

To test queued listeners, use the Bus and Queue facades in tandem:

public function test_order_placed_event_queues_notification(): void
{
    Queue::fake();

    Event::dispatch(new OrderPlaced($order));

    Queue::assertPushed(SendOrderConfirmation::class, function ($job) use ($order) {
        return $job->order->id === $order->id;
    });
}

public function test_order_placed_event_queues_notification(): void
{
    Queue::fake();

    Event::dispatch(new OrderPlaced($order));

    Queue::assertPushed(SendOrderConfirmation::class, function ($job) use ($order) {
        return $job->order->id === $order->id;
    });
}

Pro Tip: If you are testing a complex flow, don’t forget to test the failure state. Use Queue::assertPushed to verify that the retry logic or failure handling (like failed() methods) is configured for your mission-critical jobs.

4. Avoiding “The Silent Failure”

One common mistake is neglecting what happens when a listener fails. If your application relies on a chain of events, you must test the “atomic” nature of the flow.

If you are using Laravel 11/12+ features, ensure you are testing your custom shouldDiscoverEvents logic if you use event discovery. Hidden logic is the enemy of maintainable tests. If a developer adds a new listener to a directory, does your test suite automatically include it? By writing explicit integration tests for critical flows, you ensure that even “magically” discovered events are held accountable.

Testing Checklist for Events

To keep your test suite maintainable as your project grows:

• Logic Extraction: If a listener is more than 5 lines, move the logic to an Action class.
• Fake Sparingly: Use Event::fake() only when you specifically want to verify the triggering of an event, not its outcome.
• Verify Side Effects: Always write at least one integration test that lets the event fire “for real” to ensure the pipeline is wired up correctly.
• Queue Awareness: Always distinguish between testing the dispatch and testing the queued job execution.

The post Testing Laravel Events and Listeners: Ensuring Reliable Asynchronous Workflows appeared first on CodeCraft Diary.

You start simple. A user is allowed to purchase a premium item if they are active. Easy—you write a quick Eloquent scope. But three months later, the business team changes the rules. Now, a user can only buy that item if they are active, have a verified email, have spent at least $500 in the last 90 days, and are not flagged for suspicious activity.

Suddenly, your code becomes littered with long chains of Eloquent scopes in your queries, and worse, identical blocks of if-else statements in your PHP services to check the exact same logic for already-loaded models.

This is where the codebase starts to smell. We are violating the Single Responsibility Principle, duplicating rules, and creating a maintenance nightmare. To fix this, developers often reach for complex design patterns that end up overengineering the solution, violating the KISS (Keep It Simple, Stupid) principle.

But there is a elegant, highly practical pattern that solves this perfectly without breaking a sweat: The Specification Pattern.

Previous article in refactoring category: https://codecraftdiary.com/2026/06/15/laravel-event-driven-architecture/

The Real-World Problem: The “Premium Customer” Mess

Let’s look at a concrete example. Imagine an e-commerce platform where we need to determine if a customer qualifies for a VIP Discount.

The business rules for a VIP customer are:

1. The account must be active.
2. The user must have a verified email.
3. They must have made at least 5 orders in total.
4. They must not be on our fraud blacklist.

The Naive Laravel Approach

Typically, you see developers solving this in two ways. First, they write a massive query in a controller or service:

// In a Controller or Service
$vipUsers = User::query()
    ->where('is_active', true)
    ->whereNotNull('email_verified_at')
    ->whereHas('orders', function ($query) {
        $query->where('status', 'completed');
    }, '>=', 5)
    ->whereDoesntHave('flags', function ($query) {
        $query->where('type', 'fraud');
    })
    ->get();

// In a Controller or Service
$vipUsers = User::query()
    ->where('is_active', true)
    ->whereNotNull('email_verified_at')
    ->whereHas('orders', function ($query) {
        $query->where('status', 'completed');
    }, '>=', 5)
    ->whereDoesntHave('flags', function ($query) {
        $query->where('type', 'fraud');
    })
    ->get();

This works fine for fetching data from the database. But what happens when you already have a User instance in memory—say, inside a Job or an Event Listener—and you need to check if this specific user qualifies?

You end up duplicating the logic in pure PHP:

public function qualifiesForVipDiscount(User $user): bool
{
    return $user->is_active 
        && $user->email_verified_at !== null
        && $user->orders()->where('status', 'completed')->count() >= 5
        && !$user->flags()->where('type', 'fraud')->exists();
}

public function qualifiesForVipDiscount(User $user): bool
{
    return $user->is_active 
        && $user->email_verified_at !== null
        && $user->orders()->where('status', 'completed')->count() >= 5
        && !$user->flags()->where('type', 'fraud')->exists();
}

Why this breaks the KISS principle:

• Duplication: If the fraud rule changes, you have to find and rewrite both the SQL/Eloquent logic and the in-memory PHP logic.
• Model Bloat: Shoving this into the User model makes it a “God Object” over time.
• Hidden Rules: Your business logic is trapped inside technical database implementation details.

Enter the Specification Pattern

The Specification Pattern solves this by turning a business rule into a first-class citizen—a single, isolated, reusable class.

A strict specification pattern can sometimes get overly complex with abstract syntax trees and custom expression builders. To keep it KISS-compliant, we are going to build a pragmatic version tailored for modern PHP 8.5+ and Laravel.

Let’s define a simple interface for our specifications:

namespace App\Specifications;

use Illuminate\Database\Eloquent\Builder;

interface Specification
{
    /**
     * Check if a given object satisfies the specification in-memory.
     */
    public function isSatisfiedBy(mixed $candidate): bool;

    /**
     * Apply the specification directly to an Eloquent query builder.
     */
    public function apply(Builder $query): void;
}

namespace App\Specifications;

use Illuminate\Database\Eloquent\Builder;

interface Specification
{
    /**
     * Check if a given object satisfies the specification in-memory.
     */
    public function isSatisfiedBy(mixed $candidate): bool;

    /**
     * Apply the specification directly to an Eloquent query builder.
     */
    public function apply(Builder $query): void;
}

Implementing the Specification

Let’s build our IsVipCustomer specification. Instead of writing abstract logic, we put our exact four business rules inside this class.

namespace App\Specifications;

use App\Models\User;
use Illuminate\Database\Eloquent\Builder;

class IsVipCustomer implements Specification
{
    public function isSatisfiedBy(mixed $candidate): bool
    {
        if (!$candidate instanceof User) {
            return false;
        }

        return $candidate->is_active
            && $candidate->email_verified_at !== null
            && $candidate->orders->where('status', 'completed')->count() >= 5
            && !$candidate->flags->contains('type', 'fraud');
    }

    public function apply(Builder $query): void
    {
        $query->where('is_active', true)
            ->whereNotNull('email_verified_at')
            ->whereHas('orders', function ($q) {
                $q->where('status', 'completed');
            }, '>=', 5)
            ->whereDoesntHave('flags', function ($q) {
                $q->where('type', 'fraud');
            });
    }
}

namespace App\Specifications;

use App\Models\User;
use Illuminate\Database\Eloquent\Builder;

class IsVipCustomer implements Specification
{
    public function isSatisfiedBy(mixed $candidate): bool
    {
        if (!$candidate instanceof User) {
            return false;
        }

        return $candidate->is_active
            && $candidate->email_verified_at !== null
            && $candidate->orders->where('status', 'completed')->count() >= 5
            && !$candidate->flags->contains('type', 'fraud');
    }

    public function apply(Builder $query): void
    {
        $query->where('is_active', true)
            ->whereNotNull('email_verified_at')
            ->whereHas('orders', function ($q) {
                $q->where('status', 'completed');
            }, '>=', 5)
            ->whereDoesntHave('flags', function ($q) {
                $q->where('type', 'fraud');
            });
    }
}

Notice how clean this is. The technical details of how we determine a VIP customer are encapsulated in exactly one file.

Making It Truly Useful: Combining Specifications

Where this pattern completely demolishes standard refactoring approaches is when business requirements change or combine. What if we want to find users who are VIP Customers AND are Located in the EU (for tax or shipping promotions)?

Instead of writing a third massive scope, we can create a simple composition layer. Let’s create an AndSpecification:

namespace App\Specifications;

use Illuminate\Database\Eloquent\Builder;

class AndSpecification implements Specification
{
    private array $specifications;

    public function __construct(Specification ...$specifications)
    {
        $this->specifications = $specifications;
    }

    public function isSatisfiedBy(mixed $candidate): bool
    {
        foreach ($this->specifications as $spec) {
            if (!$spec->isSatisfiedBy($candidate)) {
                return false;
            }
        }
        return true;
    }

    public function apply(Builder $query): void
    {
        foreach ($this->specifications as $spec) {
            $spec->apply($query);
        }
    }
}

namespace App\Specifications;

use Illuminate\Database\Eloquent\Builder;

class AndSpecification implements Specification
{
    private array $specifications;

    public function __construct(Specification ...$specifications)
    {
        $this->specifications = $specifications;
    }

    public function isSatisfiedBy(mixed $candidate): bool
    {
        foreach ($this->specifications as $spec) {
            if (!$spec->isSatisfiedBy($candidate)) {
                return false;
            }
        }
        return true;
    }

    public function apply(Builder $query): void
    {
        foreach ($this->specifications as $spec) {
            $spec->apply($query);
        }
    }
}

Putting It Into Practice (Where It Pays Off)

Let’s look at how this simplifies our daily Laravel tasks. We’ll look at a Controller (database querying) and a Service/Job (in-memory validation).

Scenario A: Querying the Database

Inside your Admin Dashboard controller, you need to list all VIP customers from the EU to send them a special newsletter.

namespace App\Http\Controllers;

use App\Models\User;
use App\Specifications\AndSpecification;
use App\Specifications\IsVipCustomer;
use App\Specifications\IsLocatedInEU;

class VipNewsletterController extends Controller
{
    public function __invoke()
    {
        // Define the composite rule
        $vipInEuSpec = new AndSpecification(
            new IsVipCustomer(),
            new IsLocatedInEU()
        );

        // Apply it directly to the query
        $query = User::query();
        $vipInEuSpec->apply($query);
        
        $users = $query->paginate(30);

        return view('admin.vip-newsletter', compact('users'));
    }
}

namespace App\Http\Controllers;

use App\Models\User;
use App\Specifications\AndSpecification;
use App\Specifications\IsVipCustomer;
use App\Specifications\IsLocatedInEU;

class VipNewsletterController extends Controller
{
    public function __invoke()
    {
        // Define the composite rule
        $vipInEuSpec = new AndSpecification(
            new IsVipCustomer(),
            new IsLocatedInEU()
        );

        // Apply it directly to the query
        $query = User::query();
        $vipInEuSpec->apply($query);
        
        $users = $query->paginate(30);

        return view('admin.vip-newsletter', compact('users'));
    }
}

Scenario B: In-Memory Domain Validation

Now imagine a completely different part of the app. A user clicks “Claim VIP Reward”. The user is already logged in, so we already have the $user instance loaded in memory. We don’t want to hit the database with complex heavy joins again if we can avoid it.

namespace App\Http\Controllers;

use App\Specifications\IsVipCustomer;
use Illuminate\Http\Request;

class RewardController extends Controller
{
    public function claim(Request $request, IsVipCustomer $vipSpec)
    {
        $user = $request->user();

        // Check the exact same business rule in-memory
        if (!$vipSpec->isSatisfiedBy($user)) {
            return response()->json([
                'error' => 'You do not qualify for this reward.'
            ], 403);
        }

        // Process reward...
        return response()->json(['success' => 'Reward claimed!']);
    }
}

namespace App\Http\Controllers;

use App\Specifications\IsVipCustomer;
use Illuminate\Http\Request;

class RewardController extends Controller
{
    public function claim(Request $request, IsVipCustomer $vipSpec)
    {
        $user = $request->user();

        // Check the exact same business rule in-memory
        if (!$vipSpec->isSatisfiedBy($user)) {
            return response()->json([
                'error' => 'You do not qualify for this reward.'
            ], 403);
        }

        // Process reward...
        return response()->json(['success' => 'Reward claimed!']);
    }
}

Why This is NOT Overengineering

If you look at the code above, a skeptic might say: “Why did we create three classes when a couple of Eloquent scopes could do the trick?”

Here is why this approach honors the KISS principle when dealing with real complexity:

1. The “Single Source of Truth” rule: If the marketing team changes the definition of a VIP customer to require 10 orders instead of 5, you change one number in one class. Your controllers, jobs, and models remain completely untouched.
2. Database vs. Memory consistency: Standard Eloquent scopes cannot be run on a regular PHP collection or an already-loaded model without triggering fresh SQL queries. The Specification Pattern bridges this gap natively.
3. Impeccable Testability: Testing complex business logic mixed with controllers is painful. Testing a Specification class is a pure unit test. You pass a mock user, assert true or false, and you’re done in milliseconds.

public function test_user_with_insufficient_orders_is_not_vip()
{
    $user = new User(['is_active' => true, 'email_verified_at' => now()]);
    $user->setRelation('orders', collect()); // 0 orders
    $user->setRelation('flags', collect());

    $spec = new IsVipCustomer();

    $this->assertFalse($spec->isSatisfiedBy($user));
}

public function test_user_with_insufficient_orders_is_not_vip()
{
    $user = new User(['is_active' => true, 'email_verified_at' => now()]);
    $user->setRelation('orders', collect()); // 0 orders
    $user->setRelation('flags', collect());

    $spec = new IsVipCustomer();

    $this->assertFalse($spec->isSatisfiedBy($user));
}

Summary: When to Use It

Don’t use this pattern for simple things like User::where('role', 'admin'). That would be overengineering.

Reach for the Specification Pattern when:

• A business rule is dynamic and changes often based on business requirements.
• You need to use the exact same rule for both database filtering and in-memory validation.
• You need to combine multiple business rules dynamically depending on the context (e.g., matching different combinations of criteria for user segmentation).

By encapsulating volatile business logic into isolated specifications, you keep your models thin, your controllers clean, and your application incredibly adaptive to future changes. It’s Clean Architecture at its most practical level.

The post The Specification Pattern in Laravel: Refactoring Complex Business Rules appeared first on CodeCraft Diary.

But let’s be honest. When you tell a traditional QA manager or a risk-averse lead that developers are going to merge straight into the main branch and deploy to production ten times a day, they usually have a mini panic attack.

And they aren’t entirely wrong to worry.

If your team is merging code directly into the trunk every few hours, you cannot rely on manual regression testing. You cannot wait for a weekly QA cycle, and you certainly cannot spend two hours manually clicking through a staging environment to make sure a bugfix didn’t break the payment gateway.

To make Trunk-Based Development work without crashing production, you need an automated testing strategy built for speed and high confidence. You need a pipeline that gives you a definitive “Yes” or “No” in under 10 minutes.

Here is how we can build it from a backend perspective.

Why the Traditional Testing Pyramid Fails in TBD

We’ve all seen the classic testing pyramid: a massive base of unit test suites, a middle layer of integration tests, and a tiny peak of End-to-End (E2E) UI tests.

       /\
      /  \    <-- E2E / UI Tests (Slow, Flaky)
     /____\
    /      \  <-- Integration Tests (Medium Speed)
   /________\
  /          \ <-- Unit Tests (Fast, Isolated)
 /____________\

In theory, it’s a great model. In a Trunk-Based Development workflow, however, teams often warp this pyramid into something that looks more like an ice cream cone. Frontend teams or QA engineers might want to cover every single user flow with massive E2E integration suites to feel safe.

But as backend developers, we hit a major bottleneck here: heavy end-to-end tests are notoriously slow.

If your CI pipeline takes 45 minutes to run because it needs to spin up frontend clients, log in dummy users, and click through a shopping cart just to verify a backend API change, your TBD flow breaks down entirely. Developers will stop merging frequently. They will accumulate code locally because waiting for the pipeline feels like a punishment. Suddenly, your small PRs become massive again, and you’re right back to square one.

To make TBD work, your pipeline must act as a fast feedback loop, not a bureaucratic checkpoint.

The Core Strategy: The 10-Minute Rule

The golden rule of Continuous Integration in a fast-paced team is simple: The commit-to-feedback loop must take less than 10 minutes.

If a developer pushes a change to the trunk (or opens a tiny, short-lived PR that will be merged within an hour), they should know almost immediately if they broke the build. If it takes longer than 10 minutes, the developer context-switches, starts a new task, and by the time the build fails, they have to drop what they are doing to fix a problem they’ve already forgotten about.

To achieve a 10-minute pipeline, you have to split your testing strategy into two distinct phases: Pre-Merge (Gatekeeping) and Post-Merge (Asynchronous Verification).

Phase 1: Pre-Merge Validation (The Gatekeeper)

Before code touches the main branch, your CI pipeline needs to run a highly optimized, strictly isolated suite of checks. This is your first line of defense.

1. Advanced Unit Testing & Mocking

Unit tests must form the absolute majority of your test suite. They should test pure logic, edge cases, and data transformations without touching external networks, file systems, or databases.

Instead of hitting a real database, use clean interfaces and mocks. For example, if you are testing a backend service that calculates a user’s premium subscription discount, do not query the database to fetch the user profile. Pass a mock object or a stub.

// Example of a fast, isolated unit test
describe('DiscountService', () => {
  it('should apply a 20% discount for premium users', () => {
    const mockUser = { id: 1, type: 'PREMIUM' };
    const price = 100;
    
    const finalPrice = DiscountService.calculate(mockUser, price);
    
    expect(finalPrice).toBe(80); // Runs in milliseconds
  });
});

// Example of a fast, isolated unit test
describe('DiscountService', () => {
  it('should apply a 20% discount for premium users', () => {
    const mockUser = { id: 1, type: 'PREMIUM' };
    const price = 100;
    
    const finalPrice = DiscountService.calculate(mockUser, price);
    
    expect(finalPrice).toBe(80); // Runs in milliseconds
  });
});

A suite of 2,000 unit tests like this should run in under 60 seconds. If it takes longer, you are likely doing hidden I/O operations.

2. Contract Testing over Heavy Integration

When working with backend microservices, a common fear is that changing an API endpoint in Service A will break Service B. The instinctual response is to run massive integration tests that boot up multiple services at once.

Don’t do this in your pre-merge pipeline. Use Contract Testing instead (using tools like Pact).

Contract testing allows Service B (the consumer) to define a JSON file stating exactly what format it expects from Service A’s API. During Service A’s pipeline, it simply validates its code against this static contract file. It takes seconds, yet gives you the exact same confidence as a full integration test without spinning up a single extra server or relying on frontend E2E setups.

Phase 2: Post-Merge Validation (The Safety Net)

Once the code passes the 10-minute gatekeeper, it is merged into the trunk. Now, you can trigger the heavier, slower tests asynchronously. This runs in parallel or immediately after deployment to a staging environment.

1. Ephemeral Integration Testing

You do need to test real database interactions, but you should do it smart. Use short-lived, isolated environments. Tools like Docker and Testcontainers allow your pipeline to spin up a real PostgreSQL or Redis instance in a container, run database-dependent tests, and tear it down immediately.

Keep these tests focused purely on persistence logic—like verifying complex SQL queries or transaction rollbacks—rather than business logic.

2. Handling the “Flaky Test” Epidemic

Nothing destroys trust in an automated testing pipeline faster than a flaky test—a test that passes 9 times but fails on the 10th for no apparent reason (usually due to network timing, race conditions, or shared state in integration environments).

If a developer sees a pipeline fail, checks it, realizes it’s just “that one annoying flaky test again,” and hits Re-run, your testing culture is dying. Developers will start ignoring real failures.

You must enforce a strict Zero Tolerance Policy for Flakiness:

• Quarantine immediately: The moment a test shows flaky behavior, move it out of the main pipeline into a separate, non-blocking quarantine suite.
• Fix or delete: If a quarantined test isn’t fixed within a sprint, delete it. A non-existent test is better than a test that lies to your team.

Continuous Verification: Testing in Production

Even with a perfect pipeline, things will eventually go wrong. The ultimate evolution of a Trunk-Based Development testing strategy is recognizing that testing doesn’t stop when you deploy.

Since we use Feature Flags (as discussed in my last post), we can merge code to production completely hidden from users. This unlocks a powerful technique: Canary Deployments.

Instead of releasing a change to 100% of your traffic, route just 1% of real users to the new code. Your automated testing strategy here shifts from running test code to monitoring business metrics.

[Trunk Merge] 
     │
     ▼
[10-Min CI Pipeline Passes] 
     │
     ▼
[Deploy Hidden Behind Feature Flag] 
     │
     ▼
[Route 1% of Traffic (Canary)] ───► Monitor: HTTP 500s, Latency
     │
     ├─── Error Spikes? ───► Automatic Rollback (Flag Off)
     │
     └─── Stable? ─────────► Gradual Rollout to 100%

If your APM tool (like Datadog or New Relic) detects a sudden spike in HTTP 500 errors or a drop in checkout conversions for that 1% segment, the feature flag automatically flips off.

Production monitoring is the final, most reliable tier of your testing pyramid.

Conclusion: Speed Breeds Quality

Moving to Trunk-Based Development requires a massive shift in how you think about quality assurance. It requires moving away from heavy, slow, protective gates toward fast, automated, and resilient feedback loops.

If you focus on keeping your unit tests pure, replacing heavy integration tests with contract testing, ruthlessly quarantining flaky tests, and using production monitoring as your final safety net, you can easily hit that 10-minute pipeline goal.

When your pipeline is that fast, developers catch bugs while the code is still fresh in their minds. It makes development predictable, safe, and incredibly fast.

The post Automated Testing Strategies for Trunk-Based Development: How to Build a 10-Minute Pipeline appeared first on CodeCraft Diary.

This is the “code first, ask questions later” approach. And while it feels fast at the start, it’s exactly how we end up with legacy code that nobody dares to touch. It’s how “it works on my machine” turns into a 3:00 AM emergency production fix.

Test-Driven Development (TDD) flips this on its head. Instead of writing code to solve a problem and then writing tests to verify it, you write the test first. It sounds counterintuitive, but it’s a game-changer for maintainability. Let’s break it down into the cycle that actually defines professional software development: Red, Green, Refactor.

Previous article in this category: https://codecraftdiary.com/2026/06/01/flaky-tests-in-laravel/

The Cycle Explained: It’s a Rhythm, Not a Rule

The TDD process is a rhythmic loop that keeps you focused.

1. Red: You write a test for a tiny, specific piece of functionality that doesn’t exist yet. You run it. It should fail. If it passes immediately, your test is either broken or testing nothing.
2. Green: You write the absolute minimum amount of code to make that test pass. Not perfect code, not optimized code—just enough code.
3. Refactor: Now that you have a safety net, you clean up. You improve naming, extract methods, remove duplication, and optimize. Because you have the test, you can change the internals without breaking the contract.

The “Why”: Beyond Just Catching Bugs

Why go through the trouble? TDD is not just about catching bugs. It’s about design.

When you write the test first, you are forced to step into the shoes of the “consumer” of your code. You stop thinking about how a database table is structured and start thinking about how a controller or a service needs to interact with your business logic. If you find it hard to write a test, you’ve just received the most valuable feedback possible: your design is too complex or your coupling is too tight.

TDD acts as an early warning system for bad architecture.

A Real-World Example: Building a “Subscription System”

Let’s say we are building a subscription feature. We need to ensure that when a user subscribes, they receive a welcome email, and their status is updated in the database.

Phase 1: The Red Phase (The Requirement)

We start with a feature test. We are defining the behavior, not the implementation.

public function test_user_can_subscribe_to_a_plan()
{
    $user = User::factory()->create();
    
    $response = $this->actingAs($user)->post('/subscribe', [
        'plan_id' => 'premium_monthly'
    ]);

    $response->assertStatus(200);
    $this->assertDatabaseHas('subscriptions', [
        'user_id' => $user->id,
        'plan' => 'premium_monthly'
    ]);
}

public function test_user_can_subscribe_to_a_plan()
{
    $user = User::factory()->create();
    
    $response = $this->actingAs($user)->post('/subscribe', [
        'plan_id' => 'premium_monthly'
    ]);

    $response->assertStatus(200);
    $this->assertDatabaseHas('subscriptions', [
        'user_id' => $user->id,
        'plan' => 'premium_monthly'
    ]);
}

Running this results in a 404 or an error, because the route doesn’t exist. Red.

Phase 2: The Green Phase (The Implementation)

Now, we write just enough code to make this pass. We might put all the logic in the controller (yes, even if it’s dirty, because that’s the “Green” phase).

public function store(Request $request)
{
    Subscription::create([
        'user_id' => auth()->id(),
        'plan' => $request->plan_id
    ]);
    return response()->json(['status' => 'success'], 200);
}

public function store(Request $request)
{
    Subscription::create([
        'user_id' => auth()->id(),
        'plan' => $request->plan_id
    ]);
    return response()->json(['status' => 'success'], 200);
}

Test passes. Green.

Phase 3: The Refactor Phase (The Cleanup)

Now that the test is green, we look at the controller. It’s getting a bit crowded. We decide to move the logic into a SubscriptionService. We move the logic, run the test again—it still passes! We have total confidence that the refactoring didn’t break the core business requirement.

Deep Dive: Common Pitfalls

1. Over-Mocking

Developers often mock every single dependency, resulting in tests that pass even when the real system is broken. If you are mocking your entire application to test one controller, you aren’t testing reality. Use real database connections (via RefreshDatabase) and real events whenever possible.

2. Testing Implementation vs. Behavior

Don’t write tests that check if a private method was called or if a specific variable was set. Test the result. Did the user get the email? Did the database change? Does the UI show the right message? If you test the implementation, your tests will break every time you refactor, which defeats the whole purpose.

3. Avoiding the “Green” Trap

Sometimes, you write a test that is too big. You try to test the entire checkout flow in one test. When it fails, you don’t know why. Break it down. Test the validation of the payment, then the user status, then the email trigger. Small, focused tests are the secret to a high-speed suite.

The “Slow Down to Speed Up” Philosophy

The biggest pushback I hear is: “TDD takes twice as long.”

It feels like that at first. You are typing more code. You are thinking more. But think about the time you spend on:

• Manual debugging sessions in the browser.
• Writing “temporary” logging statements to trace data flow.
• Fear of deploying because you don’t know what might break.

With TDD, that “debugging” time disappears. You catch the logic error within three seconds of writing it. That is where the speed comes from. TDD isn’t about writing code faster; it’s about shipping with confidence because your test suite is your documentation.

Final Thoughts for 2026

Modern Laravel development is about clean, maintainable logic. If you want to survive a project that grows over several years, you cannot rely on memory or manual testing.

TDD isn’t a religion; it’s a discipline. Start today. Pick one small class or service. Write the test, watch it fail, and then write the code to fix it. Over time, it won’t feel like “work”—it will feel like having a second pair of eyes constantly reviewing your code as you type.

Happy coding.

The post Test-Driven Development in Laravel: The Red-Green-Refactor Loop appeared first on CodeCraft Diary.

This is the classic “Fat Controller” symptom. It makes your code fragile, nearly impossible to unit test, and violates the Single Responsibility Principle. But how do you solve this without introducing unnecessary enterprise-grade complexity? The answer lies in Event-Driven Architecture, kept simple and practical.

Previous article in this category: https://codecraftdiary.com/2026/05/25/state-pattern-vs-enums-in-modern-php/

The Hidden Cost of Tight Coupling

Consider a typical registration process in a Laravel application:

public function register(RegisterRequest $request)
{
    $user = User::create($request->validated());

    // Tightly coupled dependencies
    Mail::to($user)->send(new WelcomeEmail($user));
    Log::info('User registered: ' . $user->id);
    Analytics::track('user_signup', ['id' => $user->id]);
    Newsletter::subscribe($user->email);

    return response()->json(['message' => 'Success'], 201);
}

public function register(RegisterRequest $request)
{
    $user = User::create($request->validated());

    // Tightly coupled dependencies
    Mail::to($user)->send(new WelcomeEmail($user));
    Log::info('User registered: ' . $user->id);
    Analytics::track('user_signup', ['id' => $user->id]);
    Newsletter::subscribe($user->email);

    return response()->json(['message' => 'Success'], 201);
}

This code is intuitive, yet architecturally toxic. The controller is burdened with infrastructure knowledge. If your Newsletter API slows down, your user registration experiences lag. If the Mail service throws an exception, the entire request fails, potentially causing data inconsistency or frustration. You have created a brittle system where the success of a core operation depends on four secondary services.

The KISS Philosophy: Events and Listeners

The KISS (Keep It Simple, Stupid) principle dictates that we should avoid over-engineering. In Laravel, you don’t need a massive message broker like RabbitMQ or Kafka to achieve decoupling. Laravel’s built-in Event system is perfect for 95% of use cases.

Events act as an intermediary layer. Your controller simply broadcasts the fact that an action occurred, and various listeners react independently.

1. Defining the Event

Think of an event as a “data transfer object” that carries necessary context.

class UserRegistered
{
    public function __construct(public User $user) {}
}

class UserRegistered
{
    public function __construct(public User $user) {}
}

2. The Lean Controller

Now, look at how the controller looks after refactoring:

public function register(RegisterRequest $request)
{
    $user = User::create($request->validated());
    
    // Announce the action
    UserRegistered::dispatch($user);

    return response()->json(['message' => 'Success'], 201);
}

public function register(RegisterRequest $request)
{
    $user = User::create($request->validated());
    
    // Announce the action
    UserRegistered::dispatch($user);

    return response()->json(['message' => 'Success'], 201);
}

By decoupling, the controller is now focused solely on persistence and orchestration, not on the side effects.

3. Implementing Asynchronous Listeners

The true power of events in Laravel emerges when you utilize background processing. By implementing the ShouldQueue interface, you move the heavy lifting away from the HTTP request cycle.

class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event)
    {
        Mail::to($event->user)->send(new WelcomeEmail($event->user));
    }
}

class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event)
    {
        Mail::to($event->user)->send(new WelcomeEmail($event->user));
    }
}

Why This Architecture Scales

When you embrace events, you gain more than just cleaner controllers; you gain system resilience:

1. Fault Tolerance: If your Newsletter service is temporarily unavailable, the listener can automatically retry the task without affecting the user’s registration.
2. Performance: The user receives a 201 response immediately, while secondary tasks (like analytics) run in the background.
3. Extensibility: Need to add a “Push Notification” when a user registers? Just create a new listener. You don’t need to touch the registration controller logic at all, which eliminates the risk of regression bugs.
4. Testing Contracts: You can now test the registration process by asserting that the UserRegistered event was fired, without needing to mock complex external mail or log services.

Sandbox Example

Theory is one thing, but code in action speaks louder. [Here you can see a live example] of what EventDispatcher looks like in an isolated environment and try out how easy it is to add a new listener without changing the core logic.

Try this sandbox example by yourself: https://onlinephp.io/c/1f7b2

Managing Complexity: The “Event Hell” Warning

While events are powerful, they are not a silver bullet. An excess of events—or “Event Hell”—can lead to a “spaghetti” flow where the execution path is impossible to track.

Follow these best practices to maintain sanity:

• Don’t Over-Abstract: If a piece of code is used only in one place and will never change, don’t create an event. A simple function call is more readable.
• Focus on Side Effects: Events are for post-processing. Do not use events for core logic that must happen synchronously for the application to function.
• Descriptive Naming: Use past-tense names (OrderPlaced, InvoiceGenerated). This clearly signifies that the action has already been successfully committed to the database.

Deep Dive: Events vs. Model Observers

A frequent question is: “When should I use Eloquent Observers instead of Events?”

Eloquent Observers are strictly tied to database lifecycle events (e.g., created, updated, deleted). They are excellent when the side effect is always tied to a database change. Events, however, are more abstract. They represent business domain actions. An event like UserLoggedIn or OrderShipped is much more meaningful than a generic updated observer. Choose Events for business intent; use Observers for low-level database consistency.

Handling Failures in Background Jobs

When you move to ShouldQueue, you must plan for failure. In Laravel, you can define how your listeners handle retries:

public $tries = 3;
public $backoff = 60; // Wait 60 seconds between retries

public $tries = 3;
public $backoff = 60; // Wait 60 seconds between retries

This ensures that temporary outages (like a flickering API connection) don’t result in lost data.

Final Thoughts

Refactoring to an event-driven design is not about making your code “fancy.” It is about durability. By insulating your core controllers from volatile external dependencies, you create a codebase that is easier to debug, faster to test, and significantly more adaptable to future requirements. Start small: identify one noisy side effect in your largest controller, and move it into a listener today. Your future self—and your servers—will thank you.

The post Beyond Fat Controllers: Mastering Event-Driven Decoupling in Laravel appeared first on CodeCraft Diary.