Category: PHP

You join a project mid-flight. There’s a complex operation that creates records, updates statuses, sends notifications, and touches three different services. You need to build the reverse of it. Nobody wrote docs.

Welcome to code archaeology.

The Approach That Actually Works

Don’t start by reading the code top-to-bottom. Start by finding the entry point and tracing outward.

# Find where the operation starts
grep -rn "createOrder\|placeOrder\|submitOrder" app/ --include="*.php" -l

# Find what events it fires
grep -rn "event(\|dispatch(" app/Services/OrderService.php

# Find what listeners react
grep -rn "OrderCreated\|OrderPlaced" app/Listeners/ -l

Build a map as you go. I literally open a scratch file and write:

OrderService::create()
  -> validates input
  -> creates DB record
  -> fires OrderCreated event
     -> SendConfirmationEmail (listener)
     -> UpdateInventory (listener)
     -> NotifyWarehouse (listener)
  -> returns response

Repository Pattern Makes This Harder

If the codebase uses the repository pattern, the actual logic might be buried two or three layers deep. The controller calls the service, the service calls the repository, the repository has the Eloquent query. Grep is your best friend here.

# When you can't find where the actual DB write happens
grep -rn "->save()\|->create(\|->insert(" app/Repositories/ --include="*.php"

The Undo Operation

Once you have the map, building the reverse is mechanical. Each step in the forward operation needs a corresponding undo step, executed in reverse order. The hard part was never the coding. It was understanding what the original code actually does.

Next time you’re staring at a method that calls six other methods across four files, resist the urge to “just figure it out” in your head. Write the map. It takes five minutes and saves five hours.

I just deleted 150 lines of code by adding one optional parameter. Here’s the pattern.

The Duplicate Method Problem

You have a method that works great. Then a new requirement comes in that’s almost the same, but with a slight twist. So you copy the method, tweak it, and now you have two methods that are 90% identical.

public function getLabel(): string
{
    return $this->name . ' (' . $this->code . ')';
}

public function getLabelForExport(): string
{
    return $this->name . ' - ' . $this->code;
}

public function getLabelWithPrefix(): string
{
    return strtoupper($this->code) . ': ' . $this->name;
}

Three methods. Three variations of essentially the same thing. And every time the underlying logic changes, you update all three (or forget one).

Add a Parameter Instead

public function getLabel(string $format = 'default'): string
{
    return match ($format) {
        'export' => $this->name . ' - ' . $this->code,
        'prefix' => strtoupper($this->code) . ': ' . $this->name,
        default  => $this->name . ' (' . $this->code . ')',
    };
}

One method. One place to update. All existing calls that use getLabel() with no arguments keep working because the parameter has a default value.

When to Use This

This works when the methods share the same core logic and only differ in formatting, filtering, or a small behavioral switch. If the “variant” method has completely different logic, keep it separate.

The signal to look for: two methods with nearly identical bodies where you keep having to update both. That’s your cue to merge them with an optional parameter.

Bonus: PHP 8’s match() expression makes the branching clean. No messy if/else chains needed.

Yesterday I was refactoring some code that had a messy inheritance hierarchy. A base class had a method called allowsRefund(), and a child interface was named SupportsPartialRefund.

Read that out loud: “This class allows refund, and supports partial refund.” Two different verbs for the same concept. It’s subtle, but it makes the codebase harder to scan.

The Fix

Rename the interface to match the parent’s verb:

// ❌ Mixed verbs
class PaymentGateway
{
    public function allowsRefund(): bool { ... }
}

interface SupportsPartialRefund
{
    public function getPartialRefundLimit(): Money;
}

// ✅ Consistent verb pattern
class PaymentGateway
{
    public function allowsRefund(): bool { ... }
}

interface AllowsPartialRefund
{
    public function getPartialRefundLimit(): Money;
}

Why This Matters

When you’re scanning a class that implements multiple interfaces, consistent naming lets you instantly understand the hierarchy:

class StripeGateway extends PaymentGateway
    implements AllowsPartialRefund, AllowsRecurringCharge
{
    // The "Allows" prefix immediately tells you
    // these extend the parent's capability pattern
}

If one used Supports and another used Allows, you’d waste mental energy wondering if there’s a meaningful difference. (There isn’t.)

The Rule

When naming an interface that extends a parent class’s concept, use the same verb the parent uses. If the parent says allows, the interface says Allows. If the parent says supports, the interface says Supports. Don’t mix.

Small naming consistency compounds across a large codebase.

When you join a large codebase and need to figure out the “right” way to do something, don’t guess. Don’t check the docs. Let the codebase vote.

The Scenario

You’re working in a Laravel app and need to get the current locale. Quick, which one do you use?

// Option A
App::getLocale()

// Option B
app()->getLocale()

// Option C
config('app.locale')

They all work. But in a codebase with 200+ files touching locales, consistency matters more than personal preference.

grep Is Your Democracy

grep -r "App::getLocale" --include="*.php" | wc -l
# 96

grep -r "app()->getLocale" --include="*.php" | wc -l
# 19

grep -r "config('app.locale')" --include="*.php" | wc -l
# 3

The vote is 96-19-3. App::getLocale() wins by a landslide. That’s what you use. Discussion over.

Why This Works

The dominant pattern in a mature codebase exists for a reason. Maybe it was a conscious decision. Maybe it evolved naturally. Either way, it represents what the team actually does, not what someone thinks they should do.

Following the majority means:

• Your code looks like the rest of the codebase
• grep and find-replace operations work consistently
• New developers see one pattern, not three
• Code reviews go faster because there’s nothing to debate

More Examples

This technique works for any “multiple valid approaches” question:

# String helpers: str() vs Str:: vs helper
grep -r "Str::" --include="*.php" | wc -l
grep -r "str_" --include="*.php" | wc -l

# Config access: config() vs Config::
grep -r "config(" --include="*.php" | wc -l
grep -r "Config::" --include="*.php" | wc -l

# Route definitions: Route::get vs Route::resource
grep -r "Route::get" routes/ | wc -l
grep -r "Route::resource" routes/ | wc -l

When to Override the Vote

The only time you should go against the majority is when the dominant pattern is actively harmful — deprecated functions, security issues, or patterns that cause real bugs. In those cases, file a tech debt ticket and migrate everything at once. Don’t create a third pattern.

Here’s a pattern I keep seeing in real codebases: a method starts returning bool, then requirements grow, and the return type evolves through several stages. Each stage tells you something about what the method is actually doing.

Stage 1: The Boolean

public function validate(array $data): bool
{
    if (empty($data['email'])) {
        return false;
    }
    
    // ... more checks
    
    return true;
}

Simple. Did it work? Yes or no. But the caller has no idea why it failed.

Stage 2: true or String

public function validate(array $data): true|string
{
    if (empty($data['email'])) {
        return 'Email is required';
    }
    
    if (!filter_var($data['email'], FILTER_VALIDATE_EMAIL)) {
        return 'Invalid email format';
    }
    
    return true;
}

Now the caller gets context. true means success, a string means “here’s what went wrong.” The true type (PHP 8.2+) makes this explicit — you can’t accidentally return false.

The calling code reads naturally:

$result = $validator->validate($input);

if ($result !== true) {
    // $result is the error message
    throw new ValidationException($result);
}

Stage 3: Array or String

public function process(array $items): array|string
{
    if (empty($items)) {
        return 'No items to process';
    }
    
    $results = [];
    foreach ($items as $item) {
        $results[] = $this->transform($item);
    }
    
    return $results;
}

The method got smarter. On success it returns structured data, on failure it returns why. The union type documents this contract right in the signature.

When to Use Each

• bool — When the caller truly only needs yes/no (toggle states, feature flags, existence checks)
• true|string — When failure needs explanation but success is just “it worked”
• array|string — When success produces data and failure needs explanation

The Takeaway

If you find yourself adding error logging inside a method that returns bool, that’s the signal. The method wants to tell you more than just true/false. Let the return type evolve to match what the method actually knows.

Union types aren’t just a PHP 8 feature to know about — they’re documentation that lives in the code itself. When you see true|string, you immediately know: success is silent, failure talks.

Mapping between your internal enums and an external API’s codes? PHP 8’s match() expression was built for this.

The Old Way

// ❌ Verbose and error-prone
function mapStatus(string $apiCode): string {
    if ($apiCode === 'ACT') return 'active';
    if ($apiCode === 'INA') return 'inactive';
    if ($apiCode === 'PND') return 'pending';
    if ($apiCode === 'CAN') return 'cancelled';
    throw new \InvalidArgumentException("Unknown code: $apiCode");
}

The Clean Way

// ✅ Exhaustive, readable, safe
function mapStatus(string $apiCode): string {
    return match($apiCode) {
        'ACT' => 'active',
        'INA' => 'inactive',
        'PND' => 'pending',
        'CAN' => 'cancelled',
        default => throw new \InvalidArgumentException(
            "Unknown status code: $apiCode"
        ),
    };
}

Why match() Is Better

• Strict comparison — no type juggling surprises
• Expression, not statement — can assign directly to a variable
• Exhaustive default — forces you to handle unknown values
• Readable — the mapping is a clean lookup table

Takeaway

Use match() for any code-to-value mapping. It’s cleaner than if/else chains, safer than arrays (because of the default throw), and reads like a lookup table.