Blog

You have a method that accepts an interface type hint. Then a new caller needs to use the same method, but its object doesn’t implement that interface. The lazy fix? Widen the type hint to object and check with instanceof.

Here’s when that’s actually the right call.

The problem

Say you have a repository method that handles invalid configuration:

class ConfigRepository
{
    public function handleInvalidConfig(
        string $configKey,
        SyncableInterface $handler
    ): void {
        $mapping = $handler->getConfigMapping($configKey);
        $mapping->markInvalid();
        $mapping->save();
    }
}

This works great — until a new type of handler comes along that doesn’t implement SyncableInterface but still needs to report invalid configuration. The handler doesn’t have config mappings at all; it just needs the “mark as invalid” side of the logic.

You get a TypeError:

ConfigRepository::handleInvalidConfig(): Argument #2 ($handler) must be of type SyncableInterface, BasicHandler given

The fix: widen and guard

class ConfigRepository
{
    public function handleInvalidConfig(
        string $configKey,
        object $handler
    ): void {
        if (!$handler instanceof SyncableInterface) {
            // This handler doesn't support config mapping — skip gracefully
            return;
        }

        $mapping = $handler->getConfigMapping($configKey);
        $mapping->markInvalid();
        $mapping->save();
    }
}

When this pattern makes sense

This isn’t “make everything object and pray.” It’s appropriate when:

• The caller hierarchy is fixed — you can’t easily make all callers implement the interface (e.g., the method is called from a shared base class)
• The behavior is optional — not all callers need the full logic, some just need to pass through
• The alternative is worse — duplicating the method or adding a parallel code path creates more maintenance burden

The alternative: multiple interfaces

If you find yourself widening type hints often, it might signal that your interface is doing too much. Consider splitting:

interface ReportsInvalidConfig
{
    public function getConfigMapping(string $key): ConfigMapping;
}

interface SyncableInterface extends ReportsInvalidConfig
{
    public function sync(): void;
}

// Now the method can type-hint the narrow interface
public function handleInvalidConfig(
    string $configKey,
    ReportsInvalidConfig $handler
): void {
    $mapping = $handler->getConfigMapping($configKey);
    $mapping->markInvalid();
    $mapping->save();
}

This is cleaner long-term, but requires changing the interface hierarchy — not always possible in legacy codebases or when you’re shipping a hotfix at 2 AM.

The pragmatic rule: object + instanceof for hotfixes and optional behavior. Interface segregation for planned refactors. Both are valid — just know which situation you’re in.

Here’s a subtle way constructors can blow up in production: eagerly loading optional configuration that the current execution path doesn’t need.

Imagine you have a class that manages API credentials for both live and sandbox modes:

class GatewayCredentials
{
    private string $apiKey;
    private ?string $sandboxApiKey;
    private string $secretKey;
    private ?string $sandboxSecretKey;

    public function __construct(array $config, array $sandboxConfig)
    {
        $this->apiKey = $config['api_key'];
        $this->sandboxApiKey = $sandboxConfig['api_key'];     // 💥 crashes here
        $this->secretKey = $config['secret_key'];
        $this->sandboxSecretKey = $sandboxConfig['secret_key']; // 💥 or here
    }
}

The constructor always loads both live and sandbox credentials, even when the app is running in production mode and will never touch the sandbox values. If the sandbox config is incomplete (missing keys, empty array, or null), PHP 8 promotes undefined array key access from a notice to a warning — and frameworks like Laravel convert that warning into an ErrorException — and your production checkout page crashes because of test data that isn’t even needed.

The fix: defer with null coalescing

class GatewayCredentials
{
    private string $apiKey;
    private ?string $sandboxApiKey;
    private string $secretKey;
    private ?string $sandboxSecretKey;
    private bool $sandboxMode;

    public function __construct(array $config, array $sandboxConfig, bool $sandboxMode = false)
    {
        $this->sandboxMode = $sandboxMode;

        // Live credentials are always required
        $this->apiKey = $config['api_key'];
        $this->secretKey = $config['secret_key'];

        // Sandbox credentials are optional — don't crash if missing
        $this->sandboxApiKey = $sandboxConfig['api_key'] ?? null;
        $this->sandboxSecretKey = $sandboxConfig['secret_key'] ?? null;
    }

    public function getApiKey(): string
    {
        return $this->sandboxMode
            ? ($this->sandboxApiKey ?? throw new \RuntimeException('Sandbox API key not configured'))
            : $this->apiKey;
    }
}

The key insight: use ?? for optional config in the constructor, but fail loudly at the point of use if the value is actually needed. This way:

• Production never crashes due to missing test config
• Sandbox mode still fails fast with a clear error message
• The constructor stays defensive without hiding real problems

This pattern applies anywhere you have multi-environment or multi-mode configuration. Don’t let eagerly loaded optional data crash the paths that don’t use it.

You find the bug. It’s a one-liner — the wrong array key was being used in a calculation. You swap it, tests pass, PR ready.

But you’re not done yet.

The One-Liner That Revealed Dead Code

After fixing a calculation that was reading from the wrong field in a data array, I asked a simple question: is the old field still used anywhere?

A quick grep showed it wasn’t. The entire block that computed that intermediate value — an assignment, a conditional, a helper call — was now dead code. Nobody else referenced it. The bug fix had made it obsolete.

What started as a 1-line insertion became a 1-line insertion + 8-line deletion. The codebase got smaller and cleaner.

Why This Matters

Every dead code block is:

• A maintenance trap. Someone will read it later and try to understand why it exists.
• A false signal. It implies the computed value matters. Future developers might wire it back in.
• A merge conflict magnet. It takes up space in files that people will edit for unrelated reasons.

The Post-Fix Checklist

After every bug fix, before you open the PR, run through this:

1. Search for the old value. If you changed which variable/field is read, check if the old one is still referenced. grep -rn 'old_field_name' app/
2. Trace the computation chain. If the fix changed a formula’s input, check if any intermediate variables in the old computation are now unused.
3. Check the callers. If you changed a method’s return value, verify all callers still make sense.
4. Look one level up. Sometimes fixing a bug in a helper method means the error-handling code that worked around that bug is now unnecessary.

A Real Metric

Some of the best PRs I’ve reviewed have more deletions than insertions. A bug fix that deletes more than it adds is a sign that someone actually understood the ripple effects of their change.

The fix is the minimum. The cleanup is the craftsmanship.