PHP Luminova: Managing Incoming HTTP Request Headers

The HTTP Header class allows you to manage request headers, similar to the way the Luminova\Http\Server class that handles server-parameters. It provides methods to interact with, retrieve, and manipulate request headers, simplifying the process of managing HTTP requests.

Class Definition

• Class namespace: Luminova\Http\Header
• This class implements: Luminova\Interface\LazyObjectInterface, \Countable

Examples:

The Header object is available in the Request class object as a public property $request->header.

Get the value for a specific key:

$value = $header->get('User-Agent');

Set a new value for a key:

$header->set('User-Agent', 'New User Agent');

Remove a key:

$header->remove('Accept');

Search for a value:

$key = $header->search('Host');

Check if a key exists:

if ($header->has('Accept-Encoding')) {
    // Key exists
}

Count the number of elements:

$count = $header->count();

Methods

constructor

Initializes the header constructor.

The constructor accepts an optional headers. If no headers are passed, it will use the request headers.

public __construct(?array $variables = null): mixed

Parameters:

get

Retrieves the value of a specific header or all headers if no name is provided.

public get(?string $name = null, mixed $default = null): mixed|array|string|null

Parameters:

Return Value:

mixed|array|string|null - Return the value of the specified header, or all headers if $name is null.

set

Sets the value for a specific header.

public set(string $key, mixed $value): void

Parameters:

remove

Removes a specific header by its key.

public remove(string $key): void

Parameters:

has

Checks if a specific header key exists.

public has(string $key): bool

Parameters:

Return Value:

bool - Return true if the key exists, false otherwise.

count

Gets the total number of header variables.

public count(): int

Return Value:

int - Return the number of header variables.

send

Send HTTP headers to the client.

Handles safe header dispatch with optional REST validation and CORS checks.Prevents duplicate header output and provides clear diagnostics when headerswere already sent.

Behavior:

• Optionally aborts if headers were already sent.
• Sends HTTP status code when provided.
• Removes entity headers for 204 / 304 responses.
• Appends charset to Content-Type when missing (optional).
• Optionally validates headers for API / REST requests.

public static send(
    array<string,string|int|float> $headers,
    bool $ifNotSent = true,
    bool $charset = false,
    ?int $status = null,
    ?bool $validateRequestHeaders = null
): void

Parameters:

Throws:

• RuntimeException - When headers are already sent and debugging is enabled.

parse

Normalize headers without sending them.

Behavior:

• Applies system default headers when X-System-Default-Headers is present.
• Optionally validates REST / API headers.
• Appends charset to Content-Type when missing.
• Returns an empty array when headers are already valid or unchanged.

public static parse(array<string,mixed> $headers, bool $validateRequestHeaders = false): array<string,mixed>

Parameters:

Return Value:

array<string,mixed> - Returns the normalized headers, or empty array if no changes are required.

sendNoCacheHeaders

Send no-cache HTTP headers.

This method sends HTTP headers to disable caching and optionally set content type and retry behavior.

public static sendNoCacheHeaders(
    int $status = 200, 
    string|bool|null $contentType = null, 
    string|int|null $retry = null
): void

Parameters:

Return Value:

void - > Used by router and template rendering to prevent caching.

sendStatus

Sends HTTP response status code if it is valid.

This method checks if the provided status code is within the valid HTTP status code rangebefore sending it using the http_response_code function. It also sets the REDIRECT_STATUS superglobal.

static function sendStatus(int $code): bool 

Parameters:

Return Value:

bool - Return true if status code is valid and set, false otherwise.

terminate

Terminates the request by sending a status and formatted message.

Responds according to the Accept header:

• application/json → JSON response
• application/xml / text/xml → XML response
• text/html → HTML page
• fallback → plain text

public static terminate(
    int $status,
    string $message,
    ?string $title = null,
    int $retry = 3600
): void

Parameters:

getHeaders

Extracts all request headers using apache_request_headers or the $_SERVER variables.

public static getHeaders(): array<string,string>

Return Value:

array<string,string> - Return the request headers.

getFromGlobal

Parse _SERVER variables and extract headers from it.

public static getFromGlobal(?array $server = null): array<string,string>

Parameters:

Return Value:

array<string,string> - Return the parsed headers.

getAllowedOrigin

Retrieve the allowed origin based on configuration.

• Returns * if all origins are allowed.
• Returns the matching origin if it is explicitly allowed.
• Returns null if the origin is forbidden or missing when forbidEmptyOrigin is enabled.

public static getAllowedOrigin(?string $origin = null): ?string

Parameters:

Return Value:

string|null - Returns the allowed origin, * for all, or null if forbidden.

clearOutputBuffers

Clear or flush PHP output buffers with flexible modes.

Modes:

• auto (default): Clears all but the base buffer if multiple exist; otherwise clears the top buffer.
• all: Clears every active buffer down to the specified limit (default 0 for all).
• top: Clears only the top-most buffer.
• flush: Flushes the top-most buffer without clearing it.

public static clearOutputBuffers(string $mode = 'auto', int $limit = 0): bool

Parameters:

Return Value:

bool - Returns true if any buffer was cleared or flushed; false if no buffers existed.

isAllowedOrigin

Determine whether a given origin is allowed based on application API configuration.

public static isAllowedOrigin(?string $origin = null): bool

Parameters:

Return Value:

bool - Returns true if the origin is allowed, false otherwise.

isAllowedHeaders

Validates request headers against allowed headers, based on application API configuration.

public static isAllowedHeaders(array<string,string|int|float>|null $headers = null, ?string &$match = null): bool

Parameters:

Return Value:

bool - Return true if all headers are valid, false otherwise.

setOutputHandler

Initializes the output buffer with the appropriate content-encoding handler.

This method is a wrapper around ob_start(). It detects supported encodings(such as gzip or deflate) from the client’s request headers and appliesthe proper output handler when compression is enabled and supported. If nomatching encoding is found, it falls back to a custom or default handler.

If output buffering is already active, it will not be restarted.

public static setOutputHandler(bool $clearIfSet = false, bool $withHandler = true): bool

Parameters:

Return Value:

bool - Returns true if a new output buffer is started, false otherwise.