Download the PHP package ctw/ctw-http without Composer

Package "ctw/ctw-http"

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:

Usage Examples

HTTP Status Metadata

Retrieve complete metadata for any status code:

Throwing HTTP Exceptions

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

Catching Exceptions by Category

The exception hierarchy allows catching by error category:

Exception Hierarchy

HTTP Method Constants

HTTP Status Constants

Available Exception Classes