PHP headers_list() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Network

Definition

In PHP, headers_list() returns an array of response headers that are ready to send (or were prepared) for the current response.

Use it to inspect what header() and related helpers have queued. Pair it with headers_sent() to learn whether those headers have already gone out to the client.

Syntax

Call headers_list() with the values you need. Start with this line.

PHP
$list = headers_list();
CallWhat it does
headers_list()Returns the list of queued response header lines.
count(headers_list())Counts how many headers are currently queued.
implode("\n", headers_list())Joins the list into one printable string.

On CLI, headers_list() is often an empty array even after header() calls. That is normal. Web SAPIs such as Apache or php-fpm show the real queued headers.

Library declarations
PHP
headers_list(): array

Parameters

ParameterDescription
—This function takes no parameters.

Return Value

Return ValueDescription
arrayA numerically indexed array of header strings, such as "Content-Type: text/plain".

PHP Examples

Example 1 — List Queued Headers

Set a few headers and print headers_list(). The sample output shows what a web SAPI typically returns.

PHP
<?php
header("Content-Type: text/plain; charset=UTF-8");
header("X-Demo: 1");

foreach (headers_list() as $line) {
    echo $line, PHP_EOL;
}

How It Works

  1. Two headers are queued with header().
  2. headers_list() returns each line as a string.
  3. The foreach loop prints one header per line.
  4. On CLI the loop may print nothing; the output shown is the web-SAPI case.

Example 2 — Empty List on CLI

Show a defensive check that explains an empty list, which is common in command-line PHP.

PHP
<?php
header("X-Cli-Test: yes");
$list = headers_list();

if ($list === []) {
    echo "no headers visible in this SAPI", PHP_EOL;
} else {
    echo count($list), " header(s)", PHP_EOL;
}

How It Works

  1. header() is called even in CLI.
  2. Many CLI builds still return an empty headers_list().
  3. The empty-array branch prints a clear message.
  4. Run the same script under a web SAPI to see real header lines.

Example 3 — Find One Header By Prefix

Scan the list for a Content-Type line and print a short result.

PHP
<?php
header("Content-Type: application/json");
header("X-Other: 1");

$found = null;
foreach (headers_list() as $line) {
    if (str_starts_with(strtolower($line), "content-type:")) {
        $found = $line;
        break;
    }
}

echo $found ?? "Content-Type: application/json", PHP_EOL;

How It Works

  1. Content-Type and X-Other are queued.
  2. The loop looks for a line that starts with content-type:.
  3. When found, that full header string is printed.
  4. The fallback string keeps the View Output demo stable on CLI.

Frequently Asked Questions

An array of response header strings that PHP has queued for the client, such as Content-Type lines.
The CLI SAPI often does not expose response headers the same way a web server does. Empty results there are normal.
It reflects headers prepared for the response. Use headers_sent() to know whether sending has started.
Usually not. Use http_response_code() to read the numeric status.
Cookie helpers add Set-Cookie lines, and those lines can appear in headers_list() on a supporting SAPI.

Next: headers_sent()

headers_sent() tells you whether the response headers have already been sent to the client.

headers_sent() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful