Forem: CodeCraft Diary

Laravel Testing Mistakes That Make Your Tests Useless

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

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

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

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

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

1. Testing Implementation Instead of Behavior

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

Bad example

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

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

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

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

Better approach

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

    $response->assertStatus(201);

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

Focus on observable behavior, not internal calls.

2. Overusing Mocks

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

Problem

When everything is mocked:

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

Http::fake();

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

$response->assertStatus(200);

This tells you nothing about:

response structure
data correctness
edge cases

Better approach

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

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

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

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

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

3. Writing Tests That Always Pass

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

Example

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

    $response->assertStatus(200);
}

This test will pass even if:

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

Better approach

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

Or even better:

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

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

4. Ignoring Edge Cases

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

Common mistake

Only testing valid input:

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

Better approach

Test invalid scenarios:

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

Also test:

missing fields
duplicate values
unexpected input

Good tests try to break your application.

5. Testing Too Much in Unit Tests

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

Example

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

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

This mixes:

business logic
database layer

Better approach

Split responsibilities:

Unit test (logic only):

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

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

Feature test (full flow):

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

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

Keep your test layers clean.

6. Not Using Factories Properly

Laravel factories are powerful, but many developers misuse them.

Problem

Hardcoding everything:

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

Better approach

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

Even better:

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

Benefits:

less boilerplate
more flexible tests
easier maintenance

7. Not Cleaning Up Test Data

Dirty test data can cause flaky tests.

Problem

Tests depend on previous state.

Solution

Use:

use Illuminate\Foundation\Testing\RefreshDatabase;

This ensures:

clean DB for each test
consistent results

Flaky tests destroy trust in your test suite.

8. Writing Tests That Are Too Complex

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

Example

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

Better approach

Break it down:

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

Each test should answer one question.

9. Ignoring Performance

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

Problem

too many DB calls
unnecessary setup
heavy fixtures

Tips

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

Fast tests = tests you actually run.

10. Not Testing Real User Flows

Testing isolated pieces is not enough.

Problem

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

Example

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

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

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

Final Thoughts

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

If your tests:

only check status codes
mock everything
mirror your implementation

…then they’re not protecting your application.

Instead, focus on:

real behavior
meaningful assertions
edge cases
realistic user flows

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

Quick Checklist

Before committing a test, ask:

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

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

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

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

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

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

A controller starts small. Clean. Readable.

Then features get added.

Deadlines hit.

Logic piles up.

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

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

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

No theory overload. Just practical steps.

The Problem: A Real Fat Controller Example

Let’s start with something painfully familiar:

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

        // Business logic
        $total = 0;

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

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

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

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

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

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

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

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

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

What’s wrong here?

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

Goal: What “Clean” Looks Like

We want to move toward:

Thin controllers
Isolated business logic
Testable services
Clear boundaries between layers

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

Step 1: Extract Business Logic into a Service

First, move the core logic out of the controller.

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

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

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

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

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

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

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

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

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

        return $order;
    }
}

Controller becomes:

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

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

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

Improvement:

Controller is now thin
Logic is reusable
Easier to test

But we’re not done yet.

Step 2: Introduce a Data Transfer Object (DTO)

Passing raw arrays is fragile.

Let’s fix that.

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

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

Update controller:

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

Update service:

public function handle(CreateOrderData $data): Order

Improvement:

Stronger typing
Safer refactoring
Clear contract

Step 3: Decouple External Dependencies

Right now, your service is tightly coupled to:

Eloquent models
HTTP client

Let’s extract the webhook logic.

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

Inject it:

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

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

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

        return $order;
    }
}

Improvement:

External side effects are isolated
Easier to mock in tests

Step 4: Make It Testable

Now you can test the service independently:

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

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

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

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

Before refactoring, this would require:

HTTP mocking
Controller testing
Complex setup

Now it’s isolated.

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

Don’t overengineer this.

But if your app grows, you might extract:

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

Then inject it into the service.

When to do this:

Multiple data sources
Complex queries
Domain logic reuse

When NOT to:

Simple CRUD apps

Before vs After

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

Common Mistakes to Avoid

1. Moving everything blindly into services

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

Keep services focused.

2. Overengineering with too many layers

You don’t need:

10 interfaces
5 abstractions
enterprise architecture™

Start simple. Evolve when needed.

3. Ignoring boundaries

Controllers = HTTP
Services = business logic
Models = persistence

Mixing these again = back to chaos.

Key Takeaways

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

Final Thought

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

It means one thing:

Making your code easier to change without fear.

And the fastest way to get there?

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

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

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

That’s how clean architecture actually starts.

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

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

Trunk-Based Development sounds simple.

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

Most teams will tell you:

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

In practice, they don’t.

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

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

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

The Illusion of Trunk-Based Development

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

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

Sounds good.

But then you look closer:

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

This is not trunk-based development.

This is just shorter feature branches.

What Real Trunk-Based Development Actually Requires

Trunk-based development is not about branches.

It’s about integration frequency and safety.

At its core, it requires:

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

Without these, trunk-based development collapses.

Where Most Teams Break

1. Pull Requests Are Still Too Big

This is the biggest issue.

A developer starts a “small” feature:

adds endpoint
updates service
modifies database
adds validation
fixes something unrelated

Now the PR has:

15 files changed
600+ lines
multiple concerns

Review slows down. Feedback increases. Merge is delayed.

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

2. Code Reviews Block Integration

In theory:

“We merge frequently”

In reality:

“We merge when the PR gets approved”

That delay is critical.

If reviews take:

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

Now developers start stacking changes on top of each other.

And suddenly:

branches live longer
PRs get bigger
merges become risky

3. Teams Are Afraid to Merge Incomplete Work

This is subtle but important.

Developers often think:

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

So they keep working on the branch.

The problem:

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

Trunk-based development requires a different mindset:

You merge incomplete work safely.

The Missing Piece: Feature Flags

Most teams skip this.

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

Example

You’re building a new payment flow.

Without feature flags:

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

With feature flags:

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

Now you can:

merge partial work
deploy continuously
control exposure

Real Example From Practice

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

Metrics looked like this:

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

After digging in, the issue was clear:

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

What changed

We introduced 3 rules:

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

Result after ~3 weeks:

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

Not because developers got better.

Because the system changed.

The Hidden Constraint: CI/CD Speed

Here’s something teams often ignore:

You cannot do trunk-based development with slow pipelines.

If your CI takes:

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

So what happens?

developers batch changes
PRs get bigger
integration slows down

Rule of thumb (2026 reality):

CI under 10 minutes → good
under 5 minutes → ideal

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

Why This Matters More in 2026

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

That creates a new problem:

volume of changes increases
but review capacity doesn’t

If you don’t enforce:

small changes
fast integration
clear boundaries

your workflow collapses under its own weight.

How to Tell If You’re Actually Doing It

Be honest and check:

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

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

Practical Rules You Can Apply Tomorrow

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

1. Limit PR size

Not as a guideline — as a rule.

2. Optimize for review speed

fewer changes
clearer intent
less context switching

3. Introduce feature flags

Without them, you’re stuck.

4. Fix your CI/CD bottlenecks

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

5. Stop batching work

Batching feels efficient.
It’s not.

Closing Thought

Trunk-based development is not a branching strategy.

It’s a discipline.

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

If your:

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

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

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

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

Laravel Testing: RefreshDatabase vs DatabaseTransactions (What Actually Matters)

CodeCraft Diary — Tue, 31 Mar 2026 13:00:00 +0000

Laravel RefreshDatabase vs DatabaseTransactions is one of the most common sources of confusion when writing tests in Laravel.

Choosing the wrong approach can lead to flaky tests, hidden bugs, and unreliable results.

When writing tests in Laravel, database state can quickly become a source of confusion.

One test passes, another fails. Data seems to “leak” between tests. Records appear when they shouldn’t — or disappear when you expect them to exist.

If you’ve experienced this, you’re not alone.

In most cases, the issue comes down to how your tests handle the database. Laravel provides two primary approaches for this:

RefreshDatabase
DatabaseTransactions

At first glance, they seem similar. In reality, they behave very differently — and choosing the wrong one can lead to subtle bugs or false confidence in your test suite.

Understanding the Core Problem

Tests must be isolated.

Each test should run independently, without being affected by previous tests.

If your database is not reset properly between tests:

data can persist unexpectedly
test results become unreliable
debugging becomes painful

Laravel solves this problem using two strategies:

Reset the database completely
Wrap each test in a transaction and roll it back

Option 1: RefreshDatabase

use Illuminate\Foundation\Testing\RefreshDatabase;

class UserTest extends TestCase
{
    use RefreshDatabase;
}

How it works

Runs migrations before tests
Ensures a clean database state
Uses transactions internally when possible

Advantages

High reliability
Works with queues, jobs, events
Predictable behavior

Disadvantages

Slower
Heavier setup

Option 2: DatabaseTransactions

use Illuminate\Foundation\Testing\DatabaseTransactions;

class UserTest extends TestCase
{
    use DatabaseTransactions;
}

How it works

Starts a database transaction before each test
Rolls it back after the test finishes

Advantages

Fast
Lightweight

Disadvantages
Does NOT work well with queues or async processes
Can lead to hidden inconsistencies

When to Use Each

Use RefreshDatabase when:

testing queues or jobs
working with multiple DB connections
you need maximum reliability

Use DatabaseTransactions when:

testing simple DB logic
performance is critical
everything runs in one request lifecycle

Where Things Break in Real Projects

This is where most developers run into problems.

Especially when:

jobs don’t see database data
tests pass locally but fail in CI
retries cause unexpected behavior

-> I go deeper into real-world failures, debugging strategies, and edge cases here:

-> https://codecraftdiary.com/2026/03/28/laravel-refreshdatabase-vs-databasetransactions/

TL;DR

Use RefreshDatabase for reliability
Use DatabaseTransactions for speed
Avoid mixing both
Be careful with queues and async behavior

If you're working with Laravel testing, you might also find useful:

Queue testing pitfalls
-> https://codecraftdiary.com/2026/03/08/laravel-queue-testing-jobs-retries/
Feature testing in PHP
-> https://codecraftdiary.com/2025/10/30/feature-testing-in-php-ensuring-the-whole-system-works-together/

AI-Driven Refactoring in PHP: When to Trust Copilot (and When to Take the Wheel)

CodeCraft Diary — Tue, 24 Mar 2026 14:00:00 +0000

In 2026, the biggest performance gains in PHP don’t come from micro-optimizations—they come from I/O strategy.

Legacy PHP codebases (5–10 years old) are overwhelmingly synchronous and blocking. Refactoring them toward concurrency—using Fibers with an event loop like Revolt, Amp, or ReactPHP—can unlock massive gains.

But this is also where AI tools like Copilot become dangerous.

They can accelerate the refactor—or quietly corrupt your architecture.

Previous article in this category: https://codecraftdiary.com/2026/02/28/singleton-pattern-in-php/

The “Prompt–Refactor–Verify” Cycle

When working with AI, the difference between success and subtle bugs is prompt precision.

Bad prompt:

“Make this async.”

Good prompt:

“Identify I/O-bound operations. Refactor using Fibers with an event loop (Revolt/Amp). Avoid shared mutable state. Ensure deterministic completion.”

If you paste a 500-line method without context, AI will:

miss hidden dependencies
ignore state coupling
introduce non-obvious bugs

AI is a transformer, not a system thinker.

Real-World Example: Legacy Image Processor

Before (typical legacy flow)

foreach ($urls as $url) {
    $image = $this->download($url);   // blocking
    $resized = $this->resize($image); // CPU
    $this->upload($resized);          // blocking
}

Simple. Predictable. Slow.

After (controlled concurrency with Amp)

use Amp\Future;
use function Amp\async;

$tasks = [];

foreach ($urls as $url) {
    $tasks[] = async(function () use ($url) {
        $image = $this->download($url);   // non-blocking if using async client
        $resized = $this->resize($image);
        return $this->upload($resized);
    });
}

$results = Future\awaitAll($tasks);

What changed?

I/O is now concurrent
Execution is interleaved, not parallel threads
The bottleneck shifts from waiting → throughput

The AI Trap: “It Works” ≠ “It’s Safe”

AI often produces code that looks correct and even passes tests.

But there are hidden risks.

Shared State Issues

This is dangerous:

$this->processedUrls[] = $result;

Not because PHP is multithreaded—but because:

execution is interleaved
order is no longer deterministic
side effects accumulate unpredictably

Fix:

return values → aggregate later
avoid mutation inside async tasks

2. The “AI Echo Chamber”

One of the most dangerous patterns:

AI writes a bug → AI writes a test → test passes

Example:

// Bug: returns null on failure
return $result ?? null;

AI-generated test:

expect($service->process())->toBeNull();

Everything is green. Everything is wrong.

3. “Happy Path” Bias

AI prefers:

try {
    ...
} catch (\Throwable $e) {
    return null;
}

In production systems, this is data loss.

Senior-level expectation:

explicit exceptions
domain-level error handling

Preventing Architecture Drift

The biggest long-term risk isn’t bugs.

It’s inconsistency.

You refactor:

Class A on Monday
Class B on Tuesday

By Friday:

patterns diverge
abstractions don’t align

Why?

Because AI only sees the current file, not your system.

The “Constraint Header” Strategy

Before any refactor, define rules:

Context:

Strict types only
No direct DB calls (Repository pattern)
Async only via Amp
Immutable DTOs

Task:
Refactor InvoiceGenerator

This reduces:

random design decisions
pattern drift
“AI creativity” in critical code

Killing the “God Constructor”

Legacy PHP often looks like this:

public function __construct(
    Logger $logger,
    Mailer $mailer,
    Cache $cache,
    PaymentGateway $gateway,
    ...
) {}

AI’s default move:
→ add another dependency

Wrong direction.

Refactoring toward composition

final class OrderProcessor
{
    public function __construct(
        private PaymentGateway $gateway,
        private Notifier $notifier,
    ) {}    public function process(Order $order): void
    {
        match ($order->status) {
            Status::Pending => $this->gateway->charge($order),
            Status::Paid => throw new AlreadyPaidException(),
            default => throw new \UnhandledMatchError(),
        };        $this->notifier->notify("Order {$order->id} processed");
    }
}

Key idea:

fewer responsibilities per class
clearer boundaries
easier testing

Hallucinated APIs: The “Ghost Methods” Problem

AI sometimes invents functions that sound correct:

array_first_key($array); // ❌ does not exist

Rule:

If you don’t recognize it, verify it.

Ask:

“Which PHP version introduced this?”
“Show official docs”

No answer → hallucination.

The Hidden Cost: AI-Grown Code

If AI writes most of your refactoring:

code becomes harder to reason about
intent disappears
onboarding slows down

Countermeasure:

Ask AI:

“Explain why this design was chosen over a simpler alternative.”

If the answer is vague → the design is weak.

Reviewing AI Code Like a Senior

Static analysis won’t save you.

Tools like PHPStan check correctness—not intent.

What to actually review

1. Semantic correctness
Did we simplify—or just move complexity?

2. Concurrency safety

hidden state mutation
ordering assumptions
error propagation

3. Edge cases

Ask AI explicitly:

“Simulate a timeout during async execution. What breaks?”

The 2026 Refactoring Checklist

Before merging:

Type safety → strict, explicit
No hidden shared state
Async is intentional (not accidental)
Dependencies are minimal and meaningful
Errors are explicit (no silent nulls)
You can explain every change

If not:

→ don’t merge it

Final Thoughts

AI is an accelerator—but also a multiplier of mistakes.

It tends to:

add complexity
over-engineer
hide intent

Your role is no longer just writing code.

It’s curating it.

The real senior skill in 2026 is knowing when to say:

“This is too clever. Make it simple.”

Because great refactoring isn’t about adding concurrency.

It’s about removing everything that doesn’t need to be there.

Small Pull Requests: Why They Move Development Teams Faster

CodeCraft Diary — Tue, 17 Mar 2026 14:00:00 +0000

In many backend teams, pull requests slowly grow into something nobody wants to review.

A developer starts working on a feature.
At first, it’s just a small change — maybe a new endpoint or a service update.

Soon another improvement gets added.

A small refactor follows.

Finally, a fix for something unrelated appears.

Two days later, the pull request contains 900 lines of changes across 14 files.

At that moment, something predictable happens.

The review slows down.

Not because the reviewers are lazy — but because large pull requests create cognitive overload.

And once reviews slow down, the entire development workflow begins to lose momentum.

Previous article in this category: https://codecraftdiary.com/2026/02/21/why-just-one-more-quick-fix/

The Psychological Problem of Large Pull Requests

Large pull requests create a subtle psychological effect.

When a reviewer opens a PR and sees:

+824 −217 changes

their brain immediately categorizes it as expensive work.

The result is predictable:

The review gets postponed.
The reviewer waits for “more time”.
The PR sits for hours or days.

Eventually, when someone finally reviews it, they cannot realistically analyze everything in depth.

So one of two things happens:

The reviewer skims the code and approves it quickly.
The reviewer leaves many comments that trigger long discussion threads.

Neither outcome improves delivery speed.

Small Pull Requests Change the Dynamic

Now compare that to a PR that looks like this:

+42 −8 changes

This feels manageable.

A reviewer can realistically read the entire diff in a few minutes.

This leads to several important effects:

1. Faster Reviews

Small PRs get reviewed faster simply because they feel easier.

Many teams see review times drop from days to hours after adopting smaller pull requests.

2. Better Feedback

When the code is smaller, reviewers can focus on design decisions instead of scanning files.

Instead of writing comments like:

“This file changed a lot, can you explain the logic?”

they can ask more meaningful questions:

“Should this logic live in the service layer instead?”

3. Less Risk

Large pull requests often hide bugs.

For example, reviewers may miss subtle mistakes when hundreds of lines change at once.

Small PRs isolate changes.

If a bug appears, it’s easier to trace it back to a specific change.

A Practical Example

Consider a backend developer implementing a new feature:

Send notification emails when an order is shipped.

A typical large PR might include:

database migration
new notification service
email template
queue job
controller changes
unit tests
refactoring an old helper

All combined into one big pull request.

Instead, this can be split into several smaller ones.

PR 1 – Database Migration

Add shipped_at column to orders table

Simple schema change.

PR 2 – Notification Service

Create OrderShipmentNotifier service

Pure backend logic.

PR 3 – Queue Job

Add SendShipmentEmail job

Background processing.

PR 4 – Controller Integration

Trigger notification when order is shipped

Integration step.

Each PR becomes reviewable within minutes.

The entire feature moves through the pipeline much faster.

The Hidden Benefit: Continuous Integration

Small pull requests also improve CI pipelines.

Large PRs often cause several problems:

When a small PR fails CI, the cause is usually obvious.

Example:

PR title: Add OrderShipmentNotifier service
CI failure: NotificationServiceTest fails

The fix is straightforward.

Compare this to a massive PR with dozens of changes — the failure may come from anywhere.

Why Developers Resist Small Pull Requests

Despite the benefits, many developers hesitate to split their work.

Common reasons include:

“The feature isn’t finished yet.”

This is the most common argument.

But many PRs do not need to represent a finished feature.

They only need to represent a safe incremental step.

For example:

You can merge a service class before it’s used anywhere.

That’s perfectly valid.

“It creates too many PRs.”

This concern sounds logical but rarely holds in practice.

Ten small PRs usually move through the system faster than one large one.

Why?

Because multiple reviewers can process them quickly instead of blocking on one huge change.

“It’s extra work.”

At first, splitting work into smaller PRs requires discipline.

But after a few weeks, it becomes natural.

Developers start thinking in incremental changes rather than large feature drops.

A Simple Rule That Works

Some teams use a simple heuristic:

If a pull request takes more than 10 minutes to review, it is probably too large.

This isn’t a strict rule, but it works surprisingly well.

Another guideline:

200–300 lines of diff should usually be the upper limit.

Beyond that, review quality drops quickly.

The Long-Term Impact on Workflow

When teams consistently use small pull requests, several improvements appear over time.

The pipeline becomes predictable

PRs move steadily through the system instead of forming large queues.

Developers ship code more often

Frequent merges reduce integration conflicts.

Code reviews become collaborative

Instead of being a bottleneck, reviews become quick feedback loops.

And perhaps most importantly:

The team starts focusing on continuous delivery instead of large feature dumps.

Final Thought

Many teams try to improve their development workflow by introducing new tools, processes, or complex CI pipelines.

But one of the most effective improvements is surprisingly simple:

Keep pull requests small.

Small pull requests reduce friction in every stage of development:

code review
testing
debugging
merging

They allow teams to maintain momentum — and momentum is often the most valuable resource in software development.

Laravel Queue Testing: What Most Developers Get Wrong

CodeCraft Diary — Tue, 10 Mar 2026 14:00:00 +0000

Queues are where “it works on my machine” quietly turns into production incidents.

Emails are sent in the background.
Invoices are generated asynchronously.
External APIs are called outside the request lifecycle.
Data synchronization runs in workers you don’t actively watch.

Laravel makes queues extremely easy to use. Add ShouldQueue, dispatch the job, done.

Testing them properly is a different story.

Most developers stop at:

Bus::fake();
Bus::assertDispatched(SyncOrderJob::class);

That verifies wiring. It does not verify behavior.

This article focuses on how to test Laravel jobs correctly — including idempotency, failure handling, and retry safety — with a realistic example.

Previous article in this category: https://codecraftdiary.com/2026/02/14/contract-testing-external-apis-in-php-with-pact-real-laravel-example/

The Scenario: Syncing an Order to an External API

Let’s say we have an Order model that needs to be synchronized to an external system after checkout.

The Job

namespace App\Jobs;use App\Models\Order;
use App\Services\OrderApiClient;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;class SyncOrderJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, SerializesModels;    public int $tries = 3;    public function __construct(
        public Order $order
    ) {}    public function handle(OrderApiClient $client): void
    {
        if ($this->order->synced_at !== null) {
            return; // idempotency guard
        }        $client->send([
            'id' => $this->order->id,
            'total' => $this->order->total,
        ]);        $this->order->update([
            'synced_at' => now(),
        ]);
    }
}

Already we have several important concerns:

The job must not sync twice.

It depends on an external API client.
It may be retried.
It mutates persistent state.

Let’s test it properly

1. Testing Dispatch (Integration Level)

This belongs in a feature test.

use Illuminate\Support\Facades\Bus;
use App\Jobs\SyncOrderJob;

public function test_order_dispatches_sync_job()
{
    Bus::fake();

    $order = Order::factory()->create();

    $order->markAsPaid(); // imagine this dispatches the job

    Bus::assertDispatched(SyncOrderJob::class, function ($job) use ($order) {
        return $job->order->is($order);
    });
}

Good. Necessary.

But insufficient.

This does not test handle() at all.

2. Testing Job Logic Directly (Unit Level)

Now we test the job itself.

We do not fake the bus.
We instantiate the job and call handle() directly.

Mocking the External API

use App\Services\OrderApiClient;
use Mockery;

public function test_it_calls_external_api_when_not_synced()
{
    $order = Order::factory()->create([
        'synced_at' => null,
    ]);    

    $mock = Mockery::mock(OrderApiClient::class);

    $mock->shouldReceive('send')
        ->once()
        ->with(Mockery::on(fn ($payload) => $payload['id'] === $order->id));    

    $job = new SyncOrderJob($order);    

    $job->handle($mock);
}

This verifies real behavior.

We are not testing Laravel.
We are testing our business logic.

3. Testing Idempotency

Queues retry automatically. If your job is not idempotent, you will create duplicate side effects.

public function test_it_does_not_call_api_if_already_synced()
{
    $order = Order::factory()->create([
        'synced_at' => now(),
    ]);    

    $mock = Mockery::mock(OrderApiClient::class);

    $mock->shouldNotReceive('send');    

    $job = new SyncOrderJob($order);    

    $job->handle($mock);
}

If this test fails, your production system will eventually duplicate work.

4. Testing Retry Safety

Consider a failure between the API call and the database update.

If the job crashes after calling the API but before marking the order as synced, retry will send it again.

Safer pattern:

public function handle(OrderApiClient $client): void
{
    if ($this->order->synced_at !== null) {
        return;
    }    $this->order->update([
        'synced_at' => now(),
    ]);    $client->send([
        'id' => $this->order->id,
        'total' => $this->order->total,
    ]);
}

Now state changes before side effects.

Let’s simulate a failure.

public function test_it_retries_safely()
{
    $order = Order::factory()->create([
        'synced_at' => null,
    ]);

    $mock = Mockery::mock(OrderApiClient::class);
    $mock->shouldReceive('send')
        ->once()
        ->andThrow(new RuntimeException());

    $job = new SyncOrderJob($order);

    try {
        $job->handle($mock);
    } catch (RuntimeException $e) {
        // expected
    }

    $order->refresh();

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

Now even if retry happens, the idempotency guard prevents double execution.

This is not theoretical. This is how duplicate invoices happen.

5. Testing Jobs That Dispatch Other Jobs

Chained or nested jobs add complexity.

ProcessPaymentJob::dispatch($order);
SendInvoiceJob::dispatch($order);

To test that correctly:

Bus::fake();

$job = new ProcessPaymentJob($order);

$job->handle($paymentService);

Bus::assertDispatched(SendInvoiceJob::class);

Notice the difference:

We test handle() directly.
We fake the bus only to assert nested dispatch.

That separation is critical.

6. Testing Backoff and Retry Configuration

Laravel allows configuration:

public int $tries = 5;

public function backoff(): array
{
    return [10, 30, 60];
}

You can test configuration explicitly:

public function test_job_has_correct_retry_settings()
{
    $job = new SyncOrderJob(Order::factory()->make());

    $this->assertEquals(3, $job->tries);
}

Not glamorous — but configuration errors cause real outages.

7. The Dangerous Anti-Pattern

This is common:

Queue::fake();

SyncOrderJob::dispatch($order);

Queue::assertPushed(SyncOrderJob::class);

This test will pass even if:

The job throws immediately.
The API client is broken.
The logic is inverted.
Idempotency is missing.
The job deletes the order by accident.

You tested dispatch, not behavior.

When to Use Bus::fake() vs Real Execution

Use Bus::fake() when:

Testing controllers or services that dispatch jobs.
Verifying orchestration.
Ensuring a job is queued under certain conditions.

Do not use Bus::fake() when:

Testing job business logic.
Testing external integration behavior.
Testing failure handling.

In job tests, instantiate and call handle() directly.

Advanced: Running Jobs Synchronously in Tests

Laravel allows:

config(['queue.default' => 'sync']);

This executes jobs immediately.

Useful for feature tests where:

You want full behavior executed.
You don’t care about queue infrastructure.

But be careful:

If you rely on sync execution everywhere, you may miss race conditions or retry issues.

Design Principles for Testable Jobs

If your job is hard to test, it’s usually poorly designed.

Good Laravel jobs:

Inject services via handle().
Keep constructors lightweight.
Avoid heavy logic in __construct.
Avoid static service calls.
Are idempotent by design.
Fail loudly.

Bad Laravel jobs:

Call Http::post() directly inside handle.
Query models statically without abstraction.
Mutate global state.
Swallow exceptions silently.

Testing reveals architecture quality.

Final Thoughts

Queues introduce three new axes of complexity:

Time (execution is delayed)
Failure (automatic retries)
Concurrency (multiple workers)

Testing Laravel jobs properly means:

Testing dispatch at feature level.
Testing handle() directly at unit level.
Mocking external services.
Verifying idempotency.
Simulating failure.
Thinking explicitly about retry safety.

Queues scale your application.

Tests make your background processing reliable.

Singleton Pattern in PHP: Refactoring Global State the Right Way

CodeCraft Diary — Tue, 03 Mar 2026 14:00:00 +0000

In many legacy PHP codebases, global state sneaks in quietly.
A config.php file is included everywhere.
A static helper class grows until it becomes a god object.
A database connection lives in a global variable “just for now”.

At first, it feels convenient.
Later, it becomes untestable, unpredictable, and painful to change.

Let’s look at how global state often appears in PHP projects, how developers usually try to “fix” it, and how refactoring toward a Singleton can help — but also why Singleton is frequently misused.

Previously article in this category: https://codecraftdiary.com/2026/02/07/builder-pattern-in-php/

The Code Smell: Hidden Global State

A typical example:

// config.php
return [
    'db_host' => 'localhost',
    'db_user' => 'root',
    'db_pass' => 'secret',
];

// bootstrap.php
$config = require 'config.php';

// UserRepository.php
class UserRepository
{
    public function find(int $id): array
    {
        global $config;        $conn = new PDO(
            'mysql:host=' . $config['db_host'],
            $config['db_user'],
            $config['db_pass']
        );        return $conn->query('SELECT * FROM users WHERE id = ' . $id)->fetch();
    }
}

This code “works”.
It also hides a dependency.

UserRepository depends on configuration and a database connection, but nothing in its API communicates that. The dependency is invisible and implicit.

This leads to:

unpredictable behavior in tests
coupling between unrelated parts of the system
accidental mutation of shared state
code that is hard to reason about

This is a classic code smell: hidden dependencies via global state.

The Naive Fix: Static Helper Class

The next evolutionary step in many PHP projects looks like this:

class Config
{
    private static array $data;    public static function load(): void
    {
        self::$data = require 'config.php';
    }    public static function get(string $key): mixed
    {
        return self::$data[$key];
    }
}

class UserRepository
{
    public function find(int $id): array
    {
        $conn = new PDO(
            'mysql:host=' . Config::get('db_host'),
            Config::get('db_user'),
            Config::get('db_pass')
        );        return $conn->query('SELECT * FROM users WHERE id = ' . $id)->fetch();
    }
}

This looks cleaner:

no global
no messy includes
centralized config access

But architecturally, nothing really improved.

This is still:

global state
hidden dependency
impossible to replace in tests
tightly coupled to a static API

We replaced global with a static singleton-like façade.

This is not refactoring.
This is just changing syntax.

Refactoring Toward a Real Singleton

Let’s refactor this step by step into a proper Singleton.

final class Config
{
    private static ?Config $instance = null;
    private array $data;    private function __construct()
    {
        $this->data = require 'config.php';
    }    public static function getInstance(): Config
    {
        if (self::$instance === null) {
            self::$instance = new Config();
        }        return self::$instance;
    }    public function get(string $key): mixed
    {
        return $this->data[$key] ?? null;
    }
}

Usage:

class UserRepository
{
    public function find(int $id): array
    {
        $config = Config::getInstance();        $conn = new PDO(
            'mysql:host=' . $config->get('db_host'),
            $config->get('db_user'),
            $config->get('db_pass')
        );        return $conn->query('SELECT * FROM users WHERE id = ' . $id)->fetch();
    }
}

This is now a “proper” Singleton:

private constructor
lazy initialization
controlled access point

We improved:

structure
encapsulation
testability (slightly)

But we did not fix the core design issue.

The dependency is still hidden.

The Real Problem: Singleton Is Global State in Disguise

A Singleton is not dependency injection.
It is global state with better manners.

You still cannot:

pass different configurations in tests
swap implementations easily
reason locally about dependencies

From an architectural perspective, UserRepository still depends on Config, but that dependency is invisible in its constructor or method signature.

This creates tight coupling and invisible control flow.

The code is cleaner — but not better designed.

When Singleton Is Actually Legitimate

Singleton is not evil by definition.
It is evil when used as a default container for everything.

Legitimate use cases in PHP:

1. Immutable Application Configuration

final class AppConfig
{
    private static ?AppConfig $instance = null;
    private array $values;    private function __construct(array $values)
    {
        $this->values = $values;
    }    public static function boot(array $values): void
    {
        self::$instance = new self($values);
    }    public static function getInstance(): AppConfig
    {
        return self::$instance;
    }    public function get(string $key): mixed
    {
        return $this->values[$key] ?? null;
    }
}

Bootstrapped once, read-only afterwards.

2. Logger

A logger is often a cross-cutting concern:

shared
stateless
global by nature

3. Feature Flags / Environment Context

If the state is:

immutable
read-only
environment-level

Singleton can be acceptable.

When Singleton Is a Design Smell

Singleton becomes a problem when:

it contains mutable domain state
it replaces proper dependency injection
it hides real architectural boundaries
it becomes a service locator
business logic starts living inside it

If your Singleton has:

20 methods
multiple responsibilities
domain logic

…you created a god object with a private constructor.

A Better Refactoring Path

Often, Singleton should be treated as a transitional refactoring step, not a final architecture.

Better end state:

class UserRepository
{
    public function __construct(
        private PDO $connection
    ) {}    public function find(int $id): array
    {
        return $this->connection
            ->query('SELECT * FROM users WHERE id = ' . $id)
            ->fetch();
    }
}

And composition happens at the boundary of the application:

$config = Config::getInstance();$pdo = new PDO(
    'mysql:host=' . $config->get('db_host'),
    $config->get('db_user'),
    $config->get('db_pass')
);$repo = new UserRepository($pdo);

Now:

dependencies are explicit
testing is trivial
coupling is controlled
architecture is visible

Conclusion

Singleton is not a goal.
It is a compromise.

It can be a useful refactoring step when removing global state from a legacy PHP codebase.
It can make dependencies slightly more explicit.
It can improve encapsulation.

But if you stop there, you only replaced chaos with a nicer-looking global variable.

Good design does not start with patterns.
It starts with making dependencies explicit and pushing composition to the edges of your system.

Singleton is a tool.
Use it deliberately — and sparingly.

Why “Just One More Quick Fix” Destroys Your Delivery Pipeline

CodeCraft Diary — Tue, 24 Feb 2026 14:00:00 +0000

Every development team has heard this sentence:

“Let’s just push one more quick fix.”

It sounds harmless. Responsible, even. Something small broke, a customer is affected, production is slightly off — and the fix is obvious. Five minutes of work. No need to go through the full process. No need to wait for code review. No need to bother QA. Just one tiny change to keep things moving.

The problem is not the quick fix itself.
The problem is the culture that grows around it.

Over time, “just one more quick fix” becomes the default way changes enter production. And once that happens, your delivery pipeline slowly collapses — not because anyone is incompetent, but because the system you built to protect quality gets bypassed piece by piece.

Previous article in this category: https://codecraftdiary.com/2026/01/31/why-almost-done-work-breaks-development-flow/

How Quick Fixes Become the Normal Path to Production

Most teams don’t start with bad intentions. The first few quick fixes usually happen under real pressure:

A critical bug blocks a customer.
A payment fails.
An integration with a third-party API breaks overnight.
A configuration mistake takes down part of production.

At this stage, bypassing the process feels justified. You skip review because “it’s just a one-line change.” You deploy manually because the CI pipeline takes too long. You test in production because the bug only reproduces there.

Nothing explodes. The fix works. The customer is happy. The team moves on.

That success teaches the wrong lesson.

The next time something small breaks, the team remembers:
“We fixed it quickly last time. Let’s do it the same way.”

After a few months, you end up with two delivery paths:

The official pipeline: PR → review → tests → CI → deploy
The real pipeline: Slack message → quick commit → direct deploy

The second one becomes the faster, socially accepted option. The first one starts to feel like bureaucracy.

The Hidden Damage: You Don’t See the Cost Immediately

The real damage of quick fixes is not in the individual changes. It’s in what they do to your system over time.

1. Your CI Pipeline Stops Being Trustworthy

Once people regularly bypass CI, the pipeline stops reflecting reality. Builds fail for reasons nobody prioritizes fixing. Tests become flaky and get ignored. Warnings pile up.

Eventually, developers stop trusting the pipeline at all.

At that point, CI is no longer a quality gate — it’s just a ritual.
Teams running on platforms like GitHub or GitLab often reach this state not because the tools are bad, but because the workflow culture quietly degrades around them.

2. Code Reviews Become Optional (Which Means Useless)

When urgent fixes bypass review, reviews lose their authority. Review becomes something you do for “normal work,” while “important work” skips it.

That’s a subtle but dangerous shift.

You’re effectively teaching the team that quality checks are less important when stakes are higher. Over time, this creates blind spots exactly where you need discipline the most: production-critical paths.

3. You Normalize Risk Without Noticing

Every quick fix that works without immediate consequences normalizes risk-taking:

Deploying without review becomes acceptable.
Deploying without tests becomes acceptable.
Deploying without understanding side effects becomes acceptable.

The absence of incidents is interpreted as proof that the process is unnecessary — until the day it fails in a way that costs real money, data, or trust.

By the time that incident happens, the delivery pipeline is already too eroded to protect you.

The Psychological Trap: Quick Fixes Feel Like Ownership

Quick fixes often feel good on a personal level.

You fixed a production issue fast.
You unblocked a customer.
You were the hero who saved the day.

This creates a subtle incentive problem: the system rewards individuals for bypassing the process. The delivery pipeline, which exists to protect the team and the product, becomes an obstacle to individual heroics.

Over time, teams drift into a culture where:

Being fast matters more than being safe.
Fixing symptoms is rewarded more than fixing root causes.
Short-term relief beats long-term stability.

This is how delivery pipelines rot — not from neglect, but from well-meaning people optimizing for speed under pressure.

Real-World Pattern: The “Temporary” Hotfix That Becomes Permanent

A common pattern looks like this:

A bug appears in production.
Someone applies a quick fix directly in production or through a rushed commit.
The fix is labeled “temporary.”
The team plans to clean it up later.
Later never comes.

Weeks later, another change interacts with that temporary fix and breaks something else. Now nobody fully understands the code path. The pipeline didn’t catch it because the fix never went through proper tests.

The original quick fix saved 30 minutes.
The long-term cost is measured in hours of debugging, fragile code, and lost confidence in the system.

Why This Destroys Flow (Not Just Quality)

Quick fixes don’t just hurt quality. They destroy delivery flow.

Once bypassing the pipeline becomes normal:

Developers hesitate to touch fragile areas.
Releases become unpredictable.
Small changes cause big side effects.
People slow down because they don’t trust the system.

Ironically, the behavior that started as “moving faster” ends up making delivery slower and more stressful.

You trade short-term speed for long-term friction.

How to Fix the Culture Without Becoming Bureaucratic

This isn’t about banning hotfixes. Production incidents are real. Speed matters. The goal is to make fast changes also safe changes.

1. Make the Fast Path the Safe Path

If your CI takes 40 minutes, people will bypass it.
If your review process blocks urgent fixes, people will bypass it.

Your pipeline must be optimized for speed in emergencies:

Lightweight reviews for hotfixes.
Fast CI path for critical changes.
Clear “hotfix” workflow that still enforces minimal quality gates.

2. Track Bypasses as Technical Debt

Every bypass should leave a visible trace:

A ticket to add tests later.
A follow-up task to clean up the quick fix.
A post-incident note explaining what was skipped.

If bypassing the pipeline leaves no trace, it becomes invisible debt.

3. Reward Stability, Not Heroics

Publicly recognize:

Fixes that go through the proper pipeline under pressure.
Improvements to CI speed.
Reductions in flaky tests.

Stop glorifying the person who “just pushed a fix to prod” without safeguards. You want to reward people who improve the system, not just fight its symptoms.

The Core Insight

“Just one more quick fix” is never just one.

It’s a small exception that rewires how your team relates to the delivery pipeline.
It teaches people what the real process is — not the one in documentation, but the one that gets things shipped.

If your real process bypasses quality gates under pressure, then under real pressure, you don’t have a delivery pipeline at all.

You have hope and heroics.

And that’s not a strategy.

Contract Testing External APIs in PHP with Pact (Real Laravel Example)

CodeCraft Diary — Wed, 18 Feb 2026 14:05:00 +0000

Testing integrations with external APIs is one of the most fragile parts of any web application. In theory, we write tests, mock HTTP clients, and feel confident. In practice, APIs change, fields disappear, status codes shift, and production breaks anyway.

I learned this the hard way.

In one project, all my tests were green. My mocks returned exactly what I expected. A week later, the external API removed one field from the response. My mocks didn’t know about the change. Production did.

Mocks told me everything was fine. Reality disagreed.

This is exactly the kind of problem contract testing is meant to solve. In this article, I’ll show you how to use contract testing for external APIs in PHP with Pact, using a real-world *Laravel * example.

Why Mocking External APIs Is Not Enough

Mocking external APIs is useful. I still do it. It makes tests fast, deterministic, and cheap. But mocks have one fatal flaw:

They only test your assumptions about the API, not the API itself.

Typical problems I’ve seen in production:

The API removes or renames a field.
A nested structure changes shape.
The API starts returning 404 instead of 200 in some edge cases.
The API adds a required field to the request body.

Your mocks will never catch this unless you manually update them. That means mocks alone can silently drift away from reality.

What Is Contract Testing (In Plain English)

Contract testing sits between mocking and full integration tests.

Instead of saying:

“This is what I think the API returns,”

you say:

“This is the contract between my app (consumer) and the API (provider).”

With consumer-driven contract testing:

The consumer
defines what it expects from the API.
The provider must verify that it actually fulfills this contract.

If the provider changes something that breaks the contract, tests fail before production breaks.

This turns breaking API changes from a runtime surprise into a build-time failure.

Diagram: How contract testing works between a Laravel consumer, Pact mock server, and the real API provider.

Real-World Scenario: Laravel as API Consumer

Let’s assume a Laravel application integrates with an external billing API:

GET /api/customers/{id}

Response:
{
  "id": 123,
  "email": "john@example.com",
  "is_active": true
}

Your Laravel service:

class BillingClient
{
    public function getCustomer(int $id): array
    {
        $response = Http::get("https://billing.example.com/api/customers/{$id}");

        return $response->json();
    }
}

Your application relies on:

email
is_active

If the provider removes is_active, your app breaks. Mocks won’t catch it. Contract testing will.

Step-by-Step: Contract Testing with Pact in Laravel

Installing Pact for PHP

Install Pact dependencies for your test environment:

composer require --dev pact-foundation/pact-php

You’ll also need the Pact CLI running locally or in CI (usually via Docker).

Writing the Consumer Contract Test

The goal: define what your Laravel app expects from the API.

Example consumer test:

public function test_it_fetches_customer_from_billing_api()
{
    $builder = new InteractionBuilder();

    $builder
        ->given('Customer 123 exists')
        ->uponReceiving('A request for customer 123')
        ->with([
            'method' => 'GET',
            'path'   => '/api/customers/123',
        ])
        ->willRespondWith([
            'status' => 200,
            'headers' => ['Content-Type' => 'application/json'],
            'body' => [
                'id' => 123,
                'email' => 'john@example.com',
                'is_active' => true,
            ],
        ]);

    $builder->verify(function () {
        $client = new BillingClient();
        $customer = $client->getCustomer(123);

        $this->assertSame('john@example.com', $customer['email']);
        $this->assertTrue($customer['is_active']);
    });
}

This test:

defines the expected request
defines the expected response
generates a contract file (Pact file)

This contract is the single source of truth between consumer and provider.

Verifying the Contract on the Provider Side

On the provider side, the API team runs Pact verification:

pact-verifier --provider-base-url=http://localhost:8000 \
 --pact-url=./pacts/billing-consumer.json

If the API no longer returns is_active, verification fails.

This is the key difference from mocks:

mocks only test the consumer
contract testing tests the agreement

Running Contract Tests in CI

This is where contract testing becomes powerful.

Typical CI flow:

Consumer tests generate Pact contracts.
Provider pipeline verifies contracts.
Pipeline fails if contracts are broken.

This creates a safety net:

API changes cannot be deployed if they break existing consumers.

Common Mistakes with Contract Testing

Over-Specifying Responses

Don’t lock down every field if you don’t need it.
Only define what your app actually uses.

Only Testing Happy Paths

Include error contracts:

404 responses
validation errors
unauthorized responses

Not Versioning Contracts

Treat contracts like code. Version them.

Not Enforcing Contracts in CI

If no pipeline enforces them, contract testing is just documentation.

When Contract Testing Is Worth It (and When It’s Overkill)

Contract testing is worth it when:

multiple teams own different services
APIs evolve frequently
breaking changes are expensive

It’s probably overkill when:

the integration is trivial
you don’t control the provider
the API is stable and rarely changes

Contract testing is a scalpel, not a hammer. Use it where API stability matters.

How Contract Testing Fits into Your Laravel Testing Strategy

This is how I think about testing layers in real projects:

Unit tests – business logic
Feature tests – HTTP flows
Mocks – isolate slow or unstable services
Contract tests – protect integrations from breaking changes

Mocks keep your tests fast.
Contract tests keep your integrations honest.

They solve different problems and work best together.

Final Thoughts

Mocking external APIs is necessary — but it’s not sufficient.

If your application depends on external services and you’ve ever been surprised by a breaking API change in production, contract testing is the missing safety net.

You don’t need to contract-test everything. Start with one critical integration. Add one contract. Let your CI enforce it. The first time a breaking change is caught before deployment, contract testing pays for itself.

Builder Pattern in PHP/Laravel: Building Clean and Flexible Order Objects

CodeCraft Diary — Tue, 10 Feb 2026 14:05:00 +0000

In practice, orders in e-commerce systems often evolve over time, which makes them a perfect candidate for the Builder Pattern.

Creating orders in an e-commerce application often seems straightforward at first: a customer selects items, adds them to a cart, and checks out. But as your application grows, the Order class can quickly become complex. You might need to handle optional discounts, shipping options, gift wrapping, different payment methods, and more. Before long, your constructor looks like this:

$order = new Order(
    $customerId,
    $items,
    $paymentMethod,
    $shippingAddress,
    $discountCode,
    $giftWrap = true,
    $specialInstructions = null
);

Not only is it hard to read, but it’s also easy to make mistakes when creating orders. Because of this, the Builder Pattern becomes a natural solution. It lets you construct objects step by step, handling optional parameters elegantly while keeping your code readable and maintainable.

In this article, we’ll explore how to apply the Builder Pattern to an Order class in PHP/Laravel, improving readability, testability, and flexibility.

Previous article in this category: https://codecraftdiary.com/2026/01/17/factory-method-in-php/

Why the Builder Pattern Works for Orders

The Builder Pattern is especially useful when:

A class has many optional parameters
The class requires complex setup or validation
You want to avoid long constructors
You need clear, readable, fluent code

In e-commerce, orders often fit all these criteria. By using a builder, we can separate the construction logic from the order behavior, making it easier to extend and maintain.

Step 1: Designing the Order Class

Let’s start with a simple Order class that represents a finalized order object. We’ll assume that once an order is created, it’s immutable:

class Order
{
    public function __construct(
        public int $customerId,
        public array $items,
        public string $paymentMethod,
        public string $shippingAddress,
        public ?string $discountCode = null,
        public bool $giftWrap = false,
        public ?string $specialInstructions = null
    ) {}
}

However, the constructor still takes multiple parameters, some of them optional. While this works, it doesn’t scale well if more options are added in the future.

Step 2: Creating the Order Builder

We can create an OrderBuilder class to handle object creation step by step:

class OrderBuilder
{
    private int $customerId;
    private array $items = [];
    private string $paymentMethod = 'credit_card';
    private string $shippingAddress = '';
    private ?string $discountCode = null;
    private bool $giftWrap = false;
    private ?string $specialInstructions = null;

    public static function create(): self
    {
        return new self();
    }

    public function customerId(int $customerId): self
    {
        $this->customerId = $customerId;
        return $this;
    }

    public function addItem(array $item): self
    {
        $this->items[] = $item;
        return $this;
    }

    public function paymentMethod(string $method): self
    {
        $this->paymentMethod = $method;
        return $this;
    }

    public function shippingAddress(string $address): self
    {
        $this->shippingAddress = $address;
        return $this;
    }

    public function discountCode(string $code): self
    {
        $this->discountCode = $code;
        return $this;
    }

    public function giftWrap(bool $flag): self
    {
        $this->giftWrap = $flag;
        return $this;
    }

    public function specialInstructions(string $instructions): self
    {
        $this->specialInstructions = $instructions;
        return $this;
    }

    public function build(): Order
    {
        if (empty($this->customerId)) {
            throw new \InvalidArgumentException('Customer ID is required.');
        }

        if (empty($this->items)) {
            throw new \InvalidArgumentException('At least one item is required.');
        }

        if (empty($this->shippingAddress)) {
            throw new \InvalidArgumentException('Shipping address is required.');
        }

        return new Order(
            $this->customerId,
            $this->items,
            $this->paymentMethod,
            $this->shippingAddress,
            $this->discountCode,
            $this->giftWrap,
            $this->specialInstructions
        );
    }
}

Notice a few key things:

Fluent interface: Each setter returns $this, allowing chained calls.
Validation in build(): Mandatory fields are checked before creating the Order.
Stepwise construction: You can add items or set options one by one.

Step 3: Using the Builder

Here’s how creating an order looks without a builder:

$order = new Order(
    123,
    [['product_id' => 1, 'quantity' => 2], ['product_id' => 5, 'quantity' => 1]],
    'paypal',
    '123 Main Street, City, Country',
    'DISCOUNT10',
    true,
    'Leave at the front door'
);

As a result, it’s hard to read and error-prone.

With the builder, it becomes:

$order = OrderBuilder::create()
    ->customerId(123)
    ->addItem(['product_id' => 1, 'quantity' => 2])
    ->addItem(['product_id' => 5, 'quantity' => 1])
    ->paymentMethod('paypal')
    ->shippingAddress('123 Main Street, City, Country')
    ->discountCode('DISCOUNT10')
    ->giftWrap(true)
    ->specialInstructions('Leave at the front door')
    ->build();

Much cleaner and readable.
Easy to skip optional fields or add more items.
Validation ensures that you set all required fields.

Step 4: Integrating with Laravel Jobs or Services

In Laravel, orders are often processed asynchronously using Jobs or Services. Builders make this easier:

$order = OrderBuilder::create()
    ->customerId($user->id)
    ->addItem(['product_id' => $product->id, 'quantity' => 1])
    ->shippingAddress($user->address)
    ->build();

dispatch(new ProcessOrderJob($order));

You can also create reusable templates for common order setups:

class OrderBuilderFactory
{
    public static function giftOrder(int $customerId, array $items, string $address): OrderBuilder
    {
        return OrderBuilder::create()
            ->customerId($customerId)
            ->shippingAddress($address)
            ->giftWrap(true)
            ->paymentMethod('credit_card')
            ->addItem(...$items);
    }
}

$order = OrderBuilderFactory::giftOrder($user->id, $items, $user->address)->build();

This pattern is perfect when you have standardized order types, like gifts or bulk orders.

Step 5: Advantages of Using the Builder Pattern

Readability: The creation of orders reads like a series of instructions.
Validation: All required fields are checked in one place.
Flexibility: Optional fields can be skipped without affecting the rest.
Testability: Builders can be tested independently from the Order class.
Extensibility: Adding new optional features (e.g., gift wrap, promo codes) doesn’t break existing code.

Step 6: When Not to Use a Builder

You don’t always need builders. Avoid using them if:

The class only has 2–3 parameters.
Objects are simple DTOs without optional parameters.
Fluent APIs add unnecessary complexity.

For small objects, a simple constructor or named constructors may suffice.

Step 7: Summary

The Builder Pattern is a simple yet powerful way to manage complex object creation in PHP and Laravel. By separating construction from the object itself, your code becomes readable, maintainable, and testable.

For an Order class with multiple optional features, the builder provides a clear, step-by-step way to create instances without dealing with confusing long constructors.

Key takeaways:

Use the builder for complex or optional-heavy objects.
Keep validation in the build() method.
Leverage fluent interfaces for readability.
Consider factory methods for reusable templates.

With the Builder Pattern, your order creation code can grow with your application—without turning into a mess of parameters and confusion.

Why "Almost Done" Work Breaks Development Flow

CodeCraft Diary — Tue, 03 Feb 2026 14:57:00 +0000

Every team has it.

A pull request that's "basically finished."
A feature that's "just missing a few small things."
A task marked as almost done for the third week in a row.

It rarely looks like a problem. There's no failing build, no red alerts, no production outage. And yet, this kind of work is one of the most effective ways to quietly destroy development flow.

Not by being wrong - but by never being truly finished.

Previous article in this category:
https://codecraftdiary.com/2026/01/10/effective-code-reviews/

What "Almost Done" Really Means

In theory, almost done sounds harmless. In practice, it usually means one or more of the following:

Tests are missing or incomplete
Edge cases are known but postponed
Naming or API design "can be improved later"
Migration exists, rollback does not
Documentation is optional… for now

None of these issues are dramatic on their own. That's why they survive. The problem is that almost done work doesn't behave like work in progress - it behaves like invisible technical inventory.

It sits in the system.
It consumes attention.
And it blocks flow.

The Illusion of Progress

Half-finished work creates a powerful illusion: movement without completion.

From the outside, things look active:

PRs are open
Commits keep coming
Sprint boards show progress

But internally, the system is stuck.

Developers context-switch back to old code.
Reviewers repeatedly re-load the same mental model.
Small unresolved decisions accumulate into cognitive debt.

Nothing moves forward cleanly, because nothing is allowed to end.

Why It's Worse Than Doing Nothing

A task that hasn't been started yet is cheap.

A task that's almost done is expensive.

Why?

Because almost done work demands continuous re-entry. Every return requires:

Rebuilding context
Re-evaluating past decisions
Re-answering questions that should have been resolved once

This is not linear cost - it compounds.

The longer work stays in this state, the more expensive finishing it becomes. At some point, teams stop finishing at all. They work around it instead.

That's when flow collapses.

Review Fatigue: The Silent Multiplier

Code reviews amplify this problem dramatically.

A PR that's nearly ready but not quite there:

Gets reviewed
Receives feedback
Gets partially updated
Then stalls

When it comes back days later, the reviewer must start over.

Multiply that by several PRs and several developers, and you get review fatigue - not because reviews are bad, but because they never conclude.

At that point, reviewers stop caring about quality and focus on getting it merged. Standards drop, resentment grows, and nobody can quite explain why.

When Pull Requests Wait, Conflicts Multiply

One of the most visible symptoms of almost done work is a pull request that sits open for too long.

At first, nothing seems wrong. The code is there. CI is green. Review is "scheduled."
Then time passes.

While the PR waits, the main branch moves on:

New features are merged
Refactors happen elsewhere
Dependencies shift subtly

When the original author finally comes back, the PR is no longer just waiting for approval - it's out of date.

Example: The PR That Was "Basically Ready"

Imagine a backend pull request that introduces a new endpoint.

The logic is implemented. Tests exist, but only for the happy path.
The author opens the PR and asks for review.

The review doesn't happen that day.

Two days later, another feature touches the same service.
A small refactor is merged. Nothing dramatic.

When the original PR finally gets reviewed, it now has conflicts.
Tests fail because assumptions changed. The reviewer's comments are no longer fully relevant.

What was a one-hour review becomes a half-day cleanup.

Nothing about the code was wrong.
It just waited long enough for the system to move around it.

That's the real cost of "basically finished" work.

Merge Conflicts Are Not a Git Problem

At this point, conflicts appear. And teams often treat them as a tooling issue.

They are not.

Merge conflicts are a process failure.

They happen because work was allowed to remain unfinished long enough for the system around it to change. The longer a PR stays open, the higher the probability that it collides with unrelated changes.

This creates a feedback loop:

PR waits for review
Branch diverges
Conflicts appear
Author postpones fixing them
Review is delayed again

The PR becomes heavier every day it remains open.

The Psychological Cost of Rebase Hell

Long-lived PRs don't just create technical conflicts - they create psychological resistance.

Developers start associating the PR with:

Painful rebases
Repeated test failures
Comments they've already addressed once

So they avoid it.

"This will take a full afternoon."
"I'll deal with it when I have time."

That avoidance keeps the work in the almost done state even longer - exactly where it does the most damage.

Review Latency Is the Real Bottleneck

Teams often blame developers for not finishing work.

But in many cases, the real issue is review latency.

If reviews routinely take days:

Developers stop prioritizing clean completion
PR size increases ("If it takes days anyway…")
Conflicts become normal, not exceptional

At that point, the workflow trains people to leave things unfinished.

Short-Lived PRs, Short-Lived Problems

The solution is not hero reviewers or stricter rules.
It's shorter lifetimes.

A PR that:

Is reviewed within hours
Merged the same day
Or explicitly rejected early

…does not accumulate conflicts, fatigue, or resentment.

It either finishes - or it dies quickly.

Both outcomes preserve flow.

Make Waiting Visible
One simple but effective practice is to treat waiting PRs as first-class problems.

For example:

Highlight PRs open longer than 48 hours
Treat "waiting for review" as a blocker, not a state
Prefer reviewing over starting new work

When waiting becomes visible, it stops being normal.

Flow Breaks Where Work Waits

Conflicts, rebases, and stalled PRs are not isolated issues.

They are downstream effects of allowing work to stay almost done.

If you want fewer conflicts, don't fight Git.
Finish work faster - or stop starting it.

Lean Has a Name for This

In Lean thinking, unfinished work is called inventory.

Inventory is dangerous because:

It hides problems
It ties up resources
It creates false confidence

Software teams rarely think in these terms, but the parallel is exact.

Half-finished features are inventory.
Open PRs are inventory.
"Almost done" tasks are inventory.

And like any excess inventory, they slow the entire system.

Common Causes (That Sound Reasonable)

The most dangerous causes are the ones that feel justified:

1. Large Pull Requests
"Let's do it properly in one go."

Large PRs increase the chance that something remains unresolved - and once they stall, they tend to stay stalled.

2. Vague Definition of Done

If done isn't explicit, almost done becomes acceptable.

Without a shared baseline (tests, docs, rollback, review passed), everyone uses their own internal standard.

3. Deferred Decisions

"We'll clean this up later."
"Let's just ship it first."
Later rarely comes.

Why Backend Teams Feel This More

Backend work has properties that make almost done especially toxic:

Hidden coupling between systems
Migrations that can't be half-applied
APIs that lock in contracts early
Bugs that surface weeks later

A frontend workaround might be ugly but visible.
A backend shortcut is often invisible - until it explodes.

That's why backend teams feel "slow" even when they work constantly.

They're not slow. They're stuck finishing yesterday's almost-done work.

Practical Fixes That Actually Help

This is not about discipline or motivation. It's about system design.

1. Define "Done" Ruthlessly

If it's merged, it must include:

Tests
Review approval
Clear naming
Migration safety (if applicable)

Anything else is not done.

2. Reduce PR Size

Smaller PRs:

Finish faster
Get reviewed faster
Fail faster

They either complete - or get killed early.

3. Ban "Almost Done" Language

This sounds extreme, but language shapes behavior.
Replace:
"It's almost done"
With:
"It's blocked because X"
Blocked work is honest. Almost done is deceptive.

4. Prefer Completion Over Throughput

Shipping fewer things that actually finish beats starting many things that don't.

Flow comes from completion, not activity.

Finishing Is a Skill

Many teams optimize for starting work.
Few optimize for finishing it.

Finishing requires:

Making decisions uncomfortable early
Accepting "good enough" instead of perfect
Closing loops deliberately

It feels slower at first.
Then everything accelerates.

Conclusion: Flow Is About Endings

Development flow isn't created by speed, tools, or frameworks.

It's created by ending things cleanly.

If your team feels busy but stuck, don't ask how to move faster.
Ask how much work is almost done - and why it's allowed to stay that way.

Because unfinished work doesn't just wait.

It actively slows everything around it.