A Comprehensive Guide to Sending HTTP Response Codes in PHP

Introduction

In web development, HTTP response status codes are crucial for communication between servers and clients. They indicate the outcome of a request, such as success (2XX), redirection (3XX), client errors (4XX), or server errors (5XX). PHP offers multiple ways to send these codes, and this article systematically covers various methods based on PHP versions and historical compatibility.

Manually Assembling Response Lines with header() Function (PHP >= 4.0)

In PHP 4.0 and later, the header() function can be used to set HTTP response lines directly. This method involves specifying the full protocol and status code, for example:

header("HTTP/1.1 200 OK");

However, in FastCGI or CGI modes, PHP behavior may differ, requiring detection of the server API type:

$sapi_type = php_sapi_name();
if (substr($sapi_type, 0, 3) == 'cgi')
    header("Status: 404 Not Found");
else
    header("HTTP/1.1 404 Not Found");

Note: According to the HTTP RFC, the reason phrase can be any custom string conforming to standards, but for client compatibility, it is not recommended to use random strings. The php_sapi_name() function requires PHP 4.0.1 or higher.

Using the Third Parameter of header() Function (PHP >= 4.3)

Starting from PHP 4.3, the header() function introduced a third parameter, allowing for a more concise way to set response codes. However, the first parameter must be a non-empty string. Here are two common approaches:

header(':', true, 404);
header('X-PHP-Response-Code: 404', true, 404);

The second method is recommended because some minor browsers or web crawlers might have issues with header lines containing only a colon. The custom header field name (e.g., X-PHP-Response-Code) is not standardized but should be descriptive for better readability.

Using the http_response_code() Function (PHP >= 5.4)

PHP 5.4 introduced the http_response_code() function, which greatly simplifies setting status codes:

http_response_code(404);

This function handles protocol details automatically and is the preferred method in modern PHP development.

Compatibility Solutions

For projects requiring support for PHP versions below 5.4, a custom http_response_code function can be implemented for backward compatibility. The following code works for PHP 4.3 to 5.4:

if (!function_exists('http_response_code'))
{
    function http_response_code($newcode = NULL)
    {
        static $code = 200;
        if($newcode !== NULL)
        {
            header('X-PHP-Response-Code: '.$newcode, true, $newcode);
            if(!headers_sent())
                $code = $newcode;
        }       
        return $code;
    }
}

This function mimics the native behavior, ensuring consistent operation across different environments.

Common HTTP Status Codes Reference

HTTP status codes are categorized into several groups; here are some common examples:

• 100: Continue - The request has been received, and the client should continue sending.
• 200: OK - The request was successful.
• 301: Moved Permanently - The resource has been permanently moved.
• 404: Not Found - The requested resource does not exist.
• 500: Internal Server Error - An error occurred on the server.

A complete list can be referenced from RFC standards or online resources like Wikipedia's HTTP status codes page.

Best Practices and Considerations

When implementing HTTP status codes, consider the following:

• Always set status codes before outputting any content to avoid headers_sent() errors.
• In FastCGI environments, use the Status header instead of the full response line.
• For production environments, prefer http_response_code() for better code maintainability.
• Test compatibility with various clients, such as browsers and API tools.

Conclusion

PHP provides a range of methods from basic to advanced for sending HTTP response status codes. Developers should choose the appropriate method based on project requirements, PHP version, and server environment. Modern applications are advised to use http_response_code(), while legacy systems may require compatibility solutions. Proper use of status codes enhances the reliability and user experience of web applications.