A Clean Approach to HTTP Status Codes in PHP

Introduction

HTTP status codes are fundamental to web communication, but working with raw numbers in code can be problematic. Let's explore a better way to handle them in PHP.

The Problem with Numeric Status Codes

Using numbers directly leads to several issues:

• Poor readability - what does 418 mean at a glance?
• No IDE support for autocompletion
• Risk of typos with no validation
• Scattered definitions across a codebase

A Better Solution: The HTTPStatusCode Class

Here's how we can improve this with a dedicated class:

<?php
 
declare(strict_types=1);
 
namespace App\Http;
 
/**
 * Provides named constants and utilities for HTTP status codes
 */
final class HTTPStatusCode
{
    // Informational responses
    public const CONTINUE = 100;
    public const SWITCHING_PROTOCOLS = 101;
 
    // Successful responses
    public const OK = 200;
    public const CREATED = 201;
 
 
    /**
     * Returns the HTTP status message for a given code.
     * @throws InvalidArgumentException if the code is invalid.
     */
    public static function getMessage(int $code): string
    {
        return match ($code) {
            self::CONTINUE => 'Continue',
            self::NOT_FOUND => 'Not Found',
            self::INTERNAL_SERVER_ERROR => 'Internal Server Error',
            // ... (Full match cases in the url below)
            default => throw new \InvalidArgumentException("Invalid HTTP status code: $code"),
        };
    }
 
    /**
     * Checks if the status code is a client error (4xx).
     */
    public static function isClientError(int $code): bool
    {
        return $code >= 400 && $code < 500;
    }
 
    /**
     * Checks if the status code is a server error (5xx).
     */
    public static function isServerError(int $code): bool
    {
        return $code >= 500 && $code < 600;
    }
}

The full code is available on my GitHub. View it here.

Key Advantages

1. Improved Readability

   // Before
   if ($status === 404) { ... }
    
   // After
   if ($status === HTTPStatusCode::NOT_FOUND) { ... }

2. Built-in Validation

   try {
       $message = HTTPStatusCode::getMessage(999);
   } catch (\InvalidArgumentException $e) {
       // Handle invalid code
   }

3. IDE Support

   • Autocomplete for all status codes
   • Type hints and documentation

Practical Applications

API Responses

function createApiResponse(int $status, $data = null): array
{
    return [
        'status' => $status,
        'message' => HTTPStatusCode::getMessage($status),
        'data' => $data
    ];
}

Error Handling

if (HTTPStatusCode::isClientError($status)) {
    // handle client error or log it
}

Testing

$this->assertSame(
    HTTPStatusCode::OK,
    $response->getStatusCode()
);

Implementation Considerations

1. Immutable Design

   • The class is marked final to prevent extension
   • All methods are static since no instance state is needed

2. Performance

   • The messages array is defined once in memory
   • No object instantiation overhead

3. Extensibility

   • Easy to add new utility methods
   • Simple to update status messages if needed

Conclusion

This approach provides a clean, maintainable way to work with HTTP status codes in PHP. By using named constants and centralizing the definitions, we get:

• Better code clarity
• Reduced chance of errors
• Improved developer experience
• Easier maintenance

The complete implementation can be dropped into any PHP project and immediately improve how status codes are handled.