README

Utility classes, constants, and typed exceptions for PSR-7 HTTP operations, providing a complete HTTP status code registry with metadata and throwable exceptions for all 4xx/5xx status codes.

Introduction

Why This Library Exists

Working with HTTP in PHP often involves scattered magic numbers, inconsistent error handling, and repetitive exception creation. The PSR-7 standard defines message interfaces but doesn't provide status code constants, metadata, or exception types.

This library provides a complete HTTP toolkit:

• Status code constants: All standard HTTP status codes as class constants
• Method constants: HTTP method names (GET, POST, PUT, DELETE, etc.)
• Status metadata: Human-readable names, descriptions, and documentation URLs
• Typed exceptions: Dedicated exception classes for every 4xx and 5xx status code
• Exception hierarchy: Catch client errors (4xx) or server errors (5xx) separately

Problems This Library Solves

1. Magic numbers: Code uses 404 instead of readable STATUS_NOT_FOUND
2. Inconsistent exceptions: Each project invents its own HTTP exception classes
3. Missing metadata: Status codes lack human-readable descriptions
4. Catch-all handling: No way to catch only client errors vs. server errors
5. Documentation gaps: Developers must look up status code meanings externally

Where to Use This Library

• PSR-7 applications: Enhance HTTP message handling with typed constants
• API development: Throw semantically correct HTTP exceptions
• Error handling middleware: Catch exceptions by category (client/server)
• Logging and monitoring: Include status metadata in error reports
• HTTP clients: Use constants instead of magic numbers

Design Goals

1. PSR-7 aligned: Implements Fig\Http\Message\StatusCodeInterface
2. Complete coverage: All standard HTTP status codes (1xx through 5xx)
3. Rich metadata: Name, phrase, and documentation URL for each status
4. Exception hierarchy: Abstract base classes for client (4xx) and server (5xx) errors
5. Type-safe: Full strict types and interface contracts

Requirements

• PHP 8.3 or higher
• fig/http-message-util ^1.1

Installation

Install by adding the package as a Composer requirement:

composer require ctw/ctw-http

Usage Examples

HTTP Status Metadata

Retrieve complete metadata for any status code:

use Ctw\Http\HttpStatus; $httpStatus = new HttpStatus(HttpStatus::STATUS_NOT_FOUND); $entity = $httpStatus->get(); // Returns: // Ctw\Http\Entity\HttpStatus { // +statusCode: 404 // +name: "Not Found" // +phrase: "The requested resource could not be found but may be available again in the future." // +exception: "Ctw\Http\HttpException\NotFoundException" // +url: "https://httpstatuses.com/404" // }

Throwing HTTP Exceptions

Each 4xx and 5xx status code has a dedicated exception class:

use Ctw\Http\HttpException; // Default message uses status name throw new HttpException\NotFoundException(); // "404 Not Found" // Custom message throw new HttpException\NotFoundException('User with ID 123 not found'); // "User with ID 123 not found" // With custom headers throw new HttpException\UnauthorizedException( message: 'Invalid API key', headers: ['WWW-Authenticate' => 'Bearer'] );

Catching Exceptions by Category

The exception hierarchy allows catching by error category:

use Ctw\Http\HttpException; try { // Application code } catch (HttpException\AbstractClientErrorException $e) { // Handle 4xx errors (client's fault) $statusCode = $e->getStatusCode(); $headers = $e->getHeaders(); } catch (HttpException\AbstractServerErrorException $e) { // Handle 5xx errors (server's fault) } // Or catch all HTTP exceptions try { // Application code } catch (HttpException\HttpExceptionInterface $e) { // Handle any HTTP exception }

Exception Hierarchy

HttpExceptionInterface └── AbstractException ├── AbstractClientErrorException (4xx) │ ├── BadRequestException (400) │ ├── UnauthorizedException (401) │ ├── ForbiddenException (403) │ ├── NotFoundException (404) │ └── ... (all 4xx codes) └── AbstractServerErrorException (5xx) ├── InternalServerErrorException (500) ├── NotImplementedException (501) ├── BadGatewayException (502) ├── ServiceUnavailableException (503) └── ... (all 5xx codes) 

HTTP Method Constants

use Ctw\Http\HttpMethod; HttpMethod::METHOD_GET; // 'GET' HttpMethod::METHOD_POST; // 'POST' HttpMethod::METHOD_PUT; // 'PUT' HttpMethod::METHOD_PATCH; // 'PATCH' HttpMethod::METHOD_DELETE; // 'DELETE' HttpMethod::METHOD_HEAD; // 'HEAD' HttpMethod::METHOD_OPTIONS; // 'OPTIONS' HttpMethod::METHOD_CONNECT; // 'CONNECT' HttpMethod::METHOD_TRACE; // 'TRACE' HttpMethod::METHOD_PURGE; // 'PURGE'

HTTP Status Constants

use Ctw\Http\HttpStatus; // Informational (1xx) HttpStatus::STATUS_CONTINUE; // 100 HttpStatus::STATUS_SWITCHING_PROTOCOLS; // 101 // Success (2xx) HttpStatus::STATUS_OK; // 200 HttpStatus::STATUS_CREATED; // 201 HttpStatus::STATUS_ACCEPTED; // 202 HttpStatus::STATUS_NO_CONTENT; // 204 // Redirection (3xx) HttpStatus::STATUS_MOVED_PERMANENTLY; // 301 HttpStatus::STATUS_FOUND; // 302 HttpStatus::STATUS_NOT_MODIFIED; // 304 HttpStatus::STATUS_TEMPORARY_REDIRECT; // 307 HttpStatus::STATUS_PERMANENT_REDIRECT; // 308 // Client Error (4xx) HttpStatus::STATUS_BAD_REQUEST; // 400 HttpStatus::STATUS_UNAUTHORIZED; // 401 HttpStatus::STATUS_FORBIDDEN; // 403 HttpStatus::STATUS_NOT_FOUND; // 404 HttpStatus::STATUS_METHOD_NOT_ALLOWED; // 405 HttpStatus::STATUS_CONFLICT; // 409 HttpStatus::STATUS_UNPROCESSABLE_ENTITY; // 422 HttpStatus::STATUS_TOO_MANY_REQUESTS; // 429 // Server Error (5xx) HttpStatus::STATUS_INTERNAL_SERVER_ERROR; // 500 HttpStatus::STATUS_NOT_IMPLEMENTED; // 501 HttpStatus::STATUS_BAD_GATEWAY; // 502 HttpStatus::STATUS_SERVICE_UNAVAILABLE; // 503 HttpStatus::STATUS_GATEWAY_TIMEOUT; // 504

Available Exception Classes