They test that a user can edit their own post. They test that the admin dashboard loads for an admin. CI is green, everyone is happy.

What they don’t test is whether a random logged-in user can edit someone else’s post.

And that’s exactly the kind of bug that ends up in a security report.

Authorization feels “done” the moment you write the policy. But a policy nobody calls, a middleware someone removed from a route group during a refactor, or a gate with a flipped condition won’t break a single happy-path test. It just quietly leaves a door open.

In this article I’ll show you how I approach testing authorization in Laravel: policies, gates, and middleware. Nothing fancy, just patterns that keep these tests short, readable, and actually useful.

Last article in this category: https://codecraftdiary.com/2026/09/06/testing-time-in-laravel/

The Example: A Simple Post Policy

Let’s keep it realistic but small. Users write posts. Only the author can update a post. The author or an admin can delete it.

class PostPolicy
{
    public function update(User $user, Post $post): bool
    {
        return $user->id === $post->user_id;
    }

    public function delete(User $user, Post $post): bool
    {
        return $user->id === $post->user_id || $user->is_admin;
    }
}

class PostPolicy
{
    public function update(User $user, Post $post): bool
    {
        return $user->id === $post->user_id;
    }

    public function delete(User $user, Post $post): bool
    {
        return $user->id === $post->user_id || $user->is_admin;
    }
}

And the controller uses it:

public function update(Request $request, Post $post)
{
    Gate::authorize('update', $post);

    $post->update($request->validate([
        'title' => ['required', 'string', 'max:255'],
    ]));

    return redirect()->route('posts.show', $post);
}

public function update(Request $request, Post $post)
{
    Gate::authorize('update', $post);

    $post->update($request->validate([
        'title' => ['required', 'string', 'max:255'],
    ]));

    return redirect()->route('posts.show', $post);
}

There are two separate questions here, and you need tests for both:

1. Is the policy logic correct?
2. Is the policy actually used where it should be?

Most people only test the first one. Some test neither.

Step 1: Unit Testing the Policy

A policy is just a PHP class with methods that return booleans. That makes it one of the easiest things in Laravel to test.

class PostPolicyTest extends TestCase
{
    use RefreshDatabase;

    public function test_author_can_update_their_post(): void
    {
        $author = User::factory()->create();
        $post = Post::factory()->for($author)->create();

        $this->assertTrue($author->can('update', $post));
    }

    public function test_other_user_cannot_update_the_post(): void
    {
        $post = Post::factory()->create();
        $stranger = User::factory()->create();

        $this->assertFalse($stranger->can('update', $post));
    }
}

class PostPolicyTest extends TestCase
{
    use RefreshDatabase;

    public function test_author_can_update_their_post(): void
    {
        $author = User::factory()->create();
        $post = Post::factory()->for($author)->create();

        $this->assertTrue($author->can('update', $post));
    }

    public function test_other_user_cannot_update_the_post(): void
    {
        $post = Post::factory()->create();
        $stranger = User::factory()->create();

        $this->assertFalse($stranger->can('update', $post));
    }
}

Notice I’m using $user->can() instead of calling new PostPolicy() directly. That’s on purpose. can() goes through Laravel’s Gate, so the test also verifies that the policy is actually registered and that any before() hook behaves the way you expect. Calling the class directly would happily pass even if Laravel never found your policy.

Step 2: Cover the Role Matrix with a Data Provider

Once you have more than two roles, writing one test per combination gets old fast. A data provider turns the whole permission matrix into a single readable table:

#[DataProvider('deletePermissions')]
public function test_delete_permissions(string $role, bool $expected): void
{
    $post = Post::factory()->create();

    $user = match ($role) {
        'author' => $post->user,
        'admin' => User::factory()->create(['is_admin' => true]),
        'stranger' => User::factory()->create(),
    };

    $this->assertSame($expected, $user->can('delete', $post));
}

public static function deletePermissions(): array
{
    return [
        'author can delete' => ['author', true],
        'admin can delete' => ['admin', true],
        'stranger cannot delete' => ['stranger', false],
    ];
}

#[DataProvider('deletePermissions')]
public function test_delete_permissions(string $role, bool $expected): void
{
    $post = Post::factory()->create();

    $user = match ($role) {
        'author' => $post->user,
        'admin' => User::factory()->create(['is_admin' => true]),
        'stranger' => User::factory()->create(),
    };

    $this->assertSame($expected, $user->can('delete', $post));
}

public static function deletePermissions(): array
{
    return [
        'author can delete' => ['author', true],
        'admin can delete' => ['admin', true],
        'stranger cannot delete' => ['stranger', false],
    ];
}

Why strings instead of models? Data providers run before the test’s setUp(), so there’s no database yet. Pass a label, build the model inside the test. Small trick, saves a lot of confusion.

When a new role appears, you add one line. When someone changes the policy, the failing case name tells you exactly what broke.

Step 3: Testing Gates

Gates are for permissions that aren’t tied to a specific model. For example, in AppServiceProvider:

Gate::define('view-reports', fn (User $user) => $user->is_admin);

Gate::define('view-reports', fn (User $user) => $user->is_admin);

Testing it is just as simple. Gate::forUser() lets you check any user without logging them in:

public function test_only_admins_can_view_reports(): void
{
    $admin = User::factory()->create(['is_admin' => true]);
    $user = User::factory()->create();

    $this->assertTrue(Gate::forUser($admin)->allows('view-reports'));
    $this->assertTrue(Gate::forUser($user)->denies('view-reports'));
}

public function test_only_admins_can_view_reports(): void
{
    $admin = User::factory()->create(['is_admin' => true]);
    $user = User::factory()->create();

    $this->assertTrue(Gate::forUser($admin)->allows('view-reports'));
    $this->assertTrue(Gate::forUser($user)->denies('view-reports'));
}

Always test both sides. A gate that returns true for everyone passes the admin test perfectly.

Step 4: Feature Tests — Is the Policy Actually Wired In?

This is the part that really matters.

Your policy tests can be perfect, and the app can still be wide open. Someone deletes the Gate::authorize() line while refactoring the controller. All policy tests stay green. Production is now broken in the worst possible way: silently.

The only thing that catches this is a feature test that hits the real endpoint as the wrong user:

public function test_user_cannot_update_someone_elses_post(): void
{
    $post = Post::factory()->create(['title' => 'Original title']);
    $stranger = User::factory()->create();

    $this->actingAs($stranger)
        ->put(route('posts.update', $post), ['title' => 'Hacked'])
        ->assertForbidden();

    $this->assertSame('Original title', $post->fresh()->title);
}

public function test_user_cannot_update_someone_elses_post(): void
{
    $post = Post::factory()->create(['title' => 'Original title']);
    $stranger = User::factory()->create();

    $this->actingAs($stranger)
        ->put(route('posts.update', $post), ['title' => 'Hacked'])
        ->assertForbidden();

    $this->assertSame('Original title', $post->fresh()->title);
}

That last assertion is the one people skip. Don’t. A 403 response doesn’t guarantee nothing happened. If the update ran before the authorization check, you’d get a 403 and a modified post. Always check that the side effect did not happen.

Guests are a separate case, so give them a separate test:

public function test_guest_is_redirected_to_login(): void
{
    $post = Post::factory()->create();

    $this->put(route('posts.update', $post), ['title' => 'Hacked'])
        ->assertRedirect(route('login'));
}

public function test_guest_is_redirected_to_login(): void
{
    $post = Post::factory()->create();

    $this->put(route('posts.update', $post), ['title' => 'Hacked'])
        ->assertRedirect(route('login'));
}

For JSON APIs, use assertUnauthorized() (401) for guests and assertForbidden() (403) for logged-in users without permission. Mixing those two up is a classic.

Step 5: Testing Middleware

Say you have a middleware that only lets subscribed users into certain pages:

class EnsureUserIsSubscribed
{
    public function handle(Request $request, Closure $next): Response
    {
        if (! $request->user()?->subscribed) {
            return redirect()->route('billing');
        }

        return $next($request);
    }
}

class EnsureUserIsSubscribed
{
    public function handle(Request $request, Closure $next): Response
    {
        if (! $request->user()?->subscribed) {
            return redirect()->route('billing');
        }

        return $next($request);
    }
}

I like to test middleware on its own using a tiny route defined only for the test. That way the test doesn’t depend on whatever controller happens to use it today:

protected function setUp(): void
{
    parent::setUp();

    Route::middleware(['web', EnsureUserIsSubscribed::class])
        ->get('/_test/premium', fn () => 'premium content');
}

public function test_unsubscribed_user_is_redirected_to_billing(): void
{
    $user = User::factory()->create(['subscribed' => false]);

    $this->actingAs($user)
        ->get('/_test/premium')
        ->assertRedirect(route('billing'));
}

public function test_subscribed_user_gets_through(): void
{
    $user = User::factory()->create(['subscribed' => true]);

    $this->actingAs($user)
        ->get('/_test/premium')
        ->assertOk()
        ->assertSee('premium content');
}

protected function setUp(): void
{
    parent::setUp();

    Route::middleware(['web', EnsureUserIsSubscribed::class])
        ->get('/_test/premium', fn () => 'premium content');
}

public function test_unsubscribed_user_is_redirected_to_billing(): void
{
    $user = User::factory()->create(['subscribed' => false]);

    $this->actingAs($user)
        ->get('/_test/premium')
        ->assertRedirect(route('billing'));
}

public function test_subscribed_user_gets_through(): void
{
    $user = User::factory()->create(['subscribed' => true]);

    $this->actingAs($user)
        ->get('/_test/premium')
        ->assertOk()
        ->assertSee('premium content');
}

Then add at least one feature test on a real protected route. The isolated test proves the middleware works. The real-route test proves it’s still attached.

One warning: be careful with withoutMiddleware(). It’s tempting to use it everywhere to make tests “simpler”, but it disables auth too. If half your suite runs without middleware, half your suite never tests authorization at all.

Bonus: 403 or 404?

Sometimes you don’t want to tell a stranger that a resource even exists. If you scope the query to the current user, they get a 404 instead of a 403:

$post = $request->user()->posts()->findOrFail($id);

$post = $request->user()->posts()->findOrFail($id);

Both approaches are fine. What’s not fine is not knowing which one your app uses. Pick one, and pin it with a test (assertNotFound() or assertForbidden()), so a future refactor can’t change the behavior without anyone noticing.

Quick Checklist

Before I consider an endpoint covered, I go through this list:

• At least one test where the wrong user tries the action and gets denied
• The database is unchanged after a denied request
• Guests are tested separately from logged-in users
• Policy unit tests cover the logic; feature tests cover the wiring
• withoutMiddleware() is used rarely, and never in authorization tests

Conclusion

Authorization bugs are sneaky because they don’t crash anything. The app works, the tests pass, and the only person who notices is the one who wasn’t supposed to get in.

The good news is that these tests are some of the simplest you’ll ever write. A factory, actingAs(), one request, one assertion that something didn’t happen. Ten minutes of work per endpoint.

So next time you add a policy, don’t stop at “the author can edit”. Write the test for the stranger too. Future you (and your security team) will thank you.

The post Testing Authorization in Laravel: Policies, Gates, and Middleware appeared first on CodeCraft Diary.

That article ended with a promise: once the tests exist, you can finally start cleaning up.

So let’s do it. Same controller, same tests. No new architecture, no design patterns, no big rewrite. Just small moves, one at a time, with green tests after every single one.

Previous article in this category: https://codecraftdiary.com/2026/08/30/refactoring-the-database-layer-replacing-query-scope-bloat-with-repository-query-objects/

The code we’re starting with

Here’s the method again, exactly as it was:

public function processOrder(Request $request)
{
    $order = new Order();
    $order->product_id = $request->product_id;
    $order->quantity = $request->quantity;
    $order->user_id = auth()->id();
    $order->status = 'pending';
    $order->save();

    // business rules mixed directly inside controller
    if ($order->quantity > 10) {
        $order->priority = 'high';
    }

    if ($order->product_id === 999) {
        // fetch external pricing
        $response = Http::post('https://external-api.com/prices', [
            'product_id' => $order->product_id,
        ]);

        if ($response->ok()) {
            $order->external_price = $response->json('price');
        }
    }

    // logging inside business logic
    Log::info('Order processed', [
        'order_id' => $order->id,
        'user' => auth()->id(),
    ]);

    // send email
    Mail::to(auth()->user())->send(new OrderCreatedMail($order));

    // update stock
    $product = Product::find($order->product_id);
    $product->stock -= $order->quantity;
    $product->save();

    return response()->json([
        'id' => $order->id,
        'status' => $order->status,
        'priority' => $order->priority ?? 'normal',
    ], 201);
}

public function processOrder(Request $request)
{
    $order = new Order();
    $order->product_id = $request->product_id;
    $order->quantity = $request->quantity;
    $order->user_id = auth()->id();
    $order->status = 'pending';
    $order->save();

    // business rules mixed directly inside controller
    if ($order->quantity > 10) {
        $order->priority = 'high';
    }

    if ($order->product_id === 999) {
        // fetch external pricing
        $response = Http::post('https://external-api.com/prices', [
            'product_id' => $order->product_id,
        ]);

        if ($response->ok()) {
            $order->external_price = $response->json('price');
        }
    }

    // logging inside business logic
    Log::info('Order processed', [
        'order_id' => $order->id,
        'user' => auth()->id(),
    ]);

    // send email
    Mail::to(auth()->user())->send(new OrderCreatedMail($order));

    // update stock
    $product = Product::find($order->product_id);
    $product->stock -= $order->quantity;
    $product->save();

    return response()->json([
        'id' => $order->id,
        'status' => $order->status,
        'priority' => $order->priority ?? 'normal',
    ], 201);
}

It works. Nobody wants to touch it. That’s the definition of legacy code in most teams.

The only rule: small steps, green tests

Before we start, one rule that matters more than any technique in this article:

Change one thing. Run the tests. Commit. Repeat.

If a step breaks something, you know exactly which step it was, and git checkout . costs you two minutes instead of an afternoon. It feels slow. In practice, it’s the fastest way to refactor code you don’t fully understand.

Step 0: Pin down the behavior you’re about to touch

Our existing tests cover the happy path and the external price. But the priority rule isn’t tested at all, and it’s exactly the kind of thing that breaks quietly during refactoring. So before changing anything, I add one more characterization test:

public function test_priority_depends_on_quantity()
{
    Mail::fake();
    Http::fake();

    $this->actingAs(User::factory()->create());
    $product = Product::factory()->create(['stock' => 50]);

    $this->postJson('/api/orders/process', [
        'product_id' => $product->id,
        'quantity' => 10,
    ])->assertJson(['priority' => 'normal']);

    $this->postJson('/api/orders/process', [
        'product_id' => $product->id,
        'quantity' => 11,
    ])->assertJson(['priority' => 'high']);
}

public function test_priority_depends_on_quantity()
{
    Mail::fake();
    Http::fake();

    $this->actingAs(User::factory()->create());
    $product = Product::factory()->create(['stock' => 50]);

    $this->postJson('/api/orders/process', [
        'product_id' => $product->id,
        'quantity' => 10,
    ])->assertJson(['priority' => 'normal']);

    $this->postJson('/api/orders/process', [
        'product_id' => $product->id,
        'quantity' => 11,
    ])->assertJson(['priority' => 'high']);
}

Note the boundary. The rule is > 10, not >= 10, and “10 is normal” is exactly the kind of detail you’d accidentally change while “cleaning up”.

The test passes. Commit.

Step 1: Give magic values a name

10 and 999 mean something to someone. Probably to someone who left the company in 2021.

class OrderController extends Controller
{
    private const HIGH_PRIORITY_QUANTITY = 10;
    private const EXTERNALLY_PRICED_PRODUCT_ID = 999;

    // ...

    if ($order->quantity > self::HIGH_PRIORITY_QUANTITY) {
        $order->priority = 'high';
    }

    if ($order->product_id === self::EXTERNALLY_PRICED_PRODUCT_ID) {
        // ...
    }
}

class OrderController extends Controller
{
    private const HIGH_PRIORITY_QUANTITY = 10;
    private const EXTERNALLY_PRICED_PRODUCT_ID = 999;

    // ...

    if ($order->quantity > self::HIGH_PRIORITY_QUANTITY) {
        $order->priority = 'high';
    }

    if ($order->product_id === self::EXTERNALLY_PRICED_PRODUCT_ID) {
        // ...
    }
}

This is the most boring refactoring there is, and one of the most useful. The next person reading this code no longer has to guess why product 999 is special. The name tells them.

Tests: green. Commit.

Step 2: Stop asking for the same thing three times

The method calls auth() three times. It’s not a performance problem, it’s a readability one: every call makes you wonder whether it could return something different.

$user = auth()->user();

$order->user_id = $user->id;
// ...
Log::info('Order processed', [
    'order_id' => $order->id,
    'user' => $user->id,
]);

Mail::to($user)->send(new OrderCreatedMail($order));

$user = auth()->user();

$order->user_id = $user->id;
// ...
Log::info('Order processed', [
    'order_id' => $order->id,
    'user' => $user->id,
]);

Mail::to($user)->send(new OrderCreatedMail($order));

One variable, one source of truth. Tests: green. Commit.

Step 3: Extract methods until the main method reads like a story

This is the step that changes how the code feels. The comments in the original method are a big hint: every // fetch external pricing or // update stock is a method that wants to exist.

public function processOrder(Request $request)
{
    $user = auth()->user();

    $order = $this->createPendingOrder($request, $user);

    $this->applyPriority($order);
    $this->applyExternalPrice($order);

    Log::info('Order processed', [
        'order_id' => $order->id,
        'user' => $user->id,
    ]);

    Mail::to($user)->send(new OrderCreatedMail($order));

    $this->decreaseStock($order);

    return response()->json([
        'id' => $order->id,
        'status' => $order->status,
        'priority' => $order->priority ?? 'normal',
    ], 201);
}

private function createPendingOrder(Request $request, User $user): Order
{
    $order = new Order();
    $order->product_id = $request->product_id;
    $order->quantity = $request->quantity;
    $order->user_id = $user->id;
    $order->status = 'pending';
    $order->save();

    return $order;
}

private function applyPriority(Order $order): void
{
    if ($order->quantity > self::HIGH_PRIORITY_QUANTITY) {
        $order->priority = 'high';
    }
}

private function applyExternalPrice(Order $order): void
{
    if ($order->product_id === self::EXTERNALLY_PRICED_PRODUCT_ID) {
        $response = Http::post('https://external-api.com/prices', [
            'product_id' => $order->product_id,
        ]);

        if ($response->ok()) {
            $order->external_price = $response->json('price');
        }
    }
}

private function decreaseStock(Order $order): void
{
    $product = Product::find($order->product_id);
    $product->stock -= $order->quantity;
    $product->save();
}

public function processOrder(Request $request)
{
    $user = auth()->user();

    $order = $this->createPendingOrder($request, $user);

    $this->applyPriority($order);
    $this->applyExternalPrice($order);

    Log::info('Order processed', [
        'order_id' => $order->id,
        'user' => $user->id,
    ]);

    Mail::to($user)->send(new OrderCreatedMail($order));

    $this->decreaseStock($order);

    return response()->json([
        'id' => $order->id,
        'status' => $order->status,
        'priority' => $order->priority ?? 'normal',
    ], 201);
}

private function createPendingOrder(Request $request, User $user): Order
{
    $order = new Order();
    $order->product_id = $request->product_id;
    $order->quantity = $request->quantity;
    $order->user_id = $user->id;
    $order->status = 'pending';
    $order->save();

    return $order;
}

private function applyPriority(Order $order): void
{
    if ($order->quantity > self::HIGH_PRIORITY_QUANTITY) {
        $order->priority = 'high';
    }
}

private function applyExternalPrice(Order $order): void
{
    if ($order->product_id === self::EXTERNALLY_PRICED_PRODUCT_ID) {
        $response = Http::post('https://external-api.com/prices', [
            'product_id' => $order->product_id,
        ]);

        if ($response->ok()) {
            $order->external_price = $response->json('price');
        }
    }
}

private function decreaseStock(Order $order): void
{
    $product = Product::find($order->product_id);
    $product->stock -= $order->quantity;
    $product->save();
}

Two things worth noticing.

First, the comments are gone, and nothing is lost. The method names say the same thing, and unlike comments, method names don’t go out of date when someone changes the code.

Second, I kept the order of operations exactly the same. It’s tempting to “tidy up” the sequence while you’re in there. Don’t. The order of side effects is behavior, and we’re not changing behavior yet.

Tests: green. Commit. (Honestly, this could be three commits, one per extracted method. Smaller is better.)

Step 4: Flatten with guard clauses

applyExternalPrice has two levels of nesting. Guard clauses turn “if this, then if that, then do the thing” into “if not this, leave”:

private function applyExternalPrice(Order $order): void
{
    if ($order->product_id !== self::EXTERNALLY_PRICED_PRODUCT_ID) {
        return;
    }

    $priceResponse = Http::post('https://external-api.com/prices', [
        'product_id' => $order->product_id,
    ]);

    if (! $priceResponse->ok()) {
        return;
    }

    $order->external_price = $priceResponse->json('price');
}

private function applyExternalPrice(Order $order): void
{
    if ($order->product_id !== self::EXTERNALLY_PRICED_PRODUCT_ID) {
        return;
    }

    $priceResponse = Http::post('https://external-api.com/prices', [
        'product_id' => $order->product_id,
    ]);

    if (! $priceResponse->ok()) {
        return;
    }

    $order->external_price = $priceResponse->json('price');
}

I also snuck in a rename: $response became $priceResponse. In a controller that also returns an HTTP response, a variable called $response holding the response of a different HTTP call is a small trap. Renaming costs nothing and removes it.

Tests: green. Commit.

Step 5: The bug you’ll find along the way

Now look at the main method again, the way it reads after Step 3:

$order = $this->createPendingOrder($request, $user); // save() happens here

$this->applyPriority($order);
$this->applyExternalPrice($order);

$order = $this->createPendingOrder($request, $user); // save() happens here

$this->applyPriority($order);
$this->applyExternalPrice($order);

In the original 40-line method, this was easy to miss. Now it jumps out: the order is saved before priority and external price are set, and it’s never saved again.

That means priority and external_price never reach the database. The API response still says "priority": "high", because it reads the value from memory, not from the database. So the client is told one thing, and the database stores another.

This is the part nobody tells you about refactoring: making code readable is also how you find the bugs that were hiding in it.

And here’s the rule that matters: don’t fix it in the same commit. Everything up to now was a pure refactoring, with no behavior change. Fixing the bug is a behavior change. Keep them separate, so that if something downstream turns out to depend on the old behavior (it happens more often than you’d think), you can revert just the fix.

Before fixing, it’s worth a quick check with whoever owns this feature. Is there a report that treats null priority as normal? An admin screen that shows the priority? Five minutes of asking beats a surprised product manager.

Then the fix goes the proper way: red test first.

public function test_large_orders_are_stored_with_high_priority()
{
    Mail::fake();
    Http::fake();

    $this->actingAs(User::factory()->create());
    $product = Product::factory()->create(['stock' => 50]);

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

    $this->assertDatabaseHas('orders', [
        'product_id' => $product->id,
        'priority' => 'high',
    ]);
}

public function test_large_orders_are_stored_with_high_priority()
{
    Mail::fake();
    Http::fake();

    $this->actingAs(User::factory()->create());
    $product = Product::factory()->create(['stock' => 50]);

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

    $this->assertDatabaseHas('orders', [
        'product_id' => $product->id,
        'priority' => 'high',
    ]);
}

It fails. Good, that proves the bug is real. Now the fix, which after our refactoring is almost trivial: build the order first, save it once at the end.

$order = $this->buildPendingOrder($request, $user); // no save() inside anymore

$this->applyPriority($order);
$this->applyExternalPrice($order);

$order->save();

$order = $this->buildPendingOrder($request, $user); // no save() inside anymore

$this->applyPriority($order);
$this->applyExternalPrice($order);

$order->save();

Test: green. Commit, with a message that says what changed and why: Fix: persist order priority and external price.

Try making this fix in the original method. It’s doable, but you’d be moving a save() call around inside a wall of mixed concerns and hoping nothing else depended on it. After the refactoring, the fix is three lines and obviously correct.

Where to stop

The controller is still doing too much. It’s creating orders, calling an external API, sending email and managing stock. Stock updates aren’t atomic, and Product::find() can return null.

All true. None of it needs to be fixed today.

This is the point where you could move the logic into an action class (the fat controller article walks through that), or wrap the stock update in a transaction. But each of those is its own change, with its own tests and its own commit. Refactoring doesn’t have to end with a pattern. Sometimes the right move is to leave the code clearly better than you found it and go ship the feature you actually came here for.

Before and after

We started with one 40-line method full of comments explaining what it does. In the end, the main method reads top to bottom in ten seconds, and four small private methods with honest names do the actual work. In addition, the magic numbers are gone, a real bug is fixed, and the test suite grew from two tests to four. Above all, we didn’t need a single new class, interface or pattern.

A checklist for your next legacy refactoring

1. Make sure the behavior you’re touching is covered by tests. If it isn’t, write characterization tests first.
2. Replace magic numbers and strings with named constants.
3. Pull repeated calls into a single variable.
4. Turn comments into method names by extracting methods.
5. Flatten nested conditions with guard clauses.
6. Rename anything that could mislead the next reader.
7. When you find a bug, write it down, finish the refactoring, then fix it in a separate commit, test first.
8. Run the tests after every step. Commit after every step.
9. Stop when the code is clearly better, not when it’s perfect.

Legacy code rarely gets fixed in one heroic pull request. It gets fixed like this: one boring, safe, green step at a time.

The post Refactoring Legacy Laravel Code in Small, Safe Steps (With Real Examples) appeared first on CodeCraft Diary.

You read about Trunk-Based Development, continuous deployment, and decoupled releases. You wrap your new endpoint in an if (flags.isEnabled("new-checkout-v2")) block, merge it to main on a Tuesday morning, and release it to 5% of users. It works effortlessly. Rollbacks are no longer terrifying deploy pipelines; they are a simple toggle in a UI. You feel like an engineering deity.

Fast-forward twelve months.

Your codebase contains 214 feature flags. Nobody remembers who created enable-legacy-tax-calc-fix-final, whether temp-user-profile-v3 is fully rolled out, or why turning off test-dark-mode-override breaks authentication in the staging environment.

You haven’t built a modern, resilient continuous delivery system. You’ve built a dynamic, non-deterministic branching maze—a Feature Flag Graveyard.

          ┌──────────────────────────┐
          │   Feature Flag Created   │
          └────────────┬─────────────┘
                       │
          ┌────────────▼─────────────┐
          │  100% Rolled Out to Prod │
          └────────────┬─────────────┘
                       │
       ┌───────────────┴───────────────┐
       │                               │
┌──────▼──────┐                ┌───────▼───────┐
│ Cleaned Up  │                │   FORGOTTEN   │
└─────────────┘                └───────┬───────┘
                                       │
                         ┌─────────────▼──────────────┐
                         │ Dead Code, Dead Tests,     │
                         │ Exponential Combinatorics  │
                         └────────────────────────────┘

The Hidden Cost of “Toggle Bloat”

When teams talk about technical debt, they usually point to outdated libraries, missing unit tests, or monolithic classes. Feature flag debt is far more insidious because it masquerades as risk mitigation.

Here is what actually happens when flags are left to rot:

1. Exponential Combinatorial Explosion

If your order processing service has 10 active feature flags, you don’t have one code path to test. You have $2^{10} = 1,024$ potential system states running in production simultaneously.

No QA team or automated pipeline tests 1,000 combinations of code paths. Inevitably, a customer encounters a combination of flag states that no engineer has ever executed locally.

2. Cognitive Overhead & Architectural Degradation

Consider a simple backend service method after two years of uncleaned flags:

// A legacy nightmare hiding behind modern tooling
public async processPayment(order: Order): Promise<PaymentResult> {
  if (this.flags.isEnabled("use-stripe-v2")) {
    if (this.flags.isEnabled("bypass-fraud-check-beta")) {
      return this.stripeService.chargeFast(order);
    }
    return this.stripeService.chargeWithFraudCheck(order);
  } else {
    // Is anyone still hitting this branch? 
    // Is the legacy gateway even configured in production environment variables?
    return this.legacyGateway.charge(order);
  }
}

// A legacy nightmare hiding behind modern tooling
public async processPayment(order: Order): Promise<PaymentResult> {
  if (this.flags.isEnabled("use-stripe-v2")) {
    if (this.flags.isEnabled("bypass-fraud-check-beta")) {
      return this.stripeService.chargeFast(order);
    }
    return this.stripeService.chargeWithFraudCheck(order);
  } else {
    // Is anyone still hitting this branch? 
    // Is the legacy gateway even configured in production environment variables?
    return this.legacyGateway.charge(order);
  }
}

When a developer comes to refactor processPayment, they spend 80% of their time archaeology-ing flags: Can I delete this else block? Who owns use-stripe-v2? Is it 100% enabled in production?

Because nobody wants to break production, nobody touches it. The dead code remains forever.

3. The Knight Capital Disaster (At Micro-Scale)

In 2012, Knight Capital lost $440 million in 45 minutes due to a failed software deployment. The root cause? A repurposed feature flag.

They deployed new code that reused an old flag name, turning on obsolete, untested code on one of their servers. While your backend service might not lose half a billion dollars, executing a forgotten code path because someone toggled an abandoned flag in LaunchDarkly or Unleash will ruin your weekend just as effectively.

The Core Rule: A Feature Flag Is an Unpaid Loan

A feature flag is not a permanent architecture design pattern. It is financial debt with compounding interest.

Total Cost = Cost of Feature + Cost of Flag Cleanup

If you don’t budget time to remove the flag, you haven’t finished building the feature. You have merely pushed the labor cost onto future developers—usually with interest.

How to Prevent Your Codebase From Becoming a Graveyard

Solving flag debt isn’t a technical problem; it’s an operational discipline problem. Here are four practical patterns high-performing teams use to keep their flag count low:

1. Classify Flags by Lifetime

Not all flags are created equal. Treat them according to their actual intent:

Rule: 90% of your flags should be Release Flags. If a flag is meant for release safety, set an explicit expiration date on day one.

2. Make Flags Expire in CI/CD

Don’t rely on human memory to clean up code. Use your build pipeline to enforce cleanup:

• Stale Flag Alerts: Configure your flag management tool (Unleash, LaunchDarkly, ConfigCat) to notify Slack when a flag has been at 100% roll-out for more than 14 days.
• Failing Build Triggers: Some teams add metadata to flags in code:TypeScript// @FeatureFlag(owner: "team-checkout", expires: "2026-10-15") If a build runs past the expiration date and the flag is still in the codebase, the CI pipeline fails.

3. Pair Flag Creation with Cleanup Tickets

Whenever a developer opens a PR that introduces a new Release Flag, the definition of “Done” must require two artifacts:

1. The Jira/GitHub issue for the feature implementation.
2. A scheduled, prioritized cleanup ticket to delete the flag logic and test branches 2 weeks post-launch.

4. Continuous Refactoring Culture

Make flag removal a lightweight, ongoing task rather than a quarterly “hackathon” debt-clearing chore. Removing a fully rolled-out feature flag is usually a 5-minute task: delete the if/else, remove the obsolete test cases, and delete the key from your flag dashboard.

Conclusion: Clean Code Means Removing the Scaffolding

When builders construct a skyscraper, they use scaffolding to support the structure during assembly. Once the building stands on its own, they remove the scaffolding. Nobody leaves steel frameworks blocking the front entrance of a finished building.

Feature flags are modern software scaffolding. They allow us to move fast, test in production, and deploy without fear. But once your feature is live and stable, tear down the scaffolding.

Your future self—and your entire engineering team—will thank you.

The post The Feature Flag Graveyard: How a Safety Net Becomes Technical Debt appeared first on CodeCraft Diary.

When developers test time-dependent code, a common instinct is to use delay functions like sleep(). However, delaying test execution slows down Continuous Integration (CI) pipelines and introduces flakiness.

Testing time-based logic in PHP and Laravel does not require slowing down your test suite or manually altering system clocks. Laravel provides clear, expressive utilities to manipulate time, freeze moments, and verify scheduled tasks with precision.

+-----------------------------------------------------------------------+
|                         TIME-TESTING TOOLKIT                          |
+-----------------------------------------------------------------------+
|  Laravel Time Travel   -->  Jump forward or backward in time          |
|  Carbon Freeze         -->  Lock the clock at a specific moment       |
|  Schedule Testing      -->  Assert console commands fire correctly    |
+-----------------------------------------------------------------------+

Why Time-Dependent Tests Fail (And How to Fix Them)

Testing time logic without dedicated tools typically leads to two major issues:

1. Test Suite Sluggishness: Using sleep(5) to test a five-second expiration window forces your test runner to pause. Accumulated across a growing test suite, these delays significantly increase build times.
2. Intermittent Failures (Flakiness): Asserting that an action occurred exactly at now() can fail if CPU execution delays the assertion by even a few milliseconds.

To keep tests reliable and fast, tests must treat time as a controllable variable rather than an absolute constant.

Controlling Time with Laravel’s Travel Helpers

Laravel includes built-in time manipulation helpers accessible directly within test cases. Under the hood, these helpers interact with the Carbon library to modify the application’s perceived current time.

Traveling Into the Future

Consider a user model with a trial period expiring 14 days after registration:

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Support\Carbon;

class User extends Authenticatable
{
    public function hasActiveTrial(): bool
    {
        if ($this->trial_ends_at === null) {
            return false;
        }

        return Carbon::now()->lt($this->trial_ends_at);
    }
}

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Support\Carbon;

class User extends Authenticatable
{
    public function hasActiveTrial(): bool
    {
        if ($this->trial_ends_at === null) {
            return false;
        }

        return Carbon::now()->lt($this->trial_ends_at);
    }
}

To test whether the trial expires correctly after 14 days without waiting, use the $this->travel() helper:

namespace Tests\Feature;

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class TrialExpirationTest extends TestCase
{
    use RefreshDatabase;

    public function test_user_trial_expires_after_fourteen_days(): void
    {
        $user = User::factory()->create([
            'trial_ends_at' => now()->addDays(14),
        ]);

        // Assert trial is active initially
        $this->assertTrue($user->hasActiveTrial());

        // Travel 15 days into the future
        $this->travel(15)->days();

        // Assert trial is now expired
        $this->assertFalse($user->hasActiveTrial());
    }
}

namespace Tests\Feature;

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class TrialExpirationTest extends TestCase
{
    use RefreshDatabase;

    public function test_user_trial_expires_after_fourteen_days(): void
    {
        $user = User::factory()->create([
            'trial_ends_at' => now()->addDays(14),
        ]);

        // Assert trial is active initially
        $this->assertTrue($user->hasActiveTrial());

        // Travel 15 days into the future
        $this->travel(15)->days();

        // Assert trial is now expired
        $this->assertFalse($user->hasActiveTrial());
    }
}

Returning to Present Time

When manipulating time inside a test, restoring the original state prevents unexpected side effects in subsequent tests. Laravel automatically resets time between tests, but you can also manually restore it within a test block using $this->travelBack():

$this->travel(2)->hours();

// Perform assertions during modified time state...

$this->travelBack(); // Restores time to the actual current moment

$this->travel(2)->hours();

// Perform assertions during modified time state...

$this->travelBack(); // Restores time to the actual current moment

Freezing Time for Deterministic Assertions

In certain scenarios, moving forward relative to the current clock is insufficient. When tests require checking exact timestamp matching—such as created_at or published_at fields—freezing time at an explicit instance ensures complete determinism.

Using travelTo() and Carbon::freeze()

The $this->travelTo() method sets the application clock to a specific fixed point:

public function test_post_publishes_with_exact_timestamp(): void
{
    $knownDate = now()->setDate(2026, 5, 10)->setTime(14, 0, 0);

    // Freeze time at May 10, 2026 14:00:00
    $this->travelTo($knownDate);

    $post = \App\Models\Post::create([
        'title' => 'Testing Time in Laravel',
        'published_at' => now(),
    ]);

    $this->assertEquals('2026-05-10 14:00:00', $post->published_at->format('Y-m-d H:i:s'));
}

public function test_post_publishes_with_exact_timestamp(): void
{
    $knownDate = now()->setDate(2026, 5, 10)->setTime(14, 0, 0);

    // Freeze time at May 10, 2026 14:00:00
    $this->travelTo($knownDate);

    $post = \App\Models\Post::create([
        'title' => 'Testing Time in Laravel',
        'published_at' => now(),
    ]);

    $this->assertEquals('2026-05-10 14:00:00', $post->published_at->format('Y-m-d H:i:s'));
}

Alternatively, if you are working outside a standard Laravel TestCase or in a standalone PHP context, you can interact directly with Carbon’s underlying freeze method:

use Illuminate\Support\Carbon;

// Freeze clock at current moment
Carbon::setTestNow(now());

// Execute code requiring frozen time...

// Clear test time when finished
Carbon::setTestNow(null);

use Illuminate\Support\Carbon;

// Freeze clock at current moment
Carbon::setTestNow(now());

// Execute code requiring frozen time...

// Clear test time when finished
Carbon::setTestNow(null);

Scoped Time Manipulation with travelTo Closures

To ensure time manipulation is scoped strictly to a specific block of logic, pass a callback closure to travelTo(). This automatically restores the standard flow of time as soon as the closure finishes executing:

public function test_temporary_download_link_invalidation(): void
{
    $link = \App\Services\DownloadService::generateLink();

    $this->assertTrue($link->isValid());

    // Execute logic strictly 30 minutes in the future
    $this->travel(30)->minutes(function () use ($link) {
        $this->assertFalse($link->isValid());
    });

    // Time is automatically restored here
    $this->assertTrue(now()->isToday());
}

public function test_temporary_download_link_invalidation(): void
{
    $link = \App\Services\DownloadService::generateLink();

    $this->assertTrue($link->isValid());

    // Execute logic strictly 30 minutes in the future
    $this->travel(30)->minutes(function () use ($link) {
        $this->assertFalse($link->isValid());
    });

    // Time is automatically restored here
    $this->assertTrue(now()->isToday());
}

Testing Laravel Scheduled Tasks (Cron Jobs)

Managing scheduled tasks via app/Console/Kernel.php or routes/console.php is standard practice in Laravel applications. Verifying that scheduled commands execute at the correct time intervals should not require running full system cron daemons during testing.

Testing Schedule Execution with Event::fake() and Console Utilities

Suppose a clean-up task is scheduled to run daily at midnight:

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('prune:old-tokens')->dailyAt('00:00');

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('prune:old-tokens')->dailyAt('00:00');

To test that this command fires when midnight arrives, combine time travel with the Schedule facade assertions:

namespace Tests\Feature;

use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class ScheduleTest extends TestCase
{
    use RefreshDatabase;

    public function test_prune_tokens_command_is_scheduled_daily_at_midnight(): void
    {
        $schedule = $this->app->make(Schedule::class);

        // Freeze time at 23:59:00
        $this->travelTo(now()->setTime(23, 59, 0));

        $eventsAt2359 = collect($schedule->events())->filter(function ($event) {
            return $event->isDue($this->app);
        });

        // Command should NOT be due at 23:59
        $this->assertFalse(
            $eventsAt2359->contains(fn ($event) => str_contains($event->command, 'prune:old-tokens'))
        );

        // Travel 1 minute forward to 00:00
        $this->travel(1)->minute();

        $eventsAtMidnight = collect($schedule->events())->filter(function ($event) {
            return $event->isDue($this->app);
        });

        // Command SHOULD be due at 00:00
        $this->assertTrue(
            $eventsAtMidnight->contains(fn ($event) => str_contains($event->command, 'prune:old-tokens'))
        );
    }
}

namespace Tests\Feature;

use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class ScheduleTest extends TestCase
{
    use RefreshDatabase;

    public function test_prune_tokens_command_is_scheduled_daily_at_midnight(): void
    {
        $schedule = $this->app->make(Schedule::class);

        // Freeze time at 23:59:00
        $this->travelTo(now()->setTime(23, 59, 0));

        $eventsAt2359 = collect($schedule->events())->filter(function ($event) {
            return $event->isDue($this->app);
        });

        // Command should NOT be due at 23:59
        $this->assertFalse(
            $eventsAt2359->contains(fn ($event) => str_contains($event->command, 'prune:old-tokens'))
        );

        // Travel 1 minute forward to 00:00
        $this->travel(1)->minute();

        $eventsAtMidnight = collect($schedule->events())->filter(function ($event) {
            return $event->isDue($this->app);
        });

        // Command SHOULD be due at 00:00
        $this->assertTrue(
            $eventsAtMidnight->contains(fn ($event) => str_contains($event->command, 'prune:old-tokens'))
        );
    }
}

Key Best Practices for Time Testing

Conclusion

Time-dependent logic does not have to introduce unpredictability into your application’s test suite. By utilizing Laravel’s built-in time travel utilities, freezing Carbon instances, and evaluating scheduled events directly, you can write fast, reliable, and deterministic tests for any time-sensitive feature.

The post Testing Time and Scheduling in Laravel: Travel, Carbon Freeze, and Cron Tasks appeared first on CodeCraft Diary.

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

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

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

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

The Fallacy of the “Convenient” Model Scope

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

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

// App\Models\Customer.php

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

// App\Models\Customer.php

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

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

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

Enter Query Objects

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

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

Step 1: Extracting the Query to a Dedicated Object

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

namespace App\Queries;

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

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

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

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

namespace App\Queries;

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

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

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

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

Notice what changed here:

• Strict Encapsulation: The internal query construction (buildQuery()) is kept private. The outside world only receives the hydrated result (LengthAwarePaginator) via handle(), preventing callers from chaining arbitrary SQL downstream.

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

Step 2: Consuming Query Objects in Action Classes or Controllers

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

namespace App\Http\Controllers;

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

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

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

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

namespace App\Http\Controllers;

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

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

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

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

Repositories vs. Query Objects: Clearing the Confusion

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

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

Architectural Rule of Thumb:

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

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

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

When SHOULD You Still Use Local Query Scopes?

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

Good candidates for query scopes:

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

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

Key Takeaways for Your Codebase Today

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

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

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

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

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

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

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

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

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

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

The Four Myths of the “Identical” Staging Environment

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

1. The Data Drift Reality

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

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

2. Third-Party Sandboxes Are Half-Baked

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

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

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

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

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

4. The Maintenance Sinkhole

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

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

What Staging Is Actually Good For

None of this means staging environments are useless.

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

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

How Staging Bottlenecks Your Entire Workflow

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

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

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

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

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

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

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

Ephemeral (Preview) Environments

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

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

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

Progressive Delivery and Feature Flags

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

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

Observability and Fast Rollbacks

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

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

Stop Servicing the Mirage

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

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

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

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

CI is green.

Everyone merges their pull requests with confidence.

Then a seemingly harmless refactor breaks production.

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

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

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

Let’s look at the ones worth eliminating first.

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

1. Assertion Roulette

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

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

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

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

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

A better approach is giving each test a single responsibility.

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

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

Run on OnlinePHP.io

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

2. Mystery Guest

A test should be completely understandable on its own.

Unfortunately, many tests quietly depend on hidden data.

$user = User::find(1);

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

Where did user ID 1 come from?

Was it seeded?

Created by another test?

Imported from a dump?

Nobody knows.

This hidden dependency is known as the Mystery Guest smell.

Modern PHP testing tools make this easy to avoid.

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

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

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

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

Run on OnlinePHP.io

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

3. Fragile Assertions

Many tests verify far more than they actually need.

Imagine testing an API response.

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

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

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

Nothing is broken.

Your test still fails.

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

Instead, assert the behavior that actually matters.

For example, in Laravel:

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

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

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

Run on OnlinePHP.io

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

4. Duplicate Setup Everywhere

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

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

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

Repeat that fifty times and your tests become noisy.

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

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

The goal isn’t fewer lines of code.

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

5. Testing Implementation Instead of Behavior

This is probably the most expensive mistake teams make.

Imagine changing an internal algorithm.

The application still behaves exactly the same.

Users notice nothing.

Yet twenty tests suddenly fail.

Why?

Because they were testing implementation details rather than observable behavior.

A good test should answer:

“What should the application do?”

Not:

“How is the application currently doing it?”

Implementation changes happen constantly.

Business behavior should remain stable.

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

6. Hardcoded IDs and Magic Values

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

$user = User::find(42);

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

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

Six months later, someone changes the seed data.

Now the test mysteriously fails.

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

Prefer meaningful constants, enums, or freshly created models.

Your future self will thank you.

7. Logic Inside Tests

Tests should explain behavior.

They shouldn’t contain business logic themselves.

For example:

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

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

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

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

Instead, create separate test cases.

public function test_premium_users_receive_25_percent_discount()

public function test_regular_users_receive_10_percent_discount()

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

Simple tests communicate intent much better than clever ones.

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

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

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

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

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

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

// ❌ Slow

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

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

// ✅ Faster

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

    // Test only your application's behavior
}

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

A short PHP example demonstrating this test smell.

Run on OnlinePHP.io

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

9. Giant Tests That Verify Everything

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

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

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

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

    $response->assertCreated();

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

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

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

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

    Log::shouldHaveReceived('info');
}

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

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

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

10. Tests Nobody Trusts

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

Developers start saying things like:

“Oh, just rerun the pipeline.”

“That test always fails randomly.”

“Ignore that one.”

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

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

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

It has to be predictable.

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

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

Final Thoughts

Writing tests is only half the job.

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

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

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

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

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

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

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

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

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

$order->ship();

$order->ship();

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

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

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

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

Business Logic in Eloquent Models Is Not Automatically Wrong

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

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

A model should be allowed to answer questions about itself:

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

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

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

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

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

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

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

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

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

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

It is describing state versus coordinating work.

When a Model Starts Coordinating the Application

Consider a more ambitious implementation of ship():

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

That creates several practical problems.

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

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

Give the Workflow an Explicit Home

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

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

namespace App\Actions;

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

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

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

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

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

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

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

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

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

namespace App\Actions;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Avoid Building a Fat Action Instead

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

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

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

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

A Rule That Is Actually Useful

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

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

These methods usually fit naturally on a model:

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

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

These operations deserve closer inspection:

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

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

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

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

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

The models were never the real enemy.

The hidden workflows were.

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

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

It feels like Git is the problem.

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

Merge conflicts are rarely caused by Git itself.

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

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

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

Git Isn’t Creating the Conflict

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

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

Imagine two developers working on the same controller.

Developer A adds request validation.

Developer B changes the response format.

Both modify the same method.

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

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

The conflict isn’t a Git failure.

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

The Real Question Is: Why Did This Happen?

Whenever someone tells me:

“Git merge conflicts are driving me crazy.”

I usually ask one question.

How long was your branch open?

More often than not, the answer is:

• four days
• one week
• sometimes even three weeks

That’s usually where the real problem begins.

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

Someone renames classes.

Someone refactors a service.

Someone fixes a production bug.

Someone updates dependencies.

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

Git is simply the first tool to point that out.

The Hidden Cost Isn’t the Conflict

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

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

Understanding why the conflict exists is what costs time.

Imagine this situation.

You started a feature on Monday.

By Friday:

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

Now Git reports a conflict.

You’re no longer solving one conflict.

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

That’s the expensive part.

Large Pull Requests Multiply the Problem

One pattern appears almost everywhere.

Large pull requests almost always create larger merge conflicts.

It isn’t surprising.

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

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

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

Exactly.

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

Smaller changes don’t just make reviews easier.

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

Long-Lived Branches Drift Away From Reality

Feature branches aren’t the problem.

Long-lived feature branches are.

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

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

Developers spend hours:

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

Ironically, teams often conclude that merging is painful.

The truth is slightly different.

Merging became painful because they waited too long.

Communication Prevents More Conflicts Than Git Ever Will

Not every conflict can be avoided.

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

The difference is whether they know about each other.

Imagine this.

One developer is refactoring the authentication service.

Another developer is implementing passwordless login.

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

The conflict is inevitable.

Now imagine a five-minute conversation before they start.

“I’m working on AuthService this week.”

“Me too.”

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

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

Git could never solve that problem.

Trunk-Based Development Changes Everything

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

The goal isn’t to eliminate merge conflicts completely.

That’s impossible.

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

Instead of merging once every Friday…

…developers merge several times every day.

Instead of resolving fifty conflicts at once…

…they resolve one tiny overlap before lunch.

Small branches create small pull requests.

Small pull requests create small conflicts.

Small conflicts rarely interrupt development.

The Most Dangerous Conflicts Never Appear in Git

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

Imagine this scenario.

Developer A changes how discounts are calculated.

Developer B changes invoice generation.

Different files.

No merge conflict.

Everything merges perfectly.

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

Git couldn’t detect that.

The problem wasn’t textual.

It was logical.

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

How to Reduce Merge Conflicts

No workflow eliminates merge conflicts completely.

But a few simple habits make them significantly less painful.

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

None of these practices are revolutionary.

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

Stop Blaming Git

Git has become one of the easiest tools to blame.

It reports the conflict.

It highlights the differences.

It forces developers to make a decision.

But Git didn’t create the problem.

It simply revealed it.

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

“How can we get better at Git?”

Ask something much more valuable:

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

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

It’s hidden in the workflow.

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

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

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

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

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

The Problem with “Testing Too Much”

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

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

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

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

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

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

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

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

1. Unit Testing Listeners in Isolation

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. Handling Asynchronous Queues

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

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

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

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

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

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

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

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

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

4. Avoiding “The Silent Failure”

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

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

Testing Checklist for Events

To keep your test suite maintainable as your project grows:

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

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