How to set default header in Guzzle?

How to set default header in Guzzle?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How to set default header in Guzzle?

If you are maintaining a legacy codebase using Guzzle 4 or older, you might still be looking at $client->setDefaultHeaders($headers) to avoid passing headers on every request. That method is deprecated because it forces state mutation onto the client object, which creates hidden coupling between your HTTP layer and the application logic. The modern approach in Guzzle 6 and later shifts this responsibility from the client instance to the request options array, allowing for a more flexible and testable architecture.

The core issue with setting default headers on the client directly is that it assumes every request you make will share the exact same configuration. In distributed systems or complex applications, you often need to inject different headers based on context—such as user IDs, API keys, or environment variables—without cluttering your request builder with repetitive logic. By leveraging the request.options array, you can define a baseline of defaults that applies universally while retaining the ability to override specific values when necessary.

Here is how you initialize a client and apply default headers using the current standard:

$baseUrl = 'http://foo';
$config = [
    'defaults' => [
        'headers' => [
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
        ],
    ],
];
$client = new \GuzzleHttp\Client($baseUrl, $config);

Notice the defaults key inside the configuration array. This is where Guzzle expects to find your global settings. When you create a new request using $client->post(), Guzzle automatically merges these defaults with any headers you explicitly pass in that specific call. The explicit parameters take precedence over the configured defaults, preventing accidental data leaks or incorrect API versions from propagating unintentionally.

This pattern aligns with functional programming principles where you compose functions by passing arguments rather than relying on global state. If you need to add a custom header for a single request, you simply include it in the second argument of your method call:

$response = $client->post('/api/resource', [
    'headers' => [
        'X-Custom-Header' => 'special-value',
    ],
]);

In this scenario, Guzzle merges the default headers defined in $config with the inline headers provided in the request array. The resulting set of headers is what gets sent over the wire. This merging happens before the request is dispatched, ensuring that your defaults act as a safety net for common cases like Accept or Content-Type, while still allowing granular control when specific overrides are required.

One potential pitfall to watch out for is collision between default and inline headers. If you define Authorization in your defaults but then forget to remove it when making an internal request that shouldn't include authentication, you might expose credentials unnecessarily. Always ensure that your override logic explicitly removes sensitive or context-specific headers if they are not needed for a particular endpoint.

For developers working within the Laravel ecosystem, this pattern integrates seamlessly with service container bindings. You can bind a single Guzzle client instance configured with these defaults into your application container and reuse it across controllers and services without repeating configuration code. This keeps your HTTP clients consistent and reduces the surface area for misconfiguration errors.

Our network