DEV Community: CodeCraft Diary

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:

Mastering Value Objects in PHP 8.5+ (2026 Edition)

CodeCraft Diary — Tue, 05 May 2026 14:01:00 +0000

As developers, we often have a problematic relationship with primitives. We use a string for an email, a float for a price, and an int for a status. This is what we call Primitive Obsession—and it’s one of the common reasons why PHP codebases gradually become hard to maintain.

If you’ve been following my series on Refactoring & Patterns, you know I’m a fan of the Introduce Parameter Object pattern. But today, I want to go deeper and talk about one of the smallest, yet most powerful building blocks of clean architecture: ** Value Objects**.

Previous article in this category: https://codecraftdiary.com/2026/04/11/fat-controller-laravel-refactor/

The “Price” of Primitive Obsession

Imagine you’re working on an e-commerce platform. You have a Product and a Discount.

public function applyDiscount(float $price, float $discountPercentage): float
{
    if ($discountPercentage < 0 || $discountPercentage > 100) {
        throw new InvalidArgumentException("Invalid discount");
    }

    return $price - ($price * ($discountPercentage / 100));
}

At first glance, this looks fine. But in a real-world application, that $price is floating around (pun intended) everywhere.

Is it USD or EUR?
Does it include VAT?
What about rounding?

And more importantly: what happens if you accidentally pass $discountPercentage as $price?

PHP won’t complain. Both are floats. You just sold a MacBook for $15.

On top of that, floats introduce precision issues, which makes them a poor choice for financial calculations in the first place.

What Exactly is a Value Object?

A Value Object (VO) is an object that is defined by its value rather than its identity.

Two Value Objects with the same data are considered equal—even if they are different instances.

In modern PHP (8.2+), a well-designed Value Object has three key characteristics:

Immutability – once created, it cannot change
Validation – it cannot exist in an invalid state
Self-documentation – the type clearly expresses intent

A Better Approach: Explicit Domain Types

Let’s refactor the previous example.

final readonly class Price
{
    public function __construct(
        public int $amount, // in cents
        public Currency $currency
    ) {
        if ($this->amount < 0) {
            throw new InvalidPriceException("Price cannot be negative.");
        }
    }

    public function add(Price $other): Price
    {
        if ($this->currency !== $other->currency) {
            throw new CurrencyMismatchException();
        }

        return new Price($this->amount + $other->amount, $this->currency);
    }

    public function equals(Price $other): bool
    {
        return $this->amount === $other->amount
            && $this->currency === $other->currency;
    }
}

A few important things are happening here:

Encapsulation – price logic lives inside the Price class
Type safety – you cannot mix currencies accidentally
Immutability – every operation returns a new instance
Precision – using integers avoids float rounding issues

Why This Matters (Especially Today)

With AI-assisted development becoming standard, types matter more than ever.

When you use primitives, tools like GitHub Copilot or ChatGPT have to guess intent.

When you use a Price or EmailAddress object, both humans and AI can:

understand constraints immediately
discover available behavior via methods
avoid invalid states by design

You’re not just writing code—you’re defining a clear contract.

Real-World Refactoring: Email

How often have you written this?

if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
    throw new Exception("Invalid email");
}

If it appears in multiple places, that’s duplication—and a maintenance risk.

Let’s move that logic into a Value Object:

final readonly class EmailAddress
{
    private string $value;

    public function __construct(string $value)
    {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidEmailException($value);
        }

        $this->value = strtolower(trim($value));
    }

    public function getDomain(): string
    {
        return substr(strrchr($this->value, "@"), 1);
    }

    public function __toString(): string
    {
        return $this->value;
    }
}

Now your service layer becomes much cleaner:

// BEFORE
public function registerUser(string $email, string $password) { ... }

// AFTER
public function registerUser(EmailAddress $email, Password $password) { ... }

The moment execution reaches registerUser, you already know the email is valid.

Validation is handled at the boundary of your system—not scattered across your codebase.

Logic-Heavy Value Objects

A common mistake is treating Value Objects as simple data containers.

In practice, they should encapsulate behavior related to that data.

Instead of passing:

string $startDate, string $endDate

You can model:

OrderDateRange

With methods like:

overlapsWith()
isWithinLastMonth()
getDurationInDays()

This reduces cognitive load in your services and keeps domain logic where it belongs.

When NOT to Use Value Objects

Not everything needs to be a Value Object.

Ask yourself:

Does this data have validation rules?
Is it reused in multiple places?
Does it represent a domain concept (SKU, IBAN, Email, Price)?

If the answer is yes, a Value Object is likely justified.

If you’re building a quick prototype, primitives are fine. Just be aware of the trade-offs.

Performance Considerations

A common concern used to be performance—creating many small objects instead of using primitives.

In modern PHP, object instantiation is highly optimized. The overhead is negligible compared to the cost of bugs caused by invalid states.

More importantly:

immutable objects are predictable
they eliminate side effects
they are naturally safe in concurrent or async contexts

Summary

Refactoring toward Value Objects is one of the most effective ways to improve code quality.

It forces you to think in terms of domain concepts, not just data types.

Practical steps:

Look at a complex service class
Find a variable validated in multiple places
Extract it into a readonly Value Object
Move related logic into that object

You’ll end up with code that is easier to read, safer to modify, and harder to break.

Trunk-Based Development: Your Pull Requests Are Still Too Big

CodeCraft Diary — Thu, 30 Apr 2026 13:18:00 +0000

Most teams don’t realize this, but their biggest bottleneck isn’t architecture, tech stack, or even legacy code.

It’s pull requests.

If you read about trunk-based development, you’ll see the same advice repeated everywhere: small changes, frequent merges, fast feedback. Sounds simple. Almost obvious.

And yet — in reality — most teams are nowhere near that.

I’ve personally seen pull requests sitting open for months. Not days. Not weeks. Months.

At one point, we had a pull request in our team that was open for more than six months.

Six.

Months.

At that point, it’s no longer a pull request. It’s a parallel universe.

Below this link you can read first article about Trunk-Based Development

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

The Hidden Cost of Large Pull Requests

Let’s be precise about what’s happening here.

A large pull request is not just “a bit harder to review”. It fundamentally breaks your delivery system.

Here’s what actually happens:

1. Review becomes a cognitive nightmare

When a PR has:

1,000+ lines
multiple concerns (API, DB, UI, validation)
partial refactors

No one can realistically review it properly.

So what happens?

reviewers skim
they miss edge cases
they delay the review (“I’ll look at it later”)

And “later” turns into never.

2. Feedback loop collapses

Fast feedback is the core of modern development.

But with large PRs:

feedback comes late
feedback is vague
feedback is expensive to apply

Instead of:

“Fix this small thing”

You get:

“This entire approach might be wrong”

Now the author has to:

rethink everything
rework large chunks of code
re-request review

Cycle time explodes.

3. Merge becomes risky

The bigger the PR, the higher the risk:

conflicts with main branch
outdated assumptions
broken integrations

So teams hesitate.

And hesitation kills flow.

4. Work gets batched (and everything slows down)

This is the core anti-pattern.

Instead of shipping continuously, developers start batching work:

“I’ll just add one more thing before I open the PR”

Then:

“Actually, I’ll include this refactor too”

And suddenly:

PR grows
review slows
merge is delayed

It’s a vicious cycle.

The Real Reason Your PRs Are Too Big

Let’s be honest — this is not a tooling issue.

It’s behavioral.

Here are the real causes:

1. “I want it to be complete”

This is the most common mindset:

“I’ll open the PR when the feature is done.”

Sounds reasonable. It’s also completely wrong.

Because “done” often means:

multiple layers
edge cases
polish

Which leads to massive PRs.

2. Fear of breaking things

Without proper safety mechanisms (tests, feature flags), developers avoid small merges.

So they wait.

And wait.

And accumulate changes.

3. Poor slicing of work

Most developers split work like this:

backend PR
frontend PR
DB migration PR

Instead of:

vertical slices that deliver value end-to-end

This creates artificial dependencies and forces larger PRs.

4. Review culture is asynchronous and slow

If reviews take:

hours
or days

Developers adapt by batching work.

Why open a small PR if it will just sit there?

The 6-Month Pull Request Problem

Let’s go back to that real example.

A PR open for six months.

What does that actually mean?

The branch is completely outdated
The context is lost
The author doesn’t remember all decisions
The reviewers don’t understand it anymore

At that point, you have only two realistic options:

Merge it blindly (high risk)
Close it and start over (lost work)

Both are bad.

But the real failure happened much earlier — when the PR was allowed to grow beyond control.

How to Fix This (Practically)

This is not about theory. These are concrete practices that work.

1. Enforce a hard PR size limit
Set a rule:

Max ~300–400 lines per PR

Not as a suggestion.

As a constraint.

Why?

Because constraints force better behavior:

better slicing
fewer concerns per change
faster reviews

2. Merge incomplete work (safely)

This is the shift most teams struggle with.

You don’t need “finished features” to merge.

You need:

safe code
controlled exposure

Use:

feature flags
toggles
hidden UI states

This allows you to:

merge early
iterate safely

Slice vertically, not horizontally

Instead of:

PR 1: database
PR 2: API
PR 3: UI

Do:

PR 1: minimal end-to-end functionality
PR 2: extend behavior
PR 3: polish

Each PR:

delivers something usable
is independently testable
is small

4. Optimize review speed (not just quality)

Set expectations:

PR should be reviewed within a few hours
not days

Ways to achieve this:

smaller PRs (obviously)
clear ownership
synchronous reviews when needed (pairing)

5. Accept “ugly but correct” code (temporarily)

This is uncomfortable but critical.

Sometimes the right move is:

“Merge this small, slightly imperfect change now”

Instead of:

“Wait until it’s perfectly clean”

Why?

Because flow matters more than perfection.

You can always:

refactor later (but don’t forget — it’s important for code cleanup)
improve incrementally

6. Track your actual behavior

If you want to be serious about this, measure:

average PR size
PR lifetime
number of merges per day

Reality check:

If your PRs:

live for days
contain hundreds/thousands of lines

You are not doing trunk-based development.

No matter what your team says.

What About Large Architectural Changes?

A common question that comes up here is: does this apply when you’re doing a complete architectural overhaul of a service?

The short answer is yes — and there’s a specific pattern for it called Branch by Abstraction.

Instead of keeping the new architecture in a separate Git branch for months (and facing a merge nightmare later), you keep both versions in the main branch simultaneously. It feels messy at first. It’s much safer in practice.

Here’s how it works in combination with feature flags:

You merge small, incremental pieces of the new architecture daily — never a big bang.
You run dark launches: the new code executes in production, but its results are ignored or compared against the old implementation. No user impact, real-world validation.
When confidence is high enough, you flip the flag and the new architecture goes live instantly.
The two things that make this work:

The flag has to exist from the start. Not added later as an afterthought. If you begin the migration without a flag, you’ll end up in the same situation as a long-lived branch — just in the main branch instead.
The cleanup phase is not optional. Once the rollout is 100% successful, deleting the old code and removing the flag is not a nice-to-have. It’s part of the work. Skipping this step is how codebases become impossible to understand.

The tradeoff is real: having two architectures in the codebase simultaneously requires more discipline and coordination from the team.

The Real Mindset Shift

This is the uncomfortable truth:

Small pull requests are not a technical practice.
They are a discipline.

They require you to:

let go of “completeness”
embrace incremental delivery
prioritize flow over polish

And that’s hard.

Because it goes against how most developers naturally think about work.

Final Thought

That 6-month pull request wasn’t an exception.

It was just an extreme version of a very common problem.

Most teams are operating with:

oversized changes
slow feedback
delayed merges

And then they wonder why delivery feels slow.

If you fix just one thing, fix this:

Make your pull requests smaller. Radically smaller.

Everything else — faster reviews, fewer bugs, smoother delivery — follows from that.

Not the other way around.

Laravel Testing Mistakes That Make Your Tests Useless

CodeCraft Diary — Tue, 21 Apr 2026 13:00:00 +0000

Testing in Laravel can feel straightforward at first. You write a few tests, run php artisan test, see green output, and move on. But here’s the uncomfortable truth: many passing tests don’t actually protect your application.

If your tests don’t catch real bugs, they’re not just useless—they give you a false sense of confidence.

In this article, we’ll go through the most common Laravel testing mistakes that quietly break the value of your test suite, along with practical examples and better approaches.

You can be also interested in testing databse logic: https://codecraftdiary.com/2026/01/03/testing-database-logic-what-to-test-what-to-skip-and-why-it-matters/

1. Testing Implementation Instead of Behavior

One of the biggest mistakes is writing tests that mirror your code instead of validating what your application actually does.

Bad example

public function test_it_calls_service_method()
{
    $service = Mockery::mock(UserService::class);
    $service->shouldReceive('createUser')->once();

    $controller = new UserController($service);
    $controller->store(new Request([...]));
}

This test only checks that a method was called. It doesn’t verify:

what was created
whether the data is correct
whether anything actually works

Better approach

public function test_user_is_created()
{
    $response = $this->post('/users', [
        'name' => 'John Doe',
        'email' => 'john@example.com',
    ]);

    $response->assertStatus(201);

    $this->assertDatabaseHas('users', [
        'email' => 'john@example.com',
    ]);
}

Focus on observable behavior, not internal calls.

2. Overusing Mocks

Mocks are powerful—but overusing them leads to fragile and meaningless tests.

Problem

When everything is mocked:

you’re not testing real integration
your tests pass even if the system is broken

Http::fake();

$response = $this->get('/weather');

$response->assertStatus(200);

This tells you nothing about:

response structure
data correctness
edge cases

Better approach

Mock only what you must (external services), and assert meaningful output:

Http::fake([
    '*' => Http::response(['temp' => 25], 200),
]);

$response = $this->get('/weather');

$response->assertJson([
    'temperature' => 25,
]);

Rule of thumb:
Mock boundaries, not your own logic.

3. Writing Tests That Always Pass

Some tests are written in a way that they can’t fail—even if the code is broken.

Example

public function test_response_is_ok()
{
    $response = $this->get('/users');

    $response->assertStatus(200);
}

This test will pass even if:

the response is empty
the wrong data is returned
business logic is broken

Better approach

$response->assertJsonStructure([
    'data' => [
        '*' => ['id', 'name', 'email']
    ]
]);

Or even better:

$this->assertDatabaseCount('users', 3);

Ask yourself:
“What bug would this test catch?”
If the answer is “none”, rewrite it.

4. Ignoring Edge Cases

Most bugs don’t happen in the “happy path”. They happen at the edges.

Common mistake

Only testing valid input:

$this->post('/users', [
    'email' => 'john@example.com',
]);

Better approach

Test invalid scenarios:

$this->post('/users', [
    'email' => 'not-an-email',
])->assertSessionHasErrors('email');

Also test:

missing fields
duplicate values
unexpected input

Good tests try to break your application.

5. Testing Too Much in Unit Tests

Unit tests should be fast and focused. But many developers turn them into mini integration tests.

Example

public function test_order_creation()
{
    $order = OrderService::create([...]);

    $this->assertDatabaseHas('orders', [...]);
}

This mixes:

business logic
database layer

Better approach

Split responsibilities:

Unit test (logic only):

public function test_total_price_is_calculated_correctly()
{
    $total = OrderCalculator::calculate([100, 200]);

    $this->assertEquals(300, $total);
}

Feature test (full flow):

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

$this->assertDatabaseHas('orders', [...]);

Keep your test layers clean.

6. Not Using Factories Properly

Laravel factories are powerful, but many developers misuse them.

Problem

Hardcoding everything:

User::create([
    'name' => 'Test',
    'email' => 'test@example.com',
]);

Better approach

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

Even better:

$user = User::factory()->state([
    'email_verified_at' => now(),
])->create();

Benefits:

less boilerplate
more flexible tests
easier maintenance

7. Not Cleaning Up Test Data

Dirty test data can cause flaky tests.

Problem

Tests depend on previous state.

Solution

Use:

use Illuminate\Foundation\Testing\RefreshDatabase;

This ensures:

clean DB for each test
consistent results

Flaky tests destroy trust in your test suite.

8. Writing Tests That Are Too Complex

If your test is hard to read, it’s probably doing too much.

Example

public function test_everything()
{
    // 50 lines of setup
    // 10 assertions
}

Better approach

Break it down:

public function test_user_can_register() {}
public function test_email_must_be_unique() {}
public function test_password_is_required() {}

Each test should answer one question.

9. Ignoring Performance

Slow tests are often skipped—and skipped tests are useless tests.

Problem

too many DB calls
unnecessary setup
heavy fixtures

Tips

use in-memory database (SQLite)
avoid unnecessary seeding
keep unit tests fast

Fast tests = tests you actually run.

10. Not Testing Real User Flows

Testing isolated pieces is not enough.

Problem

You test services and controllers separately, but never the full flow.

Example

public function test_user_can_register_and_login()
{
    $this->post('/register', [
        'email' => 'john@example.com',
        'password' => 'password',
    ]);

    $this->post('/login', [
        'email' => 'john@example.com',
        'password' => 'password',
    ])->assertRedirect('/dashboard');
}

This is what actually matters:
Can the user complete the action?

Final Thoughts

Laravel makes testing easy—but writing useful tests is a different skill.

If your tests:

only check status codes
mock everything
mirror your implementation

…then they’re not protecting your application.

Instead, focus on:

real behavior
meaningful assertions
edge cases
realistic user flows

A smaller set of high-quality tests is far more valuable than a large suite of weak ones.

Quick Checklist

Before committing a test, ask:

Does this test fail if something important breaks?
Am I testing behavior, not implementation?
Would this catch a real bug?
Is this test simple and readable?

If the answer is “no”, it’s time to improve it.

Well-written tests are not just about coverage—they’re about confidence. And confidence comes from tests that actually matter.

Fat Controller to Clean Architecture in Laravel (Step-by-Step Refactor)

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

Refactoring a fat controller in Laravel is one of the most impactful improvements you can make in a growing codebase. As projects evolve, controllers often become overloaded with validation, business logic, and side effects, making them difficult to maintain and test.

A controller starts small. Clean. Readable.

Then features get added.

Deadlines hit.

Logic piles up.

And suddenly, you’re staring at a 500-line controller that handles validation, business logic, database writes, API calls, and maybe even a bit of formatting “just for now.”

This is what we call a Fat Controller — and it’s one of the most common maintainability problems in Laravel applications.

In this article, we’ll take a real-world approach and refactor a fat controller into a cleaner, scalable structure using principles inspired by Clean Architecture.

No theory overload. Just practical steps.

The Problem: A Real Fat Controller Example

Let’s start with something painfully familiar:

class OrderController extends Controller
{
    public function store(Request $request)
    {
        // Validation
        $validated = $request->validate([
            'user_id' => 'required|exists:users,id',
            'items' => 'required|array',
        ]);

        // Business logic
        $total = 0;

        foreach ($validated['items'] as $item) {
            $product = Product::find($item['id']);

            if (!$product) {
                throw new Exception('Product not found');
            }

            if ($product->stock < $item['quantity']) {
                throw new Exception('Not enough stock');
            }

            $total += $product->price * $item['quantity'];

            $product->stock -= $item['quantity'];
            $product->save();
        }

        // Save order
        $order = Order::create([
            'user_id' => $validated['user_id'],
            'total' => $total,
        ]);

        // Save items
        foreach ($validated['items'] as $item) {
            OrderItem::create([
                'order_id' => $order->id,
                'product_id' => $item['id'],
                'quantity' => $item['quantity'],
            ]);
        }

        // External API call
        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);

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

What’s wrong here?

Controller handles too many responsibilities
Business logic is not reusable
Hard to test
Tight coupling to Eloquent and external APIs
Changes are risky

Goal: What “Clean” Looks Like

We want to move toward:

Thin controllers
Isolated business logic
Testable services
Clear boundaries between layers

We’re not going full academic Clean Architecture. We’re applying just enough structure to stay sane.

Step 1: Extract Business Logic into a Service

First, move the core logic out of the controller.

class CreateOrderService
{
    public function handle(array $data): Order
    {
        $total = 0;

        foreach ($data['items'] as $item) {
            $product = Product::find($item['id']);

            if (!$product) {
                throw new Exception('Product not found');
            }

            if ($product->stock < $item['quantity']) {
                throw new Exception('Not enough stock');
            }

            $total += $product->price * $item['quantity'];

            $product->stock -= $item['quantity'];
            $product->save();
        }

        $order = Order::create([
            'user_id' => $data['user_id'],
            'total' => $total,
        ]);

        foreach ($data['items'] as $item) {
            OrderItem::create([
                'order_id' => $order->id,
                'product_id' => $item['id'],
                'quantity' => $item['quantity'],
            ]);
        }

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

        return $order;
    }
}

Controller becomes:

class OrderController extends Controller
{
    public function store(Request $request, CreateOrderService $service)
    {
        $validated = $request->validate([
            'user_id' => 'required|exists:users,id',
            'items' => 'required|array',
        ]);

        $order = $service->handle($validated);

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

Improvement:

Controller is now thin
Logic is reusable
Easier to test

But we’re not done yet.

Step 2: Introduce a Data Transfer Object (DTO)

Passing raw arrays is fragile.

Let’s fix that.

class CreateOrderData
{
    public function __construct(
        public int $userId,
        public array $items
    ) {}

    public static function fromArray(array $data): self
    {
        return new self(
            $data['user_id'],
            $data['items']
        );
    }
}

Update controller:

$data = CreateOrderData::fromArray($validated);
$order = $service->handle($data);

Update service:

public function handle(CreateOrderData $data): Order

Improvement:

Stronger typing
Safer refactoring
Clear contract

Step 3: Decouple External Dependencies

Right now, your service is tightly coupled to:

Eloquent models
HTTP client

Let’s extract the webhook logic.

class OrderWebhookService
{
    public function send(Order $order): void
    {
        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);
    }
}

Inject it:

class CreateOrderService
{
    public function __construct(
        private OrderWebhookService $webhook
    ) {}

    public function handle(CreateOrderData $data): Order
    {
        // logic...

        $this->webhook->send($order);

        return $order;
    }
}

Improvement:

External side effects are isolated
Easier to mock in tests

Step 4: Make It Testable

Now you can test the service independently:

public function test_it_creates_order()
{
    $service = app(CreateOrderService::class);

    $data = new CreateOrderData(
        userId: 1,
        items: [
            ['id' => 1, 'quantity' => 2],
        ]
    );

    $order = $service->handle($data);

    $this->assertNotNull($order->id);
}

Before refactoring, this would require:

HTTP mocking
Controller testing
Complex setup

Now it’s isolated.

Step 5: Optional — Introduce Repositories (Only If Needed)

Don’t overengineer this.

But if your app grows, you might extract:

class ProductRepository
{
    public function find(int $id): ?Product
    {
        return Product::find($id);
    }
}

Then inject it into the service.

When to do this:

Multiple data sources
Complex queries
Domain logic reuse

When NOT to:

Simple CRUD apps

Before vs After

Aspect	Before	After
Controller size	Huge	Minimal
Testability	Hard	Easy
Reusability	None	High
Coupling	High	Reduced
Maintainability	Painful	Scalable

Common Mistakes to Avoid

1. Moving everything blindly into services

You’ll just create fat services instead of fat controllers.

Keep services focused.

2. Overengineering with too many layers

You don’t need:

10 interfaces
5 abstractions
enterprise architecture™

Start simple. Evolve when needed.

3. Ignoring boundaries

Controllers = HTTP
Services = business logic
Models = persistence

Mixing these again = back to chaos.

Key Takeaways

Fat controllers are a symptom, not the root problem
The real issue is mixed responsibilities
Start with service extraction
Add DTOs for safety
Isolate side effects (APIs, events)
Only introduce more abstraction when justified

Final Thought

Clean Architecture in Laravel doesn’t mean rewriting your app into a textbook diagram.

It means one thing:

Making your code easier to change without fear.

And the fastest way to get there?

Start killing your fat controllers — one method at a time.

If this is something you’re dealing with right now, your next step is simple:

Pick your worst controller and extract just one action into a service.

That’s how clean architecture actually starts.

Trunk-Based Development: Why Most Teams Think They Use It (But Don’t)

CodeCraft Diary — Tue, 07 Apr 2026 13:20:00 +0000

Trunk-Based Development sounds simple.

No long-lived branches.
Frequent merges.
Small, incremental changes.

Most teams will tell you:

“Yeah, we basically do trunk-based development.”

In practice, they don’t.

What they usually have is a hybrid that keeps the downsides of feature branches — while pretending to get the benefits of trunk-based development.

I’ve seen this pattern in multiple backend teams. On paper, everything looks modern. In reality, delivery is still slow, pull requests are large, and integration is painful.

So let’s break down what’s actually going on.

The Illusion of Trunk-Based Development

Ask a team how they work, and you’ll often hear something like:

“We merge to main frequently”
“We don’t keep branches for too long”
“We try to keep PRs small”

Sounds good.

But then you look closer:

PRs are open for 3–5 days
branches still contain multiple features
merges are delayed because reviews are slow
developers are afraid to merge unfinished work

This is not trunk-based development.

This is just shorter feature branches.

What Real Trunk-Based Development Actually Requires

Trunk-based development is not about branches.

It’s about integration frequency and safety.

At its core, it requires:

merging to main at least daily (ideally multiple times per day)
keeping changes small enough to review quickly
having strong safety mechanisms in place

Without these, trunk-based development collapses.

Where Most Teams Break

1. Pull Requests Are Still Too Big

This is the biggest issue.

A developer starts a “small” feature:

adds endpoint
updates service
modifies database
adds validation
fixes something unrelated

Now the PR has:

15 files changed
600+ lines
multiple concerns

Review slows down. Feedback increases. Merge is delayed.

At that point, it doesn’t matter what you call your workflow —
you’re not doing trunk-based development.

2. Code Reviews Block Integration

In theory:

“We merge frequently”

In reality:

“We merge when the PR gets approved”

That delay is critical.

If reviews take:

1 day → integration is delayed
2–3 days → conflicts increase
5 days → context is lost

Now developers start stacking changes on top of each other.

And suddenly:

branches live longer
PRs get bigger
merges become risky

3. Teams Are Afraid to Merge Incomplete Work

This is subtle but important.

Developers often think:

“I can’t merge this yet — it’s not finished”

So they keep working on the branch.

The problem:

the longer the branch lives
the more it diverges
the harder it is to merge

Trunk-based development requires a different mindset:

You merge incomplete work safely.

The Missing Piece: Feature Flags

Most teams skip this.

And without it, trunk-based development doesn’t work.

Example

You’re building a new payment flow.

Without feature flags:

you need to finish everything before merging
you keep a long-lived branch
integration is delayed

With feature flags:

if (Feature::enabled('new_payment_flow')) {
    $this->newFlow();
} else {
    $this->oldFlow();
}

Now you can:

merge partial work
deploy continuously
control exposure

Real Example From Practice

I worked with a team that claimed they were doing trunk-based development.

Metrics looked like this:

average PR size: ~500 lines
review time: 2–3 days
merges per developer: ~2 per week

After digging in, the issue was clear:

developers grouped work “to be efficient”
reviews were asynchronous and slow
no feature flags

What changed

We introduced 3 rules:

PR must be mergeable within the same day
no PR over ~300 lines (soft limit)
feature flags for incomplete features

Result after ~3 weeks:

PR size dropped by ~40%
review time dropped to hours
merges increased to multiple per day
production issues decreased

Not because developers got better.

Because the system changed.

The Hidden Constraint: CI/CD Speed

Here’s something teams often ignore:

You cannot do trunk-based development with slow pipelines.

If your CI takes:

20 minutes → friction
40 minutes → developers wait
60+ minutes → people stop merging frequently

So what happens?

developers batch changes
PRs get bigger
integration slows down

Rule of thumb (2026 reality):

CI under 10 minutes → good
under 5 minutes → ideal

Anything above that:
→ you’re actively fighting your workflow

Why This Matters More in 2026

With AI-assisted coding, developers can generate code faster than ever.

That creates a new problem:

volume of changes increases
but review capacity doesn’t

If you don’t enforce:

small changes
fast integration
clear boundaries

your workflow collapses under its own weight.

How to Tell If You’re Actually Doing It

Be honest and check:

Do you merge to main multiple times per day?
Are most PRs reviewed within hours, not days?
Can you safely merge incomplete work?
Are branches short-lived (hours, not days)?

If not:
→ you’re not doing trunk-based development

Practical Rules You Can Apply Tomorrow

If you want to move closer to real trunk-based development, start here:

1. Limit PR size

Not as a guideline — as a rule.

2. Optimize for review speed

fewer changes
clearer intent
less context switching

3. Introduce feature flags

Without them, you’re stuck.

4. Fix your CI/CD bottlenecks

Speed is not a luxury — it’s a requirement.

5. Stop batching work

Batching feels efficient.
It’s not.

Closing Thought

Trunk-based development is not a branching strategy.

It’s a discipline.

Most teams don’t fail because they don’t understand it.
They fail because they don’t change the constraints that make it possible.

If your:

PRs are big
reviews are slow
CI is slow
merges are risky

then it doesn’t matter what you call your workflow.

You’re still doing feature-branch development — just with better branding.

And that’s exactly why your delivery still feels slower than it should.