Blog

Sometimes the best fix is deleting old fixes.

While consolidating API client code, I found this “normalization” logic in production:

$normalized = str_replace(
    ['SOAP-ENV:', 'xmlns:SOAP-ENV', 'xmlns:ns1'],
    ['soapenv:', 'xmlns:soapenv', 'xmlns'],
    $request
);

It looked intentional. Maybe the API was picky about namespace prefixes? Nope. It was breaking everything.

Removing the normalization fixed server errors that had been happening silently. The API worked fine with standard SOAP envelopes — the str_replace was stripping namespace declarations and causing “undeclared prefix” errors on the server side.

This kind of code survives because: (1) it was probably copy-pasted from a StackOverflow answer, (2) maybe it worked once on a different API, (3) nobody questioned it because it was already there.

When refactoring, actually test the old code path independently. Sometimes those “necessary” workarounds are just ancient bugs in disguise.

You’d think adding a timeout to PHP’s SoapClient would be straightforward. Maybe a constructor option like 'timeout' => 30?

Nope. Welcome to PHP SOAP hell.

The only way to set a request timeout on native SoapClient is ini_set():

ini_set('default_socket_timeout', 30);
$client = new SoapClient($wsdl, $options);

The connection_timeout constructor option? That’s only for the initial TCP handshake, not the actual SOAP call. It won’t save you from slow API responses.

But there’s a cleaner approach — extend SoapClient and override __doRequest() to use Guzzle:

class GuzzleSoapClient extends SoapClient
{
    private GuzzleClient $guzzle;

    public function __construct($wsdl, array $options = [])
    {
        parent::__construct($wsdl, $options);
        $this->guzzle = new GuzzleClient([
            'timeout' => $options['timeout'] ?? 30,
        ]);
    }

    public function __doRequest(
        $request, $location, $action, $version, $oneWay = 0
    ): ?string {
        $response = $this->guzzle->post($location, [
            'body' => $request,
            'headers' => ['SOAPAction' => $action],
        ]);
        return (string)$response->getBody();
    }
}

Drop-in replacement. Actual timeout support. No ini_set() hacks.

Quick quiz: what does processOrder($order, true, false, true, false, false) do?

You have no idea. Neither do I. And neither will you in three months when you come back to debug this code.

I used to think this was just “how PHP worked” — positional parameters, take it or leave it. Then PHP 8.0 dropped named parameters, and suddenly that cryptic boolean soup became self-documenting code.

Here’s the before and after:

// Before: positional boolean hell
function processOrder(
    Order $order,
    bool $validateStock = true,
    bool $sendEmail = false,
    bool $applyDiscount = true,
    bool $updateInventory = false,
    bool $logActivity = false
) {
    // ...
}

// What does this even mean?
processOrder($order, true, false, true, false, false);

// After: PHP 8 named parameters
processOrder(
    order: $order,
    validateStock: true,
    applyDiscount: true
);

// Or when you need to flip a flag deep in the parameter list:
processOrder(
    order: $order,
    sendEmail: true,
    logActivity: true
);

The beauty of named parameters is that you skip the defaults you don’t need. No more passing null, null, null, true just to reach the parameter you actually want to change.

This isn’t just about readability (though that’s huge). It’s about maintenance. When you add a new optional parameter, existing calls don’t break. When you reorder parameters (carefully!), named calls stay stable.

Rule of thumb: if you have more than two boolean parameters, or any boolean parameter after the first argument, use named parameters at the call site. Your code reviewers will love you.

PHP 8 is six years old now. If you’re not using named parameters yet, you’re missing out on one of the best DX improvements PHP has ever shipped.

Here’s a PHP gotcha that’s bitten me more than once when working with typed properties and external data sources like API responses or deserialized objects.

In PHP 7.4+, when you declare a typed property like this:

class ApiResponse
{
    public ResponseData $data;
}

You might assume that $data defaults to null if it’s never assigned. It doesn’t. It’s in an uninitialized state — which is different from null. Try to access it and you’ll get:

TypeError: Typed property ApiResponse::$data must not be accessed before initialization

This is especially common when deserializing API responses. If the external service returns a malformed payload missing expected fields, your deserializer creates the object but never sets the property. PHP then explodes when you try to read it.

The fix is straightforward — make the property nullable and give it a default:

class ApiResponse
{
    public ?ResponseData $data = null;
}

Two things changed: the ? prefix makes the type nullable, and = null provides an explicit default. Both are required — even a ?Type property without = null stays uninitialized.

Then add a null-safe check where you access it:

if (!$response->data?->items) {
    // Handle missing data gracefully
    return [];
}

The ?-> operator (PHP 8.0+) short-circuits to null instead of throwing an error. Clean and defensive.

The takeaway: Any typed property that might not get initialized — especially in DTOs, API response objects, or anything populated by external data — should be nullable with an explicit = null default. Don’t assume your data sources will always send complete payloads.