PHP cURL custom headers

PHP cURL custom headers

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

Stefan Bogdanescu

Founder & Senior Architect

Adding Custom Headers to PHP cURL Requests

When emulating third-party services like iTunes, you often encounter non-standard HTTP headers that are required for authentication or content retrieval. In the specific case of fetching artwork, iTunes expects two custom headers: X-Apple-Tz and X-Apple-Store-Front. If your standard GET request returns a 403 Forbidden or empty response, it is almost certainly because these headers are missing.

In PHP, adding these headers to a cURL session is straightforward using the CURLOPT_HTTPHEADER option. This option accepts an array of header strings in the format "Name: Value". You must set this option before executing the request with curl_exec().

Here is the minimal implementation required to inject those specific headers:

$ch = curl_init('https://itunes.apple.com/...');

// Define the custom headers as an array of strings
$headers = [
    'X-Apple-Tz: 0',
    'X-Apple-Store-Front: 143444,12'
];

curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($ch);

The key technical detail here is that CURLOPT_HTTPHEADER replaces any default headers set by cURL, except for the mandatory ones like Host. This means if you do not explicitly add a Content-Type header and your request body is empty, it will likely work fine. However, if you are sending a POST request with data, you must ensure that Content-Type is included in the $headers array, or cURL might default to an incorrect content type depending on your specific library version and configuration.

Handling Multiple Header Sets

A common pitfall arises when developers try to mix standard headers (like Accept) with custom ones in a single array. While this usually works, it is important to remember the order of operations. All headers defined in the CURLOPT_HTTPHEADER option are sent exactly as specified. If you need to add standard headers like User-Agent, you must include them explicitly within that same array:

$headers = [
    'X-Apple-Tz: 0',
    'X-Apple-Store-Front: 143444,12',
    'Accept: application/json' 
];

Failing to include the Accept header when the server expects JSON can result in a fallback to HTML responses or, in stricter configurations, a rejection of the request. Always verify what the target API documentation requires for both custom and standard headers before finalizing your array.

Managing Session State Across Requests

If you are executing multiple requests within a single script—perhaps iterating through a list of albums—you must ensure that the header configuration does not persist incorrectly if you reuse the same cURL handle for unrelated requests. While CURLOPT_HTTPHEADER is generally session-scoped to the specific handle, it is often cleaner practice to create a new handle or explicitly clear headers between distinct logical operations if you are building a complex script.

Another consideration involves how these headers interact with proxies. If your application runs behind a proxy that modifies headers, you might find that custom headers get stripped or altered before reaching the target server. In such environments, ensure your proxy configuration allows X-Apple-* headers to pass through unmodified.

Validation and Error Handling

Finally, do not assume the request succeeds simply because curl_exec() returns data. You must check the HTTP status code. If the headers are incorrect or the values (like the Store Front ID) are outdated, iTunes will return an error response even if the connection is established. Always parse the response to confirm you received valid JSON and that no authentication warnings were present in the headers.

For complex API integrations, especially those involving sensitive data or large-scale scraping, consider leveraging a robust framework like Laravel to manage cURL sessions more cleanly. The ecosystem provides tools for managing middleware and client configurations that can abstract away much of the manual header management, reducing the risk of oversight. However, for direct script execution, mastering CURLOPT_HTTPHEADER remains the fundamental skill required.

Our network