DEV Community: CodeCraft Diary

Mastering Value Objects in PHP 8.5+ (2026 Edition)

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

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

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

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

The “Price” of Primitive Obsession

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

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

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

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

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

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

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

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

What Exactly is a Value Object?

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

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

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

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

A Better Approach: Explicit Domain Types

Let’s refactor the previous example.

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

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

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

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

A few important things are happening here:

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

Why This Matters (Especially Today)

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

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

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

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

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

Real-World Refactoring: Email

How often have you written this?

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

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

Let’s move that logic into a Value Object:

final readonly class EmailAddress
{
    private string $value;

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

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

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

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

Now your service layer becomes much cleaner:

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

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

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

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

Logic-Heavy Value Objects

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

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

Instead of passing:

string $startDate, string $endDate

You can model:

OrderDateRange

With methods like:

overlapsWith()
isWithinLastMonth()
getDurationInDays()

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

When NOT to Use Value Objects

Not everything needs to be a Value Object.

Ask yourself:

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

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

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

Performance Considerations

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

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

More importantly:

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

Summary

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

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

Practical steps:

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

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

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

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

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

It’s pull requests.

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

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

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

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

Six.

Months.

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

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

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

The Hidden Cost of Large Pull Requests

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

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

Here’s what actually happens:

1. Review becomes a cognitive nightmare

When a PR has:

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

No one can realistically review it properly.

So what happens?

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

And “later” turns into never.

2. Feedback loop collapses

Fast feedback is the core of modern development.

But with large PRs:

feedback comes late
feedback is vague
feedback is expensive to apply

Instead of:

“Fix this small thing”

You get:

“This entire approach might be wrong”

Now the author has to:

rethink everything
rework large chunks of code
re-request review

Cycle time explodes.

3. Merge becomes risky

The bigger the PR, the higher the risk:

conflicts with main branch
outdated assumptions
broken integrations

So teams hesitate.

And hesitation kills flow.

4. Work gets batched (and everything slows down)

This is the core anti-pattern.

Instead of shipping continuously, developers start batching work:

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

Then:

“Actually, I’ll include this refactor too”

And suddenly:

PR grows
review slows
merge is delayed

It’s a vicious cycle.

The Real Reason Your PRs Are Too Big

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

It’s behavioral.

Here are the real causes:

1. “I want it to be complete”

This is the most common mindset:

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

Sounds reasonable. It’s also completely wrong.

Because “done” often means:

multiple layers
edge cases
polish

Which leads to massive PRs.

2. Fear of breaking things

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

So they wait.

And wait.

And accumulate changes.

3. Poor slicing of work

Most developers split work like this:

backend PR
frontend PR
DB migration PR

Instead of:

vertical slices that deliver value end-to-end

This creates artificial dependencies and forces larger PRs.

4. Review culture is asynchronous and slow

If reviews take:

hours
or days

Developers adapt by batching work.

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

The 6-Month Pull Request Problem

Let’s go back to that real example.

A PR open for six months.

What does that actually mean?

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

At that point, you have only two realistic options:

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

Both are bad.

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

How to Fix This (Practically)

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

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

Max ~300–400 lines per PR

Not as a suggestion.

As a constraint.

Why?

Because constraints force better behavior:

better slicing
fewer concerns per change
faster reviews

2. Merge incomplete work (safely)

This is the shift most teams struggle with.

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

You need:

safe code
controlled exposure

Use:

feature flags
toggles
hidden UI states

This allows you to:

merge early
iterate safely

Slice vertically, not horizontally

Instead of:

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

Do:

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

Each PR:

delivers something usable
is independently testable
is small

4. Optimize review speed (not just quality)

Set expectations:

PR should be reviewed within a few hours
not days

Ways to achieve this:

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

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

This is uncomfortable but critical.

Sometimes the right move is:

“Merge this small, slightly imperfect change now”

Instead of:

“Wait until it’s perfectly clean”

Why?

Because flow matters more than perfection.

You can always:

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

6. Track your actual behavior

If you want to be serious about this, measure:

average PR size
PR lifetime
number of merges per day

Reality check:

If your PRs:

live for days
contain hundreds/thousands of lines

You are not doing trunk-based development.

No matter what your team says.

What About Large Architectural Changes?

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

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

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

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

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

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

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

The Real Mindset Shift

This is the uncomfortable truth:

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

They require you to:

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

And that’s hard.

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

Final Thought

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

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

Most teams are operating with:

oversized changes
slow feedback
delayed merges

And then they wonder why delivery feels slow.

If you fix just one thing, fix this:

Make your pull requests smaller. Radically smaller.

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

Not the other way around.

Laravel Testing Mistakes That Make Your Tests Useless

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

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

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

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

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

1. Testing Implementation Instead of Behavior

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

Bad example

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

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

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

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

Better approach

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

    $response->assertStatus(201);

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

Focus on observable behavior, not internal calls.

2. Overusing Mocks

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

Problem

When everything is mocked:

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

Http::fake();

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

$response->assertStatus(200);

This tells you nothing about:

response structure
data correctness
edge cases

Better approach

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

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

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

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

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

3. Writing Tests That Always Pass

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

Example

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

    $response->assertStatus(200);
}

This test will pass even if:

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

Better approach

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

Or even better:

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

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

4. Ignoring Edge Cases

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

Common mistake

Only testing valid input:

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

Better approach

Test invalid scenarios:

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

Also test:

missing fields
duplicate values
unexpected input

Good tests try to break your application.

5. Testing Too Much in Unit Tests

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

Example

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

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

This mixes:

business logic
database layer

Better approach

Split responsibilities:

Unit test (logic only):

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

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

Feature test (full flow):

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

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

Keep your test layers clean.

6. Not Using Factories Properly

Laravel factories are powerful, but many developers misuse them.

Problem

Hardcoding everything:

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

Better approach

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

Even better:

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

Benefits:

less boilerplate
more flexible tests
easier maintenance

7. Not Cleaning Up Test Data

Dirty test data can cause flaky tests.

Problem

Tests depend on previous state.

Solution

Use:

use Illuminate\Foundation\Testing\RefreshDatabase;

This ensures:

clean DB for each test
consistent results

Flaky tests destroy trust in your test suite.

8. Writing Tests That Are Too Complex

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

Example

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

Better approach

Break it down:

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

Each test should answer one question.

9. Ignoring Performance

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

Problem

too many DB calls
unnecessary setup
heavy fixtures

Tips

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

Fast tests = tests you actually run.

10. Not Testing Real User Flows

Testing isolated pieces is not enough.

Problem

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

Example

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

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

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

Final Thoughts

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

If your tests:

only check status codes
mock everything
mirror your implementation

…then they’re not protecting your application.

Instead, focus on:

real behavior
meaningful assertions
edge cases
realistic user flows

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

Quick Checklist

Before committing a test, ask:

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

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

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

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

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

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

A controller starts small. Clean. Readable.

Then features get added.

Deadlines hit.

Logic piles up.

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

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

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

No theory overload. Just practical steps.

The Problem: A Real Fat Controller Example

Let’s start with something painfully familiar:

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

        // Business logic
        $total = 0;

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

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

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

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

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

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

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

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

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

What’s wrong here?

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

Goal: What “Clean” Looks Like

We want to move toward:

Thin controllers
Isolated business logic
Testable services
Clear boundaries between layers

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

Step 1: Extract Business Logic into a Service

First, move the core logic out of the controller.

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

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

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

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

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

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

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

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

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

        return $order;
    }
}

Controller becomes:

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

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

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

Improvement:

Controller is now thin
Logic is reusable
Easier to test

But we’re not done yet.

Step 2: Introduce a Data Transfer Object (DTO)

Passing raw arrays is fragile.

Let’s fix that.

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

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

Update controller:

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

Update service:

public function handle(CreateOrderData $data): Order

Improvement:

Stronger typing
Safer refactoring
Clear contract

Step 3: Decouple External Dependencies

Right now, your service is tightly coupled to:

Eloquent models
HTTP client

Let’s extract the webhook logic.

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

Inject it:

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

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

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

        return $order;
    }
}

Improvement:

External side effects are isolated
Easier to mock in tests

Step 4: Make It Testable

Now you can test the service independently:

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

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

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

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

Before refactoring, this would require:

HTTP mocking
Controller testing
Complex setup

Now it’s isolated.

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

Don’t overengineer this.

But if your app grows, you might extract:

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

Then inject it into the service.

When to do this:

Multiple data sources
Complex queries
Domain logic reuse

When NOT to:

Simple CRUD apps

Before vs After

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

Common Mistakes to Avoid

1. Moving everything blindly into services

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

Keep services focused.

2. Overengineering with too many layers

You don’t need:

10 interfaces
5 abstractions
enterprise architecture™

Start simple. Evolve when needed.

3. Ignoring boundaries

Controllers = HTTP
Services = business logic
Models = persistence

Mixing these again = back to chaos.

Key Takeaways

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

Final Thought

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

It means one thing:

Making your code easier to change without fear.

And the fastest way to get there?

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

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

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

That’s how clean architecture actually starts.

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

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

Trunk-Based Development sounds simple.

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

Most teams will tell you:

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

In practice, they don’t.

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

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

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

The Illusion of Trunk-Based Development

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

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

Sounds good.

But then you look closer:

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

This is not trunk-based development.

This is just shorter feature branches.

What Real Trunk-Based Development Actually Requires

Trunk-based development is not about branches.

It’s about integration frequency and safety.

At its core, it requires:

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

Without these, trunk-based development collapses.

Where Most Teams Break

1. Pull Requests Are Still Too Big

This is the biggest issue.

A developer starts a “small” feature:

adds endpoint
updates service
modifies database
adds validation
fixes something unrelated

Now the PR has:

15 files changed
600+ lines
multiple concerns

Review slows down. Feedback increases. Merge is delayed.

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

2. Code Reviews Block Integration

In theory:

“We merge frequently”

In reality:

“We merge when the PR gets approved”

That delay is critical.

If reviews take:

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

Now developers start stacking changes on top of each other.

And suddenly:

branches live longer
PRs get bigger
merges become risky

3. Teams Are Afraid to Merge Incomplete Work

This is subtle but important.

Developers often think:

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

So they keep working on the branch.

The problem:

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

Trunk-based development requires a different mindset:

You merge incomplete work safely.

The Missing Piece: Feature Flags

Most teams skip this.

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

Example

You’re building a new payment flow.

Without feature flags:

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

With feature flags:

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

Now you can:

merge partial work
deploy continuously
control exposure

Real Example From Practice

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

Metrics looked like this:

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

After digging in, the issue was clear:

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

What changed

We introduced 3 rules:

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

Result after ~3 weeks:

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

Not because developers got better.

Because the system changed.

The Hidden Constraint: CI/CD Speed

Here’s something teams often ignore:

You cannot do trunk-based development with slow pipelines.

If your CI takes:

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

So what happens?

developers batch changes
PRs get bigger
integration slows down

Rule of thumb (2026 reality):

CI under 10 minutes → good
under 5 minutes → ideal

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

Why This Matters More in 2026

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

That creates a new problem:

volume of changes increases
but review capacity doesn’t

If you don’t enforce:

small changes
fast integration
clear boundaries

your workflow collapses under its own weight.

How to Tell If You’re Actually Doing It

Be honest and check:

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

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

Practical Rules You Can Apply Tomorrow

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

1. Limit PR size

Not as a guideline — as a rule.

2. Optimize for review speed

fewer changes
clearer intent
less context switching

3. Introduce feature flags

Without them, you’re stuck.

4. Fix your CI/CD bottlenecks

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

5. Stop batching work

Batching feels efficient.
It’s not.

Closing Thought

Trunk-based development is not a branching strategy.

It’s a discipline.

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

If your:

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

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

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

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

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.