DEV Community: CodeCraft Diary

Merge Conflicts Are a Process Problem, Not a Git Problem

CodeCraft Diary — Tue, 28 Jul 2026 15:31:00 +0000

Most developers treat merge conflicts as a Git problem.

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.

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 Specification Pattern in Laravel: Refactoring Complex Business Rules

CodeCraft Diary — Tue, 14 Jul 2026 14:43:00 +0000

As our Laravel applications grow, we inevitably face a common architectural dilemma: where do we put complex business logic that dictates whether an entity meets certain criteria?

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:

The account must be active.
The user must have a verified email.
They must have made at least 5 orders in total.
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();

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();
}

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;
}

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');
            });
    }
}

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);
        }
    }
}

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'));
    }
}

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!']);
    }
}

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:

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.
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.
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));
}

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.

Testing Laravel Events and Listeners: Ensuring Reliable Asynchronous Workflows

CodeCraft Diary — Tue, 14 Jul 2026 13:48:00 +0000

In modern Laravel applications, events and listeners are the glue that holds our complex business logic together. They allow us to decouple our code, keeping controllers thin and services focused. However, as applications scale, this "decoupling" can become a testing nightmare.

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);
}

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);
}

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'
    ]);
}

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;
    });
}

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.

Automated Testing Strategies for Trunk-Based Development: How to Build a 10-Minute Pipeline Home Development Workflow & Best Practices

CodeCraft Diary — Tue, 30 Jun 2026 14:44:00 +0000

If you’ve been following my recent posts, you already know I am a big fan of Trunk-Based Development (TBD), tiny pull requests, and deploying to production multiple times a day using feature flags. It sounds like an engineering dream: no long-lived branches, no merge hell on Friday afternoons, and features reaching users in hours instead of months.

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.

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
  });
});

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.

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.

Test-Driven Development in Laravel: The Red-Green-Refactor Loop

CodeCraft Diary — Tue, 23 Jun 2026 14:00:00 +0000

We’ve all been there. You have a new feature to build. You open your IDE, create a Controller, start wiring up the logic, maybe add some validation, and then, hours later, you finally write a test to make sure it actually works. Or, if we’re being honest, maybe you don’t write the test at all.

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.

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.
Green: You write the absolute minimum amount of code to make that test pass. Not perfect code, not optimized code—just enough code.
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'
    ]);
}

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);
}

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.

Beyond Fat Controllers: Mastering Event-Driven Decoupling in Laravel

CodeCraft Diary — Thu, 18 Jun 2026 18:07:00 +0000

As your Laravel application scales, your controllers often evolve into a "dumping ground" for business logic. You start with a straightforward registration flow, and before you know it, you are juggling email notifications, Slack alerts, audit logging, and third-party API calls—all packed into a single method.

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);
}

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 incons

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) {}
}

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);
}

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));
    }
}

Why This Architecture Scales

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

Fault Tolerance: If your Newsletter service is temporarily unavailable, the listener can automatically retry the task without affecting the user's registration.
Performance: The user receives a 201 response immediately, while secondary tasks (like analytics) run in the background.
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.
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

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.

How to Deploy 10 Times a Day Safely with Feature Flags

CodeCraft Diary — Tue, 09 Jun 2026 21:00:00 +0000

If you’ve been following my previous posts, you know I’m a big advocate for Trunk-Based Development and shrinking your pull requests until they almost feel too small. In a perfect world, developers merge code directly into the main branch multiple times a day, everything flows smoothly, and production remains rock solid.

But let’s be honest. When you actually try to pitch this to a backend team working on a core system, you almost always hit the exact same wall of resistance.

Someone in the back of the room will inevitably raise their hand and ask: “That sounds great in theory, but I’m currently refactoring our legacy checkout service. It’s going to take me four days of deep architectural changes. Are you seriously telling me I should merge half-baked, broken code into the main trunk and push it straight to production where real customers are buying our products?”

It’s a completely valid objection. If your only tool for hiding uncompleted work is holding onto a massive, long-lived feature branch, then trunk-based development breaks down immediately. You end up with the exact nightmare we talked about earlier: huge code reviews, painful merge conflicts, and code that rots before it ever sees a live environment.

To make continuous delivery actually work without causing catastrophic production outages every single afternoon, you need to decouple two concepts that most engineering teams mistakenly treat as the exact same thing: Deployment and Release.

Last article in this category is focused on Trunk-Based Development: https://codecraftdiary.com/2026/05/18/trunk-based-development-roadmap/

The Core Concept: Shifting Left by Decoupling

In traditional development setups, deploying code and releasing a feature happen simultaneously. You merge your giant feature branch, the CI/CD pipeline runs, the code hits the live servers, and boom—your users immediately see the new functionality.

This model is incredibly high-stakes. If something goes wrong, your only options are rolling back the entire deployment (which might contain unrelated fixes from other developers) or rushing a frantic hotfix through the pipeline while customer support tickets pile up and management starts breathing down your neck.

Feature flags (or feature toggles) completely change this dynamic by shifting the risk layout.

Deployment means moving bits to servers. Your code lives in the production environment, executing safely under the hood, but it remains invisible or inaccessible to the end user. It’s a technical activity.
Release means making that code active for users. It’s a business decision, completely independent of the deployment schedule.

By wrapping your new code inside a simple conditional statement, you can safely deploy unfinished logic to production ten times a day. The code is physically there on your production servers, but the execution path is dormant. You’ve successfully removed the stress from the deployment process.

A Realistic Look at the Code

Let’s skip the over-engineered enterprise frameworks for a moment and look at how this actually plays out in a standard backend context. Imagine you are upgrading a legacy payment gateway integration to a new, more reliable third-party API provider.

Instead of waiting weeks to swap the entire implementation out in one massive, terrifying PR, you introduce a flag. In its simplest form, it looks something like this:

public class PaymentProcessor {
    private final NewPaymentGateway newGateway;
    private final LegacyPaymentGateway legacyGateway;
    private final FeatureFlagClient flagClient;

    public void processPayment(Order order) {
        try {
            if (flagClient.isFeatureEnabled("use-new-payment-gateway", order.getUserId())) {
                newGateway.charge(order);
            } else {
                legacyGateway.charge(order);
            }
        } catch (Exception e) {
            // Fallback safety net
            if (flagClient.isFeatureEnabled("use-new-payment-gateway", order.getUserId())) {
                logger.warn("New gateway failed, falling back to legacy for user: " + order.getUserId(), e);
                legacyGateway.charge(order);
            } else {
                throw e;
            }
        }
    }
}

Notice that we aren’t just checking a global true/false boolean config value. We are passing the order.getUserId() into the flag client. This allows for runtime evaluation based on context.

With this setup, you can merge your new gateway code when it’s only 20% finished. The interface is there, the basic structure is set, but the flag is turned off for everyone in production. You get to test your integration continuously against real staging environments or hidden production paths without risking a single actual customer transaction.

The Database Problem: Handling Migrations Safely

One common argument against frequent deployments with feature flags is: “What about database changes? You can’t just feature-flag a schema migration.” This is where many teams stumble. If your code depends on a new database column that doesn’t exist yet, your application will crash. To solve this, your database strategy must evolve alongside your code isolation. You have to follow the Expand and Contract pattern.

Instead of renaming or modifying a column in a single destructive step, you break the change down into multiple backward-compatible deployments:

Expand: You deploy a migration that adds the new column or table. The old code doesn’t know it exists, so nothing breaks.
Dual Write: You deploy a feature flag that starts writing data to both the old and new columns simultaneously, but still reads only from the old one. This ensures your new schema populates with live data.
Backfill: You run a background script to copy historical data from the old structure to the new one.
Flip the Switch: You change the feature flag to read from the new column. If performance degrades, you slide the flag back instantly.
Contract: Once you are 100% confident, you remove the feature flag, delete the old code path, and deploy a final migration to drop the old column.

Yes, it requires more steps. But it transforms a terrifying database migration into a series of boring, completely safe tasks.

Moving Beyond Simple Booleans: Dark Launching and Canaries

Once you separate deployment from release, you unlock deployment workflows that make standard staging environments look completely obsolete. The most powerful of these is the Canary Release (or gradual rollout).

Instead of flipping a switch and hoping your database doesn’t melt under a new query load, you can configure your feature flag system to evaluate based on percentages or specific user attributes. A realistic rollout plan for our new payment gateway looks like this:

Phase 1: Internal Testing (The QA Tier)

The flag is enabled only for internal QA team user IDs or specifically whitelisted corporate IP addresses. You are running tests on the live production infrastructure, using real database connections, but nobody outside your company knows about it.

Phase 2: The Canary (1% Traffic)

You route exactly 1% of random global traffic through the new gateway. You sit back and monitor your logging dashboard for an hour. You look for spikes in 500 errors, increased latency, or unusual database connection pool exhaustion. If 1% of your users experience a bug, it’s a minor issue you can catch quickly, rather than a company-wide outage affecting everyone.

Phase 3: The Ramp-Up (10% -> 50%)

If the metrics look clean after 24 hours, you scale the flag to 10%, then 50% over the next two days. This gradual increase helps you see how the system behaves under a realistic load.

Phase 4: Full Release (100%)

The feature is stable, metrics are perfect, and the old legacy gateway is officially ready for decommissioning.

If a subtle edge-case bug appears when you hit the 10% mark, you don’t panic. You don’t trigger a full rollback of the service container, which might take 15 minutes to compile and deploy. You simply log into your feature flag dashboard, slide the toggle back to 0%, and fix the bug at your own pace during normal working hours.

The Dark Side: Managing the Architecture Debt

If you talk to any backend engineer who has used feature flags in a messy, fast-moving project, they will warn you about the exact same thing: technical debt. It is incredibly easy to treat feature flags like a magic wand, scattering them everywhere until your codebase looks like a tangled bowl of conditional spaghetti.

If a flag stays in your code for six months after a feature has rolled out to 100% of users, it stops being a tool for continuous delivery and becomes an architectural liability. It makes the code harder to read, complicates unit testing because you have to mock multiple flag states, and leaves dead code paths hanging around indefinitely.

To prevent your system from turning into an unmaintainable maze, you need to establish strict engineering discipline around the lifecycle of a flag.

Treat Toggles as Temporary Scaffolding

Every time you create a feature flag, you should immediately create a corresponding ticket in your backlog to remove that flag. The definition of done for a new feature shouldn’t just be “it works in production.” It must be “it works in production, the old legacy code is deleted, and the flag conditional is completely stripped out of the codebase.”

Flag Owner Assignment

Every flag must have a clear owner—either a specific developer or a product team. If a flag sits unchanged for more than four weeks, the automated system or team lead should trigger a warning to review its status.

Keep Them Short-Lived

Release toggles should rarely live longer than a single development sprint or two. If a flag has been at 100% for more than a few days without complaints, it’s time to schedule a quick cleanup PR. Don’t let them turn into permanent configuration settings.

Choosing Your Tools Safely

You don’t need to build a massive, complex internal configuration platform from scratch to get started. For smaller teams, a simple, centralized database table or a Redis-backed configuration file that reloads dynamically can be enough to get your feet wet.

As your team expands and you need advanced targeting rules, percentage rollouts, and audit logs, looking at dedicated tools like LaunchDarkly, Flagsmith, or open-source solutions like Unleash becomes highly valuable.

The critical architectural requirement is that evaluating a flag must be lightning-fast. It cannot introduce a blocking HTTP request into your critical backend path every time a function is called; it needs to resolve locally in memory via cached flag states that sync asynchronously in the background.

Final Thoughts

Transitioning to a workflow where you deploy to production ten times a day isn’t an engineering flex—it’s about reducing anxiety. It changes the entire culture of a development team. Production deployments stop being high-stress, late-night events that require everyone to be on standby with their laptops open. They become boring, routine non-events that happen continuously in the background while you grab a coffee or focus on your next task.

Feature flags are the missing link that makes this possible. They give you the safety net to keep your pull requests tiny, your main branch green, and your delivery pipeline moving forward without ever breaking the user experience.

Flaky Tests in Laravel: Why Your CI Randomly Fails

CodeCraft Diary — Sun, 07 Jun 2026 17:37:00 +0000

Your test suite passes locally.
CI fails.

You rerun the pipeline.
Now everything is green.

You change absolutely nothing.
An hour later, another random failure appears.

If this sounds familiar, you are probably dealing with flaky tests.

Flaky tests are tests that sometimes pass and sometimes fail without any meaningful code changes. They are one of the most frustrating problems in modern software development because they slowly destroy trust in your test suite.

And once developers stop trusting tests, they start ignoring failures, rerunning pipelines blindly, and eventually shipping bugs to production.

After dealing with flaky tests in multiple Laravel projects, I noticed something important:

Most flaky tests are not caused by PHPUnit itself.

They are usually caused by hidden shared state, timing assumptions, asynchronous behavior, or infrastructure leaking between tests.

In this article, I’ll show the most common causes of flaky tests in Laravel and how to fix them properly.

Previous article in Testing category: https://codecraftdiary.com/2026/05/09/how-mutation-testing-exposes-the-truth-php-2026-edition/

What Makes a Test “Flaky”?

A flaky test has three characteristics:

It fails inconsistently
The failure is difficult to reproduce
Rerunning the test often “fixes” it

This is different from a normal failing test.

A normal failing test indicates a deterministic bug.

A flaky test creates uncertainty.

And uncertainty is dangerous in CI pipelines because developers eventually stop taking failures seriously.

1. Time-Dependent Tests

One of the most common sources of flaky tests is time.

Laravel makes working with time easy through Carbon, but time-based logic can easily become unstable.

Consider this example:

public function test_subscription_expires_after_24_hours(): void
{
    $subscription = Subscription::factory()->create([
        'expires_at' => now()->addDay(),
    ]);

    sleep(1);

    $this->assertFalse($subscription->isExpired());
}

This test may pass most of the time.

But depending on:

CI speed
server load
execution timing
timezone handling

it can eventually fail unpredictably.

The fix is simple:

Use fixed time.

Carbon::setTestNow('2026-05-28 10:00:00');

$subscription = Subscription::factory()->create([
    'expires_at' => now()->addDay(),
]);

$this->assertFalse($subscription->isExpired());

And always clean up afterwards:

Carbon::setTestNow();

Without cleanup, fake time can leak into other tests and create even more randomness.

2. Shared Database State

Another massive source of flaky tests is database leakage between tests.

I still see projects where tests depend on records created by previous tests.

Example:

public function test_user_can_create_post(): void
{
    $this->post('/posts', [
        'title' => 'Example',
    ]);

    $this->assertDatabaseCount('posts', 1);
}

At first, this looks harmless. However, once another test inserts posts into the database, the count may suddenly become 2, 5, or even 12.

The fix is proper database isolation.

In Laravel, this usually means:

use RefreshDatabase;

or:

use DatabaseTransactions;

depending on your architecture.

I already wrote an entire article comparing these approaches because using the wrong one can create hidden instability.

The important part is this:

Tests should never depend on leftovers from previous tests.

Ever.

3. Random Factories

Factories are great.

Randomness is not.

This test looks innocent:

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

$this->assertEquals('admin', $user->role);

But if the factory generates random roles, this test becomes unstable immediately.

I’ve seen this problem especially in large Laravel projects where factories evolved over years and slowly accumulated randomness everywhere.

Instead, explicitly define required state:

$user = User::factory()->create([
    'role' => 'admin',
]);

Deterministic data creates deterministic tests.

4. Queue and Async Problems

Queues are one of the biggest sources of flaky behavior.

Especially when developers partially fake queues while still allowing some jobs to execute asynchronously.

Example:

Queue::fake();

dispatch(new SendInvoiceJob($invoice));

$this->assertDatabaseHas('invoices', [
    'status' => 'sent',
]);

This can fail because the queued job never actually runs.

Or worse:
it runs sometimes depending on environment configuration.

Another common issue is testing behavior immediately after dispatching async jobs.

Example:

dispatch(new SyncProductsJob());

$this->assertDatabaseCount('products', 500);

The assertion may execute before the worker finishes.

Locally it passes.

In CI it randomly fails.

A better approach is either:

testing the dispatch itself,
or running jobs synchronously during tests.

Example:

Bus::fake();

dispatch(new SyncProductsJob());

Bus::assertDispatched(SyncProductsJob::class);

Or:

config()->set('queue.default', 'sync');

during the test environment.

5. Parallel Testing Issues

Parallel testing speeds up CI dramatically.

But it also exposes hidden shared state.

I’ve seen failures caused by:

shared Redis keys
shared files
cached config
temporary directories
static variables
singleton state

Example:

Storage::disk('local')->put('report.pdf', 'content');

If multiple tests write the same file simultaneously, random failures appear.

The fix is isolation.

Example:

Storage::fake();

or unique filenames:

$file = Str::uuid() . '.pdf';

Parallel testing does not create flaky tests.

It reveals problems that already existed.

6. External APIs

Real HTTP calls inside tests are dangerous.

Sometimes the API is slow.

Sometimes rate limits trigger.

Sometimes sandbox environments fail.

And suddenly your test suite becomes unreliable for reasons completely outside your application.

This is why external APIs should usually be mocked or faked.

Laravel provides excellent HTTP faking:

Http::fake([
    '*' => Http::response([
        'success' => true,
    ], 200),
]);

Now your tests become:

faster
deterministic
independent from network stability

I covered this topic in more detail in my API mocking article because external integrations are one of the easiest ways to accidentally create unstable tests.

7. Tests That Depend on Execution Order

This one is extremely dangerous.

A test passes only because another test ran before it.

Example:

public function test_admin_exists(): void
{
    $this->assertDatabaseHas('users', [
        'email' => 'admin@example.com',
    ]);
}

This silently depends on another test creating the admin user first.

Run tests individually and this suddenly fails.

A good test should work:

independently
repeatedly
in any order

If execution order matters, the suite is fragile.

Why Flaky Tests Become Expensive

The biggest problem with flaky tests is not technical.

It is psychological.

Once developers stop trusting CI:

failures get ignored
reruns become normal
real bugs get missed
confidence disappears

I’ve seen teams where developers reran pipelines three or four times automatically because “CI is always flaky anyway.”

That is dangerous.

Because eventually a real regression hides inside the noise.

Final Thoughts

Flaky tests are rarely random.

There is almost always an underlying engineering problem:

shared state
uncontrolled time
async behavior
non-isolated infrastructure
hidden dependencies

The solution is not “rerun CI.”

The solution is making tests deterministic.

A reliable test suite should produce the same result every time:

locally
in CI
on every machine
under every execution order

Once your tests become deterministic, your entire development workflow becomes faster, safer, and dramatically less frustrating.

How to Deploy 10 Times a Day Safely with Feature Flags

CodeCraft Diary — Sun, 07 Jun 2026 15:49:08 +0000

But let’s be honest. When you actually try to pitch this to a backend team working on a core system, you almost always hit the exact same wall of resistance.

Last article in this category is focused on Trunk-Based Development: https://codecraftdiary.com/2026/05/18/trunk-based-development-roadmap/

The Core Concept: Shifting Left by Decoupling

Feature flags (or feature toggles) completely change this dynamic by shifting the risk layout.

Deployment means moving bits to servers. Your code lives in the production environment, executing safely under the hood, but it remains invisible or inaccessible to the end user. It’s a technical activity.
Release means making that code active for users. It’s a business decision, completely independent of the deployment schedule.

A Realistic Look at the Code

Instead of waiting weeks to swap the entire implementation out in one massive, terrifying PR, you introduce a flag. In its simplest form, it looks something like this:

public class PaymentProcessor {
    private final NewPaymentGateway newGateway;
    private final LegacyPaymentGateway legacyGateway;
    private final FeatureFlagClient flagClient;

    public void processPayment(Order order) {
        try {
            if (flagClient.isFeatureEnabled("use-new-payment-gateway", order.getUserId())) {
                newGateway.charge(order);
            } else {
                legacyGateway.charge(order);
            }
        } catch (Exception e) {
            // Fallback safety net
            if (flagClient.isFeatureEnabled("use-new-payment-gateway", order.getUserId())) {
                logger.warn("New gateway failed, falling back to legacy for user: " + order.getUserId(), e);
                legacyGateway.charge(order);
            } else {
                throw e;
            }
        }
    }
}

Notice that we aren't just checking a global true/false boolean config value. We are passing the order.getUserId() into the flag client. This allows for runtime evaluation based on context.

The Database Problem: Handling Migrations Safely

One common argument against frequent deployments with feature flags is: “What about database changes? You can’t just feature-flag a schema migration.” This is where many teams stumble. If your code depends on a new database column that doesn't exist yet, your application will crash. To solve this, your database strategy must evolve alongside your code isolation. You have to follow the Expand and Contract pattern.

Instead of renaming or modifying a column in a single destructive step, you break the change down into multiple backward-compatible deployments:

Expand: You deploy a migration that adds the new column or table. The old code doesn't know it exists, so nothing breaks.
Dual Write: You deploy a feature flag that starts writing data to both the old and new columns simultaneously, but still reads only from the old one. This ensures your new schema populates with live data.
Backfill: You run a background script to copy historical data from the old structure to the new one.
Flip the Switch: You change the feature flag to read from the new column. If performance degrades, you slide the flag back instantly.
Contract: Once you are 100% confident, you remove the feature flag, delete the old code path, and deploy a final migration to drop the old column.

Yes, it requires more steps. But it transforms a terrifying database migration into a series of boring, completely safe tasks.

Moving Beyond Simple Booleans: Dark Launching and Canaries

Instead of flipping a switch and hoping your database doesn't melt under a new query load, you can configure your feature flag system to evaluate based on percentages or specific user attributes. A realistic rollout plan for our new payment gateway looks like this:

Phase 1: Internal Testing (The QA Tier)
The flag is enabled only for internal QA team user IDs or specifically whitelisted corporate IP addresses. You are running tests on the live production infrastructure, using real database connections, but nobody outside your company knows about it.

Phase 2: The Canary (1% Traffic)
You route exactly 1% of random global traffic through the new gateway. You sit back and monitor your logging dashboard for an hour. You look for spikes in 500 errors, increased latency, or unusual database connection pool exhaustion. If 1% of your users experience a bug, it’s a minor issue you can catch quickly, rather than a company-wide outage affecting everyone.

Phase 3: The Ramp-Up (10% -> 50%)
If the metrics look clean after 24 hours, you scale the flag to 10%, then 50% over the next two days. This gradual increase helps you see how the system behaves under a realistic load.

Phase 4: Full Release (100%)
The feature is stable, metrics are perfect, and the old legacy gateway is officially ready for decommissioning.

The Dark Side: Managing the Architecture Debt

To prevent your system from turning into an unmaintainable maze, you need to establish strict engineering discipline around the lifecycle of a flag.

Treat Toggles as Temporary Scaffolding

Every time you create a feature flag, you should immediately create a corresponding ticket in your backlog to remove that flag. The definition of done for a new feature shouldn't just be "it works in production." It must be "it works in production, the old legacy code is deleted, and the flag conditional is completely stripped out of the codebase."

Flag Owner Assignment

Keep Them Short-Lived

Choosing Your Tools Safely

You don't need to build a massive, complex internal configuration platform from scratch to get started. For smaller teams, a simple, centralized database table or a Redis-backed configuration file that reloads dynamically can be enough to get your feet wet.

Final Thoughts

State Pattern vs. Enums in Modern PHP

CodeCraft Diary — Tue, 26 May 2026 15:06:00 +0000

In many PHP and Laravel applications, entity lifecycles start simple. An Order can be:

Pending
Paid
Shipped
Cancelled

When PHP introduced native Enums, they became the perfect fit for this kind of state modeling. They are type-safe, database-friendly, and much cleaner than arbitrary strings spread across the codebase.

For simple workflows, Enums are often exactly the right solution. The problem begins when states stop being just labels and start accumulating behavior.

This article explores where Enums work well, where they start breaking down, and how the State Pattern can help without introducing unnecessary complexity or framework-heavy abstractions.

Previous articlet in Refactoring cattegory: https://codecraftdiary.com/2026/05/02/mastering-value-objects-in-php/

Enums Are Excellent — Until They Aren’t

For simple workflows, Enums are clean and maintainable.

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';
}

This is ideal when states are primarily used for:

Filtering and querying data
Display logic and badges in UI
Basic validation
API serialization
Database persistence

Problems start appearing when business rules become state-dependent. A common first step is adding helper methods directly into the Enum:

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function canBeCancelled(): bool
    {
        return match($this) {
            self::Pending, self::Paid => true,
            self::Shipped, self::Cancelled => false,
        };
    }
}

This is still perfectly reasonable and respects the KISS principle.

But over time, workflows tend to evolve. A cancellation process may eventually require refunding payments, restocking inventory, notifying external systems, creating audit logs, or dispatching events.

At that point, the Enum slowly stops being a simple value object and starts becoming a workflow engine.

The Hidden Problem: Growing Coupling

Consider how a bloating Enum typically looks in production:

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function cancel(
        Order $order,
        PaymentGateway $gateway,
        InventoryManager $inventory
    ): void {
        match ($this) {
            self::Pending => $order->updateStatus(self::Cancelled),

            self::Paid => $this->executeCancellationWithRefund($order, $gateway, $inventory),

            self::Shipped => throw new LogicException('Cannot cancel a shipped order.'),
            self::Cancelled => throw new LogicException('Order is already cancelled.'),
        };
    }

    private function executeCancellationWithRefund(Order $order, PaymentGateway $gateway, InventoryManager $inventory): void
    {
        $gateway->refund($order->payment_id);
        $inventory->restock($order->items);
        $order->updateStatus(self::Cancelled);
    }
}

The issue here is not the number of lines. The issue is coupling.

The Enum now knows about payment infrastructure, inventory management, business transitions, and side effects. Adding a new state such as PartiallyRefunded now requires modifying a growing conditional structure that centralizes unrelated responsibilities.

This is where applications experience state explosion—the point where transitions and side effects become increasingly difficult to isolate and reason about. At this stage, the code may still look “short,” but it is no longer simple.

The State Pattern: Isolating Behavior

The State Pattern addresses this by moving behavior into dedicated state objects. Instead of one large conditional structure, each state becomes responsible for its own transitions and rules.

1. Define the Workflow Contract

interface OrderState
{
    public function cancel(Order $order): void;
    public function ship(Order $order): void;
    public function toValue(): string;
}

The interface should stay minimal. Only include operations whose behavior actually changes depending on the state.

2. Create Small, Focused State Classes
Each state becomes an isolated, testable component. Look at how clean the responsibilities become:

Pending State

readonly class PendingState implements OrderState
{
    public function cancel(Order $order): void
    {
        $order->transitionTo(new CancelledState());
    }

    public function ship(Order $order): void
    {
        throw new LogicException('Cannot ship an unpaid order.');
    }

    public function toValue(): string
    {
        return 'pending';
    }
}

Paid State

readonly class PaidState implements OrderState
{
    public function __construct(
        private PaymentGateway $gateway,
        private InventoryManager $inventory,
    ) {}

    public function cancel(Order $order): void
    {
        $this->gateway->refund($order->payment_id);
        $this->inventory->restock($order->items);

        $order->transitionTo(new CancelledState());
    }

    public function ship(Order $order): void
    {
        $order->transitionTo(new ShippedState());
    }

    public function toValue(): string
    {
        return 'paid';
    }
}

Shipped State

readonly class ShippedState implements OrderState
{
    public function cancel(Order $order): void
    {
        throw new LogicException('The order has already been shipped.');
    }

    public function ship(Order $order): void
    {
        throw new LogicException('Order is already shipped.');
    }

    public function toValue(): string
    {
        return 'shipped';
    }
}

Most importantly, adding a new state no longer requires modifying a massive conditional block. This aligns naturally with the Open/Closed Principle.

3. A Pragmatic Hybrid Approach

Completely replacing Enums with raw state objects is often unnecessary in database-driven applications. In practice, the most maintainable approach is a hybrid architecture:

Enums handle persistence, transport, and API serialization.
State objects handle business behavior and side effects.

The Enum remains the canonical storage format:

enum OrderStatusEnum: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';
}

Resolving State Behavior Cleanly

Instead of resolving dependencies directly inside the model, a dedicated factory keeps infrastructure concerns isolated from your domain.

readonly class OrderStateFactory
{
    public function __construct(
        private PaymentGateway $gateway,
        private InventoryManager $inventory,
    ) {}

    public function make(OrderStatusEnum $status): OrderState
    {
        return match ($status) {
            OrderStatusEnum::Pending => new PendingState(),
            OrderStatusEnum::Paid => new PaidState($this->gateway, $this->inventory),
            OrderStatusEnum::Shipped => new ShippedState(),
            OrderStatusEnum::Cancelled => new CancelledState(),
        };
    }
}

Keeping the Model Lightweight

Now, the Order model stays clean and decoupled from infrastructure services. It simply orchestrates the workflow via the factory:

class Order
{
    public OrderStatusEnum $status;
    public int $payment_id;
    public array $items = [];

    public function __construct(
        private readonly OrderStateFactory $stateFactory,
    ) {}

    public function transitionTo(OrderState $state): void
    {
        $this->status = OrderStatusEnum::from($state->toValue());
    }

    public function cancel(): void
    {
        $this->stateFactory
            ->make($this->status)
            ->cancel($this);
    }

    public function ship(): void
    {
        $this->stateFactory
            ->make($this->status)
            ->ship($this);
    }
}

This keeps your persistence simple, business logic isolated, dependencies explicit, and workflows extensible—all without introducing heavy framework abstractions.

Testing Becomes Significantly Easier

One of the biggest advantages of state objects is test isolation. Instead of testing a large Enum with multiple branches and heavy mocking setups, each workflow state can be verified independently:

PendingStateTest — Verify that cancellation transitions directly to cancelled.
PaidStateTest — Assert that the payment gateway receives the refund call and inventory is restocked.
ShippedStateTest — Assert that exceptions are thrown correctly on forbidden actions.

This dramatically reduces test setup complexity and makes transition rules much easier to verify.

When Should You Use Enums vs. State Objects?

Use Enums when:

The state is primarily a static label.
Transitions are simple and linear.
Behavior differences between states are minimal.
No external services or infrastructure are involved.
Examples: Blog post status (Draft, Published), user visibility flags, or filtering categories.

Use the State Pattern when:

Transitions trigger side effects or external APIs.
States require completely different validation rules.
Workflows keep expanding with new edge cases.
Conditional logic (match or if/else) around the same state starts repeating across the codebase.
Examples: Payment workflows, fulfillment systems, subscription lifecycles, or approval pipelines.

Final Thoughts

Enums are not the enemy. In fact, they are often the best solution for simple state representation.

The real problem starts when business workflows evolve and a single Enum begins accumulating infrastructure dependencies, transition orchestration, side effects, and validation logic. At that point, the issue is no longer code length—it is responsibility density.

The State Pattern is valuable not because it is “more advanced,” but because it isolates change. And in long-lived systems, isolated change is usually what keeps complexity manageable.

Trunk-Based Development: From Chaos to Flow

CodeCraft Diary — Tue, 19 May 2026 14:16:00 +0000

If you’ve followed the first two parts of this series, you know the hard truth: most teams aren’t actually doing Trunk-Based Development. They are doing “Short-lived Feature Branching” with better branding. We’ve talked about why your PRs are still too big and why the 6-month pull request is a parallel universe that kills delivery.

But how do you actually fix it? Knowing small PRs are better is easy. Changing a team’s habits is the hard part.
This is the practical roadmap for moving from long-lived branches to real trunk-based flow.

Previous posts about Trunk-Based Development: Pt. 2 — https://codecraftdiary.com/2026/04/29/trunk-based-development-your-pull-requests-are-still-too-big/

Pt. 1 https://codecraftdiary.com/2026/04/04/trunk-based-development-why-most-teams-think-they-use-it-but-dont/

Phase 1: Fixing the Foundation (The Infrastructure)

You cannot do trunk-based development with slow pipelines. If your CI/CD suite is a bottleneck, your developers will naturally revert to batching work to “save time”.

1. The 10-Minute Rule for CI

In 2026, speed is a requirement, not a luxury. If your CI takes 20 minutes, there is friction; if it takes 60 minutes, people stop merging frequently.

Target: Aim for CI under 10 minutes.
Action: Parallelize your test suites. If a test is flaky, don’t ignore it — fix it or delete it. A flaky test suite is a debt that destroys the confidence needed for frequent merges.

2. Radical Observability

To merge to main multiple times a day safely, you need to know exactly what is happening in production.

Action: Implement real-time logging and alerting. If you merge a small change and the error rate spikes, you should know within seconds, not after a customer support ticket arrives.

Phase 2: Mastering the Tools of “Incomplete” Work

The biggest fear in TBD is merging work that isn’t “done”. To overcome this, you must decouple deployment from release.

3. Feature Flags as a Standard
Feature flags are the missing piece for most teams. They allow you to merge partial work and control exposure without waiting for the entire feature to be polished.

The Strategy: Wrap new logic in a toggle. This lets the code live in the main branch, deployed to production but hidden from users until it’s ready.

The Rule: A feature flag must exist from the start, not as an afterthought.

4. Branch by Abstraction for Large Changes
When you are doing a complete architectural overhaul, do not create a “v2-architecture” Git branch. That is a recipe for a merge nightmare.

The Strategy: Keep both the old and new architectures in the main branch simultaneously.

The Execution: Use an abstraction layer (an interface or wrapper) to toggle between the old and new logic. Run “dark launches” where the new code executes, but you ignore the results or simply compare them against the old version to gain confidence.

Phase 3: Rewiring the Process (Small PRs)

Small pull requests are the backbone of TBD. A large PR is a cognitive nightmare that leads to shallow reviews and delayed deployments.

5. Enforce Hard PR Size Limits
Don’t make small PRs a suggestion; make them a constraint.

The Rule: Set a soft limit of ~300 lines and a hard limit of ~400–500 lines per PR.

The Logic: Constraints force better behavior. If a task is too big, it forces the developer to think about how to slice it vertically.

6. Vertical vs. Horizontal Slicing
Stop splitting work by “Backend PR,” “Database PR,” and “Frontend PR”. This creates artificial dependencies and forces you to wait until all are done before merging.

The Strategy: Slice vertically. One PR should deliver a minimal end-to-end functionality (even if hidden by a flag), followed by another PR that extends that behavior.

Phase 4: The Cultural Shift (The Hard Part)

Trunk-based development is 10% tooling and 90% discipline.

7. Optimize for Review Speed, Not Just Quality

If reviews take days, developers will batch work to avoid the “waiting tax”.

Expectation: A PR should be reviewed within a few hours, not days.

Technique: If a PR is small (under 300 – 400 lines), it takes 15 minutes to review. If it’s still stuck, do live reviews or pair programming to clear the logjam.

8. Accept “Ugly but Correct”

Flow matters more than perfection.

The Mindset: It is better to merge a small, slightly imperfect (but safe) change today than a “perfect” massive change next week. You can refactor and improve incrementally once the code is integrated -> but don’t forget to refactor.

Phase 5: The Cleanup and AI Reality

AI-assisted coding is generating more code than ever. If you don’t have small changes and fast integration, your workflow will collapse under the sheer volume of AI-generated changes.

9. The Non-Optional Cleanup
Feature flags and abstractions are great, but they create technical debt if left forever.

The Rule: Once a rollout is 100% successful, deleting the old code and the flag is part of the original task, not a “nice-to-have” for later.

10. Track Your Behavior (Metrics)
Stop guessing if you are doing TBD. Measure it.

KPIs: Track average PR size, PR lifetime, and merges per developer per day.

Reality Check: If your PRs live for days and contain thousands of lines, you are still doing feature-branch development.

Common Failure Mode

Teams adopt feature flags but still keep long-lived branches.

That is not trunk-based development.

The branch lifetime matters more than the branching strategy itself.

Final Thought

Trunk-based development feels uncomfortable at first because it goes against the natural desire to be “complete” and “polished” before sharing work. It requires you to prioritize the system’s flow over your individual comfort.

If you fix just one thing this month, make your pull requests radically smaller. Faster reviews, fewer bugs, and smoother delivery will follow. Everything else is just details.

How Mutation Testing Exposes the Truth (PHP 2026 Edition)

CodeCraft Diary — Tue, 12 May 2026 13:50:00 +0000

You've got 85% code coverage. Your CI pipeline is green. You ship to production — and things break in ways your tests never caught. Sound familiar?

I've been there. And for a long time, I thought the answer was more tests. What I actually needed was better tests. That's exactly what mutation testing taught me, and after using Infection PHP in production projects through 2025 and into 2026, I can confidently say it changed how I think about test quality entirely.

Previous article in this category: https://codecraftdiary.com/2026/04/18/laravel-testing-mistakes/

The Dirty Secret of Code Coverage

Code coverage tells you which lines were executed during your test run. It says nothing about whether your assertions are actually meaningful.

Consider this classic trap:

<?php

class OrderDiscountCalculator
{
    public function calculate(float $price, int $quantity): float
    {
        if ($quantity >= 10) {
            return $price * 0.9;
        }

        return $price;
    }
}

And a test that covers it 100%:

<?php

use PHPUnit\Framework\TestCase;

class OrderDiscountCalculatorTest extends TestCase
{
    public function testCalculate(): void
    {
        $calculator = new OrderDiscountCalculator();

        // Both branches hit — 100% coverage!
        $calculator->calculate(100.0, 15);
        $calculator->calculate(100.0, 5);
    }
}

This test covers 100% of the code. It also asserts absolutely nothing. If someone changes 0.9 to 0.5, your test suite stays green while your customers get 50% off everything. That's a very expensive bug.

This is precisely the problem mutation testing solves.

What Is Mutation Testing?

Mutation testing works by automatically introducing small bugs — called mutants — into your source code, then running your test suite against each mutated version. If your tests catch the bug (the mutant is killed), great. If your tests still pass with the bug in place (the mutant survives), you have a gap.

Common mutations include things like:

Changing >= to > or <=
Replacing + with -
Flipping true to false
Removing entire return statements

The metric you care about is the Mutation Score Indicator (MSI) — the percentage of mutants your tests kill. A high MSI means your tests are genuinely sensitive to regressions.

Getting Started with Infection PHP

Infection is the de facto mutation testing framework for PHP. It integrates cleanly with PHPUnit and runs as a Composer dev dependency.

composer require --dev infection/infection

Run it for the first time with:

./vendor/bin/infection --threads=4

Infection will run your existing test suite, then start generating and testing mutants. On a modern project with --threads=4, it's fast enough to include in a CI pipeline.

A Real-World Example: Catching What Coverage Misses

Let me walk you through a scenario I actually encountered on a SaaS project — a pricing engine with tiered discounts.

<?php

class TieredPricingService
{
    private const TIERS = [
        100 => 0.70, // 30% discount for 100+
        50  => 0.80, // 20% discount for 50+
        10  => 0.90, // 10% discount for 10+
    ];

    public function getPrice(float $unitPrice, int $quantity): float
    {
        foreach (self::TIERS as $minQuantity => $multiplier) {
            if ($quantity >= $minQuantity) {
                return round($unitPrice * $multiplier * $quantity, 2);
            }
        }

        return round($unitPrice * $quantity, 2);
    }
}

My original tests covered all branches. PHPUnit reported 100% coverage. But when I ran Infection, it flagged a surviving mutant — it changed >= to > in the tier check, and my test for exactly 10 units didn't catch it because I only tested with 11. The boundary condition was untested.

Here's what the corrected test looked like after Infection exposed the gap:

<?php

use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\DataProvider;

class TieredPricingServiceTest extends TestCase
{
    private TieredPricingService $service;

    protected function setUp(): void
    {
        $this->service = new TieredPricingService();
    }

    #[DataProvider('pricingProvider')]
    public function testGetPrice(float $unitPrice, int $quantity, float $expected): void
    {
        $this->assertSame($expected, $this->service->getPrice($unitPrice, $quantity));
    }

    public static function pricingProvider(): array
    {
        return [
            'below first tier'         => [10.0, 5,   50.00],
            'exactly at 10 tier'       => [10.0, 10,  90.00],  // boundary — was missing!
            'above 10 tier'            => [10.0, 11,  99.00],
            'exactly at 50 tier'       => [10.0, 50,  400.00], // boundary
            'exactly at 100 tier'      => [10.0, 100, 700.00], // boundary
            'above highest tier'       => [10.0, 200, 1400.00],
        ];
    }
}

After adding boundary assertions, Infection's MSI jumped from 61% to 94%. That's the difference between a test suite that gives you false confidence and one that actually has your back.

Configuring Infection for Your Project

Infection is configured via infection.json5 in your project root. Here's a production-ready config I use:

{
    "$schema": "vendor/infection/infection/resources/schema.json",
    "source": {
        "directories": ["src"],
        "excludes": ["src/Infrastructure/Migrations"]
    },
    "mutators": {
        "@default": true
    },
    "testFramework": "phpunit",
    "testFrameworkOptions": "--testsuite=unit",
    "minMsi": 85,
    "minCoveredMsi": 90,
    "threads": 4,
    "logs": {
        "text": "var/log/infection.log",
        "html": "var/log/infection.html",
        "summary": "var/log/infection-summary.log"
    }
}

The minMsi and minCoveredMsi thresholds are important — they let your CI pipeline fail if mutation score drops below acceptable levels, the same way PHPUnit can fail below a coverage threshold.

Integrating Into CI (GitHub Actions)

Here's a GitHub Actions job I've been running since mid-2025:

mutation-testing:
  runs-on: ubuntu-latest
  needs: tests
  steps:
    - uses: actions/checkout@v4

    - name: Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.3'
        coverage: xdebug

    - name: Install dependencies
      run: composer install --no-interaction

    - name: Run Infection
      run: ./vendor/bin/infection --threads=4 --min-msi=85 --min-covered-msi=90

One important note: Infection requires a coverage driver (Xdebug or PCOV) to know which mutants are relevant to which tests. PCOV is faster for large codebases; Xdebug gives more detail. I use Xdebug locally and PCOV in CI.

Common Objections — And Honest Answers

"It's too slow." It can be on large codebases, but --threads and configuring source.excludes to skip generated code, migrations, and DTOs makes a huge difference. I typically exclude everything that has no business logic.

"The MSI is too low to be useful." Start with --min-msi=0 and just look at the HTML report. Prioritize killing mutants in your core domain logic first — that's where bugs actually hurt.

"It produces too many surviving mutants." Some mutants are genuinely equivalent (they don't change behavior). Infection lets you mark these as ignored in config. Over time your noise floor drops significantly.

What My Workflow Looks Like in 2026

My current approach on active PHP projects:

PHPUnit with strict coverage for the fast feedback loop during development.
Infection on every PR targeting only changed files — using --git-diff-filter (available since Infection 0.27) to keep CI times reasonable.
Full Infection run weekly on the main branch to catch gradual MSI drift.

The --git-diff-filter flag is a game-changer for larger repos — it only mutates code touched in the current diff, so mutation testing stays practical even on monorepos.

./vendor/bin/infection --git-diff-filter=AM --threads=8

Final Thoughts

Code coverage is a floor, not a ceiling. It tells you the minimum — which lines were touched. Mutation testing tells you something far more valuable: whether those lines are protected by tests that would actually catch a regression.

If you're publishing technical content in 2026 and you're not talking about mutation testing, you're leaving one of PHP's most powerful quality tools completely off the table. The tooling has matured, the CI integration is straightforward, and the payoff in confidence is real.

Start with a single service class. Run Infection. Look at what survives. I promise you'll find something surprising.

Resources: