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.

Previous Article in this category : https://codecraftdiary.com/2026/03/21/ai-driven-refactoring/

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

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

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

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

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

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

Update service:

public function handle(CreateOrderData $data): Order

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

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

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

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

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

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.

The post Fat Controller Laravel Refactor: Step-by-Step Clean Architecture Guide appeared first on CodeCraft Diary.

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.

Last article in this category: https://codecraftdiary.com/2026/03/15/small-pull-requests/

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

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:

1. PR must be mergeable within the same day
2. no PR over ~300 lines (soft limit)
3. 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.

The post Trunk-Based Development: Why Most Teams Think They Use It (But Don’t) appeared first on CodeCraft Diary.

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, flaky tests, or even false confidence in your test suite.

In this guide, you’ll learn exactly how both approaches work, their trade-offs, and when to use each in real-world scenarios.

Last article in this category: https://codecraftdiary.com/2026/03/08/laravel-queue-testing-jobs-retries/

PHP Unit docs: https://phpunit.de/documentation.html

Understanding the Core Problem

Before diving into Laravel specifics, let’s clarify the core issue:

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:

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

Article about practice feature testing in PHP: https://codecraftdiary.com/2025/10/30/feature-testing-in-php-ensuring-the-whole-system-works-together/

Option 1: RefreshDatabase

The RefreshDatabase trait is the most commonly used solution.

use Illuminate\Foundation\Testing\RefreshDatabase;

class UserTest extends TestCase
{
    use 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

What this means in practice

Every test starts with:

• a fresh schema
• no leftover data
• consistent environment

Advantages

1. High reliability

Each test runs in a completely clean environment.

2. Works with everything

• queues
• jobs
• events
• external processes

3. Predictable behavior

No surprises caused by hidden state.

Disadvantages

1. Slower

Running migrations repeatedly can add overhead.

2. Heavier setup

Especially noticeable in large applications.

Option 2: DatabaseTransactions

The DatabaseTransactions trait takes a different approach.

use Illuminate\Foundation\Testing\DatabaseTransactions;

class UserTest extends TestCase
{
    use 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

What this means

Instead of resetting the database:

• changes are never committed
• everything is undone automatically

Advantages

1. Fast

Transactions are significantly quicker than migrations.

2. Lightweight

No need to rebuild the database schema.

Disadvantages

1. Limited scope

Does NOT work well with:

• queued jobs
• async processes
• separate DB connections

2. Hidden pitfalls

If something runs outside the transaction:

• it won’t be rolled back
• tests may behave inconsistently

Key Differences

Here’s a clear comparison:

When to Use RefreshDatabase

Use RefreshDatabase when:

1. You are testing queues or jobs

Jobs often run outside the main transaction.

dispatch(new ProcessOrderJob($order));

dispatch(new ProcessOrderJob($order));

If you use DatabaseTransactions, the job may not see the data at all.

2. You rely on multiple database connections

Transactions don’t span across connections reliably.

3. You want maximum reliability

If your priority is correctness over speed, this is the safer option.

When to Use DatabaseTransactions

Use DatabaseTransactions when:

1. You are testing simple database interactions

Example:

• repository logic
• basic CRUD operations

2. Performance matters

In large test suites, this can significantly reduce execution time.

3. Everything runs in a single request lifecycle

No queues, no async behavior, no external processes.

Common Mistakes (and How to Avoid Them)

Mixing both traits

use RefreshDatabase, DatabaseTransactions;

use RefreshDatabase, DatabaseTransactions;

This creates unpredictable behavior.

Fix: Choose one strategy per test class.

Using transactions with queues

Queue::fake();

Queue::fake();

Even with fakes, underlying behavior may break if data isn’t committed.

Fix: Use RefreshDatabase for queue-related tests.

Assuming transactions isolate everything

They don’t.

Anything outside the transaction:

• won’t be rolled back
• can pollute your test environment

Ignoring test failures caused by state

Flaky tests often indicate:

improper database isolation

Don’t ignore them — fix the root cause.

Real-World Example

Let’s say you’re testing order processing.

public function test_order_is_processed()
{
    $order = Order::factory()->create();

    dispatch(new ProcessOrderJob($order));

    $this->assertDatabaseHas('orders', [
        'id' => $order->id,
        'status' => 'processed',
    ]);
}

public function test_order_is_processed()
{
    $order = Order::factory()->create();

    dispatch(new ProcessOrderJob($order));

    $this->assertDatabaseHas('orders', [
        'id' => $order->id,
        'status' => 'processed',
    ]);
}

With DatabaseTransactions

• job may not see the order
• test fails unexpectedly

With RefreshDatabase

• data is committed
• job works correctly
• test passes

Recommended Strategy

For most Laravel applications, the safest default is:

use RefreshDatabase;

use RefreshDatabase;

Then optimize later if needed.

Hybrid approach (advanced)

You can:

• use RefreshDatabase for feature tests
• use DatabaseTransactions for isolated unit-like tests

This gives you:

• reliability where needed
• speed where possible

Final Thoughts

Database testing in Laravel isn’t just about writing assertions — it’s about controlling state.

Choosing between RefreshDatabase and DatabaseTransactions directly affects:

• test reliability
• debugging time
• overall confidence in your application

If you’re unsure which one to use, start with:

RefreshDatabase

It may be slightly slower, but it will save you hours of debugging and prevent subtle, hard-to-track issues.

Once your test suite grows, you can selectively introduce DatabaseTransactions where performance matters and constraints are well understood.

TL;DR

• Use RefreshDatabase for reliability and real-world scenarios
• Use DatabaseTransactions for speed in simple cases
• Avoid mixing both
• Be mindful of queues and async behavior

A well-structured test suite isn’t just about coverage — it’s about trust.

And that trust starts with a clean, predictable database.

The post Laravel RefreshDatabase vs DatabaseTransactions: When to Use Each appeared first on CodeCraft Diary.

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
}

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

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.

1. Shared State Issues

This is dangerous:

$this->processedUrls[] = $result;

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

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

AI-generated test:

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

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

Everything is green. Everything is wrong.

3. “Happy Path” Bias

AI prefers:

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

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

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

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

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.

The post AI-Driven Refactoring in PHP: When to Trust Copilot (and When to Take the Wheel) appeared first on CodeCraft Diary.

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:

1. The reviewer skims the code and approves it quickly.
2. 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:

• longer build times
• harder debugging when tests fail
• multiple unrelated failures

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.

The post Small Pull Requests: Why They Move Development Teams Faster appeared first on CodeCraft Diary.

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

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

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

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

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

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

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

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

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

To test that correctly:

Bus::fake();

$job = new ProcessPaymentJob($order);

$job->handle($paymentService);

Bus::assertDispatched(SendInvoiceJob::class);

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

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

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

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

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:

1. Time (execution is delayed)
2. Failure (automatic retries)
3. 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.

The post Laravel Queue Testing: What Most Developers Get Wrong appeared first on CodeCraft Diary.

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',
];

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

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

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

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

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

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

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

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

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

$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.

The post Singleton Pattern in PHP: Refactoring Global State the Right Way appeared first on CodeCraft Diary.

“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:

1. A bug appears in production.
2. Someone applies a quick fix directly in production or through a rushed commit.
3. The fix is labeled “temporary.”
4. The team plans to clean it up later.
5. 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.

The post Why “Just One More Quick Fix” Destroys Your Delivery Pipeline appeared first on CodeCraft Diary.

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
}

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

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

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

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:

1. Consumer tests generate Pact contracts.
2. Provider pipeline verifies contracts.
3. 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.

The post Contract Testing External APIs in PHP with Pact (Real Laravel Example) appeared first on CodeCraft Diary.

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

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

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

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

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

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

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

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

1. Readability: The creation of orders reads like a series of instructions.
2. Validation: All required fields are checked in one place.
3. Flexibility: Optional fields can be skipped without affecting the rest.
4. Testability: Builders can be tested independently from the Order class.
5. 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.

The post Builder Pattern in PHP/Laravel: Building Clean and Flexible Order Objects appeared first on CodeCraft Diary.