Forem: CodeCraft Diary

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.

Mocking External APIs in PHP (Sandbox Example)

CodeCraft Diary — Tue, 27 Jan 2026 14:18:00 +0000

Testing external API integrations thoroughly is one of the hardest parts of building reliable web applications. Live API calls are slow, flaky, costly, and can fail unpredictably due to network issues, rate limits, or provider outages. For these reasons, most mature test suites do not make real HTTP requests — they mock them.

This article walks you through mocking external HTTP APIs in plain PHP, from basics to advanced techniques, with sandbox-style examples you can run immediately. We’ll cover:

Why mocking is essential
Creating a PHP API client
Mocking responses with Guzzle
Dynamic and conditional fake responses
Simulating error conditions (timeouts, server errors)
Asserting requests were made correctly
Sequential responses for testing retries
Using sandbox APIs for integration

Previous article in testing category: https://codecraftdiary.com/2026/01/03/testing-database-logic-what-to-test-what-to-skip-and-why-it-matters/

1. Why Mock External API Calls

Before diving into code, here’s why mocking is crucial:

a. Speed
Live HTTP calls dramatically slow down tests — often orders of magnitude slower than in-memory logic.

b. Stability
Third-party APIs can be unreliable, returning downtime or throttling, which makes tests flaky.

c. Isolation
Tests should verify your application logic, not the availability or correctness of external services.

d. Cost and Limits
Calling paid APIs every test run can incur costs or hit rate limits.

2. Creating a PHP HTTP Client

We’ll use Guzzle as our HTTP client. Here’s a simple WeatherClient:

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

class WeatherClient
{
    private Client $client;
    private string $baseUrl;
    private string $apiKey;

    public function __construct(string $baseUrl, string $apiKey)
    {
        $this->baseUrl = $baseUrl;
        $this->apiKey = $apiKey;
        $this->client = new Client(['base_uri' => $baseUrl]);
    }

    public function getCurrent(string $city): array
    {
        try {
            $response = $this->client->request('GET', '/current', [
                'query' => ['q' => $city, 'key' => $this->apiKey],
                'http_errors' => false
            ]);
            return json_decode($response->getBody()->getContents(), true);
        } catch (RequestException $e) {
            throw new \RuntimeException("API request failed: ".$e->getMessage());
        }
    }
}

GuzzleHttp\Client handles HTTP requests
Works in plain PHP without Laravel

3. Mocking API Responses with Guzzle

Guzzle provides MockHandler to simulate responses. Here’s a basic test:

<?php
use GuzzleHttp\Client;
use GuzzleHttp\Handler\MockHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Psr7\Response;

// Mock API response
$mock = new MockHandler([
    new Response(200, [], json_encode([
        'location' => ['name' => 'London'],
        'current' => ['temp_c' => 18]
    ]))
]);

$handlerStack = HandlerStack::create($mock);
$client = new Client(['handler' => $handlerStack, 'base_uri' => 'https://api.weather.com']);

// Inject mock client into WeatherClient
$weatherClient = new WeatherClient('https://api.weather.com', 'dummy-key');
$ref = new ReflectionClass($weatherClient);
$prop = $ref->getProperty('client');
$prop->setAccessible(true);
$prop->setValue($weatherClient, $client);

// Make request (uses mocked response)
$result = $weatherClient->getCurrent('London');

echo "City: ".$result['location']['name']."\n";   // London
echo "Temperature: ".$result['current']['temp_c']."°C\n"; // 18

No real HTTP requests are made
Ideal for unit testing

3a. Basic Example: Mocking a Simple API in Plain PHP Sandbox

This version shows how to simulate external API responses in plain PHP, without Guzzle or Laravel, making it suitable for online sandbox environments like https://onlinephp.io/c/d4940

<?php
// Simple WeatherClient that returns fake responses
class WeatherClient
{
    private $baseUrl;
    private $apiKey;

    public function __construct(string $baseUrl, string $apiKey)
    {
        $this->baseUrl = $baseUrl;
        $this->apiKey = $apiKey;
    }

    // Fake API call returning predefined data
    public function getCurrent(string $city): array
    {
        $fakeApiResponses = [
            'London' => [
                'location' => ['name' => 'London'],
                'current' => ['temp_c' => 18, 'condition' => 'Partly cloudy']
            ],
            'New York' => [
                'location' => ['name' => 'New York'],
                'current' => ['temp_c' => 22, 'condition' => 'Sunny']
            ]
        ];

        return $fakeApiResponses[$city] ?? [
            'location' => ['name' => $city],
            'current' => ['temp_c' => null, 'condition' => 'Unknown']
        ];
    }
}

// --- Sandbox Test ---
$client = new WeatherClient('https://api.fakeweather.com', 'dummy-key');

$cities = ['London', 'New York', 'Paris'];

foreach ($cities as $city) {
    $result = $client->getCurrent($city);
    $temp = $result['current']['temp_c'] ?? 'unknown';
    $condition = $result['current']['condition'] ?? 'unknown';
    echo "City: {$result['location']['name']}, Temperature: {$temp}°C, Condition: {$condition}\n";
}

Why include this:

Shows a fully runnable example in any PHP environment.
Illustrates the concept of mocking/faking API responses without external dependencies.
Complements the Guzzle-based example for readers who want a quick sandbox-ready approach.

4. Dynamic and Conditional Fake Responses

You can customize responses based on input:

$mock = new MockHandler([
    function ($request, $options) {
        parse_str($request->getUri()->getQuery(), $query);
        if ($query['q'] === 'US') {
            return new Response(200, [], json_encode(['data'=>'US result']));
        }
        return new Response(200, [], json_encode(['data'=>'Other result']));
    }
]);

$handlerStack = HandlerStack::create($mock);
$client = new Client(['handler' => $handlerStack]);

Use closures to decide response dynamically

5. Simulating Errors: Timeouts & Server Failures

a. Failed Connection / Timeout

$mock = new MockHandler([
    new \GuzzleHttp\Exception\ConnectException(
        "Connection failed",
        new \GuzzleHttp\Psr7\Request('GET', '/current')
    )
]);

b. Server Errors (HTTP 500)

$mock = new MockHandler([
    new Response(500, [], 'Internal Server Error')
]);

c. Sequential Responses for Retry Logic

$mock = new MockHandler([
    new Response(500, [], 'Fail'),  // First request
    new Response(200, [], json_encode(['location'=>['name'=>'London'], 'current'=>['temp_c'=>20]])), // Second
]);

Useful for testing retry behavior

6. Assertions

In PHPUnit, you can assert the results:

$this->assertEquals('London', $result['location']['name']);
$this->assertEquals(18, $result['current']['temp_c']);

In a sandbox without PHPUnit, simple checks:

if ($result['location']['name'] === 'London') {
    echo "Test passed!\n";
} else {
    echo "Test failed!\n";
}

7. Using Fixtures for Realistic Responses

Instead of hardcoding JSON:

$body = file_get_contents('weather_fixture.json');
$mock = new MockHandler([ new Response(200, [], $body) ]);

Easier to maintain and mirrors real API structure

8. Integration Testing with Sandbox APIs

Some APIs provide sandbox environments (Stripe, PayPal, GitHub) where you can test real HTTP requests safely.

For full sandbox testing:

Configure your client’s base URL to the sandbox
Optionally, use Wiremock or similar mock servers for advanced stubbing
Run integration tests against sandbox to ensure real API compatibility

9. Best Practices

Mock external APIs only, don’t mock internal logic
Use descriptive fixtures for clarity
Include error scenarios in tests (timeouts, 500 errors)
Combine unit tests (mocked) with occasional sandbox integration tests

Factory Method in PHP: When Refactoring Leads to a Pattern

CodeCraft Diary — Tue, 20 Jan 2026 15:09:00 +0000

Factory Method is one of those patterns that many PHP developers encounter early, but fully understand much later. It is often introduced as a “creational pattern” with diagrams and inheritance hierarchies, yet in real projects it rarely starts that way.

In practice, Factory Method is almost never a design decision made upfront. It is a destination reached through refactoring—usually when simple object creation starts to interfere with otherwise stable business logic.

This article explains how Factory Method emerges naturally, what problems it actually solves, and where developers frequently misuse it.

Factory Method is often described as the “younger sibling” of Abstract Factory.

Here you can find article about Abstract factory: https://codecraftdiary.com/2025/12/07/abstract-factory-pattern-php/

The Starting Point: Simple Object Creation

Every PHP project begins with direct instantiation:

$exporter = new CsvExporter();
$exporter->export($data);

This is clean, readable, and perfectly correct.
No abstraction is needed because there is no variability yet.

The mistake many developers make is assuming that patterns should exist before problems do. In reality, the absence of patterns here is a sign of healthy code.

The First Smell: Conditional Creation

As requirements grow, object creation often becomes conditional:

if ($format === 'csv') {
    $exporter = new CsvExporter();
} elseif ($format === 'xlsx') {
    $exporter = new XlsxExporter();
} else {
    throw new RuntimeException('Unsupported format');
}

$exporter->export($data);

This code still works, but several problems appear:

Business logic is mixed with creation logic
Adding a new exporter requires modifying this method
The method now has multiple reasons to change

However, this situation still does not justify Factory Method.

At this stage, the problem is not patterns—it is responsibility.

The Correct First Move: Extract Creation

The right response is not introducing a GoF pattern, but performing a simple refactoring:

protected function createExporter(string $format): Exporter
{
    if ($format === 'csv') {
        return new CsvExporter();
    }

    if ($format === 'xlsx') {
        return new XlsxExporter();
    }

    throw new RuntimeException('Unsupported format');
}

This step is critical. It separates what the code does from what it creates.

At this point, many developers stop—and often they should. If object creation remains stable and parameter-driven, a Strategy, a map, or even a simple switch is usually enough.

Factory Method only becomes relevant if creation itself must vary by context.

The Key Question

Before going any further, ask:

Will different variants of this class need to create different implementations, while the overall algorithm stays the same?

If the answer is no, Factory Method is the wrong tool.

If the answer is yes, Factory Method is likely the simplest correct solution.

When the Pattern Emerges

Consider a scenario where you now have multiple export services, each following the same workflow:

Validate data
Create exporter
Export
Log result

The workflow is identical. Only the exporter differs.

This is where Factory Method naturally appears.

Defining the Stable Algorithm

abstract class ExportService
{
    public function export(array $data): void
    {
        $this->validate($data);

        $exporter = $this->createExporter();
        $exporter->export($data);

        $this->log();
    }

    abstract protected function createExporter(): Exporter;

    protected function validate(array $data): void
    {
        // shared validation logic
    }

    protected function log(): void
    {
        // shared logging logic
    }
}

Notice what happened:

The algorithm is fixed
The creation step is deferred
Subclasses decide what to instantiate

This is Factory Method—not because the pattern was chosen, but because the structure demanded it.

Concrete Implementations

class CsvExportService extends ExportService
{
    protected function createExporter(): Exporter
    {
        return new CsvExporter();
    }
}

class XlsxExportService extends ExportService
{
    protected function createExporter(): Exporter
    {
        return new XlsxExporter();
    }
}

Each subclass controls creation, while the base class controls behavior.

This separation is the essence of Factory Method.

Why This Works Better Than Conditionals

1. Stable Core Logic
The export process is written once. It does not care which exporter exists, only that one exists.

2. Open for Extension
New exporters require new subclasses, not changes to existing logic.

3. Improved Testability
You can override createExporter() in tests and inject test doubles without touching production code.

Common Misunderstandings

“Factory Method replaces conditionals”
It does not.
If the choice depends on runtime data, Factory Method is usually the wrong abstraction.

“Factory Method is just a factory class”
Factory Method is about inheritance and variation, not about standalone factory objects.

“It should be public”
In almost all cases, the factory method should be protected. Making it public leaks internal construction details.

Factory Method vs Other Options

Factory Method sits in the middle: more flexible than direct
instantiation, simpler than full factory hierarchies.

When NOT to Use Factory Method

Avoid Factory Method if:

There is only one concrete implementation
Object creation depends purely on input values
You need to assemble complex object graphs
A simple data-driven approach is enough

Patterns add structure—but also weight.

Final Thought

Factory Method is not something you “apply”.
It is something your code grows into.

If you extract object creation, notice that subclasses need to customize it, and want to keep the main algorithm untouched—you are already there.

Used this way, Factory Method becomes one of the most practical and low-risk patterns in everyday PHP development.

Not because it is clever—but because it respects how software actually evolves.

Why Code Reviews Break Down in Backend Development - CodeCraft Diary

CodeCraft Diary — Wed, 14 Jan 2026 14:30:00 +0000

Almost every development team claims to do code reviews.
Far fewer can honestly say their reviews consistently improve code quality and developer productivity.

In many teams, code review slowly turns into a source of frustration: pull requests pile up, feedback is inconsistent, and developers either argue over details or stop caring altogether. The problem is rarely the people involved. It is almost always the design of the review process itself.

This article looks at the most common code review problems teams face in real projects and offers practical solutions that work in modern workflows.

Previous article: https://codecraftdiary.com/2025/12/20/development-workflow-failures/

Problem 1: Code Reviews Try to Catch Everything

What Happens

Many teams implicitly expect code review to be the final quality gate. Reviewers are supposed to catch logic bugs, style issues, missing tests, edge cases, performance problems, and architectural flaws - all at once.

The result:

reviews take too long
reviewers feel overwhelmed
authors wait days for feedback
reviews become superficial under time pressure

Why This Fails

Humans are bad at repetitive, mechanical checks. When reviewers are overloaded, they either miss important issues or focus on trivial ones.
Expecting reviewers to act as both automation and architects guarantees burnout.

Example

A typical pull request in such teams looks like this:
The CI pipeline is minimal or missing, so reviewers leave comments about formatting, unused imports, naming conventions, and missing null checks. By the time anyone looks at the actual behavior of the code, the discussion thread already has 20 comments.
The same change with proper automation looks very different. Formatting, linting, and tests are enforced automatically. Review comments focus on edge cases, error handling, and whether the change actually solves the problem it claims to solve.
Nothing about the developers changed. Only the responsibility of the review did.

The Fix: Narrow the Responsibility of Code Review

A healthy process clearly defines what code review is not responsible for.

Anything that can be checked automatically should never be reviewed manually:

formatting and style
linting and static analysis
basic type or syntax errors
test execution

Once automation enforces the baseline, reviewers can focus on:

correctness of behavior
clarity of intent
risk and edge cases

Code review should reduce risk - not eliminate it.

Problem 2: Reviews Focus on Opinions Instead of Outcomes

What Happens

Comments like:

"I would write this differently"
"This doesn't feel clean"
"I don't like this abstraction"

Example

Opinion-based feedback often sounds like this:

"I would structure this differently."

Outcome-based feedback reframes the same concern:

"This structure makes it hard to see how errors propagate. How would we diagnose a failure here in production?"

Reviews turn into subjective debates. Decisions depend on who reviews the PR rather than on shared standards.

Why This Fails

Opinion-driven reviews scale poorly. As teams grow, inconsistency increases and trust erodes. Authors stop learning because feedback feels arbitrary.

The Fix: Anchor Reviews to Explicit Criteria

Effective reviews are guided by shared questions, not personal taste.

Examples of outcome-based review questions:

Is the intent of this change clear from the code and description?
Does this implementation handle failure cases explicitly?
Does this introduce hidden coupling or long-term maintenance risk?
Is the complexity justified by the problem being solved?

When feedback is tied to outcomes, disagreements become productive discussions instead of personal conflicts.

Problem 3: Pull Requests Are Too Large

What Happens

Large pull requests accumulate:

multiple features
refactors mixed with behavior changes
unrelated fixes "while I was there"

Reviewers skim. Important issues get missed. Feedback arrives late or not at all.

Why This Fails

Large PRs increase cognitive load. Reviewers cannot hold the full context in their heads, especially under time pressure.

Example

A single pull request includes:

a new feature
a refactor of existing logic
renamed variables across multiple files
a few unrelated fixes "while touching the code"

Reviewers now have to understand what changed and why, across multiple concerns. Important issues are missed simply because the mental load is too high.

When the same work is split into three focused pull requests, reviews become faster, feedback is clearer, and risk is reduced - even though the total amount of code is the same.

The Fix: Enforce Small, Focused Changes

A good rule of thumb:

If a reviewer cannot understand the purpose of a PR in five minutes, it is too large.

Practical improvements:

separate refactors from functional changes
ship incremental improvements behind feature toggles if needed
encourage early, partial PRs for feedback

Small PRs are not about discipline. They are about enabling fast feedback loops.

Problem 4: Reviews Ignore Failure Scenarios

What Happens

Reviews focus on the happy path:

valid input
successful API calls
ideal system state

Edge cases and failure modes are rarely discussed.

Why This Fails

Most production incidents are caused by:

unexpected input
partial failures
timeouts and retries
concurrency issues If these are not considered during review, they will surface later - in production.

Example

A change integrates with an external API. The review verifies that the happy path works and approves the pull request.

In production, the API occasionally times out. The retry logic triggers twice, causing the same operation to run multiple times. Duplicate records appear. The issue is not a bug in the implementation - it is a missing discussion about failure modes during review.

Asking "What happens if this runs twice?" during review would have surfaced the problem early.

The Fix: Make Failure a First-Class Review Topic

Reviewers should explicitly ask:

What happens if this dependency fails?
What happens if this runs twice?
What happens under load?
What assumptions does this code rely on?

Even if not all cases are handled immediately, acknowledging them dramatically reduces future surprises.

Problem 5: Tests Exist but Don't Prove Anything Important

What Happens

Tests are present, but they:

assert implementation details
mirror the code instead of validating behavior
break frequently during refactors

Reviews approve tests because "there are tests", not because they add confidence.

Why This Fails

Decorative tests create a false sense of security. They increase maintenance cost without reducing risk.

The Fix: Review Tests as Risk Protection

Example

A test asserts that a private method is called with specific parameters. The test passes, but it does not verify any observable behavior.

After a refactor, the test breaks even though the system still behaves correctly. Developers update the test without gaining any new confidence.

A single test that verifies a business rule - for example, "an order is rejected when inventory is insufficient" - would provide far more value than multiple tests that mirror the internal structure of the code.

Instead of counting tests, reviewers should ask:

What behavior would break if this test failed?
Does this test protect a business rule or just code structure?
Would this test catch a real regression?

A small number of meaningful tests is more valuable than broad but shallow coverage.

Problem 6: Code Review Culture Becomes Toxic or Avoidant

What Happens

Two common extremes:

overly aggressive reviews that discourage contributions
overly polite reviews that avoid real feedback

Both lead to stagnation.

Why This Fails

Code review is a social process. If feedback feels unsafe or pointless, developers disengage.

The Fix: Separate People from Code - Explicitly

Healthy teams adopt clear norms:

critique decisions, not individuals
explain why something matters
acknowledge good solutions
use questions to invite discussion

Code review should feel like collaboration, not judgment.

Problem 7: Approval Means "Perfect"

What Happens

Reviewers hesitate to approve because they see possible improvements. PRs stall waiting for "one more fix".

Why This Fails

Perfection is undefined and unattainable. Delayed merging increases risk more than minor imperfections.

The Fix: Redefine Approval

Approval means:

"The risk of merging this change is acceptable given our context."

It does not mean:

the solution is ideal
no improvements remain
no future refactoring will be needed

This shift alone can dramatically speed up delivery without sacrificing quality.

How This Fits Modern Development Workflows

In modern teams:

automation enforces consistency
deployments are frequent
rollbacks are possible
feedback cycles are short

Code review should complement these realities - not fight them.

When designed correctly, code review:

spreads knowledge
reduces hidden risk
improves decision-making
strengthens team trust

When designed poorly, it becomes friction disguised as quality control.

Final Thought

Most code review problems are not technical.
They are process and expectation problems.

Fixing them does not require smarter developers or stricter rules - only clearer boundaries, better questions, and respect for how people actually work.

When that happens, code review stops being a bottleneck and becomes what it was always meant to be: a shared investment in better software.