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.

Sending cookies to an API? Don’t hardcode the domain. Extract it from the URL instead.

The Problem

// ❌ Hardcoded domain — breaks when URL changes
$cookieJar->setCookie(new SetCookie([
    'Name' => 'session',
    'Value' => $token,
    'Domain' => 'api.example.com',
]));

Hardcoded domains break the moment someone changes the base URL in config, or you switch between staging and production environments.

The Fix

// ✅ Extract domain dynamically
$baseUrl = config('services.api.base_url');
$domain = parse_url($baseUrl, PHP_URL_HOST);

$cookieJar->setCookie(new SetCookie([
    'Name' => 'session',
    'Value' => $token,
    'Domain' => $domain,
]));

parse_url() with PHP_URL_HOST gives you just the hostname — no protocol, no path, no port. Clean and environment-agnostic.

Takeaway

Any time you need a domain, host, or path from a URL — use parse_url(). It handles edge cases (ports, trailing slashes, query strings) that string manipulation misses.

Not all UUIDs are created equal. When you need to replicate how a browser or external system generates identifiers, the version matters.

UUID v1 vs v4

UUID v4 is random — great for request IDs where uniqueness is all you need:

use Ramsey\Uuid\Uuid;

// Each request gets a unique random ID
$requestId = Uuid::uuid4()->toString();
// e.g., "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"

UUID v1 is time-based — useful for session IDs where sortability and temporal ordering matter:

// Session ID that encodes when it was created
$sessionId = Uuid::uuid1()->toString();
// e.g., "6ba7b810-9dad-11d1-80b4-00c04fd430c8"

When to Use Which

• v4 (random): Request IDs, correlation IDs, idempotency keys — anything where uniqueness matters but order doesn’t
• v1 (time-based): Session IDs, event IDs, audit logs — anything where you want to sort by creation time or match sequential behavior

Takeaway

Match the UUID version to the lifecycle. Random for one-off requests, time-based for persistent sessions. It’s a small detail that makes debugging much easier when you’re tracing requests through logs.

Working with an API that returns authentication tokens? Don’t hardcode the cache TTL. The API already tells you when the token expires — use it.

The Common Mistake

// ❌ Hardcoded — what if the API changes expiry?
Cache::put('api_token', $token, 3600);

Hardcoding means your cache could expire before the token does (wasting API calls) or after it does (causing auth failures).

The Fix

// ✅ Dynamic — uses what the API tells you
$response = Http::post('https://api.example.com/auth', [
    'client_id' => config('services.api.client_id'),
    'client_secret' => config('services.api.client_secret'),
]);

$data = $response->json();
$token = $data['access_token'];
$expiresIn = $data['expires_in']; // seconds

// Cache with a small buffer (expire 60s early)
Cache::put('api_token', $token, $expiresIn - 60);

The expires_in field is there for a reason. Subtract a small buffer (30-60 seconds) to avoid edge cases where your cache and the token expire at the same instant.

Takeaway

Let the API dictate your cache duration. It’s one less magic number in your codebase, and it automatically adapts if the provider changes their token lifetime.

Need to validate that a string contains multiple words in any order? Don’t write 6 permutations of the same regex. Use positive lookaheads instead.

The Problem

You want to check if a string contains “cat” AND “dog” AND “bird” in any order. The naive approach is a mess of permutations — 6 for 3 words, 24 for 4 words. No thanks.

The Fix: Chained Positive Lookaheads

$pattern = '/^(?=.*cat)(?=.*dog)(?=.*bird)/';
$text = 'I saw a bird, then a cat, then a dog';

if (preg_match($pattern, $text)) {
    echo 'All three words found!';
}

Each (?=.*word) is a separate assertion. All must pass. Order doesn’t matter. Add a fourth word? Add one more lookahead. Clean and scalable.

Takeaway

Positive lookaheads let you check multiple conditions without caring about order. Use (?=.*word) for each required word. Works in PHP, JavaScript, Python — basically everywhere.