README

A PSR-7 HTTP Message and PSR-17 HTTP Factory implementation for the Lighthouse framework.

Installation

composer require lighthouse/http

Requirements

PHP 8.2 or higher

Features

Full PSR-7 (HTTP Message) implementation
Full PSR-17 (HTTP Factories) implementation
Immutable value objects
Strict typing throughout
Zero dependencies beyond PSR interfaces

Quick Start

Creating a Request

use Lighthouse\Http\Request;

// Simple request
$request = new Request('GET', 'https://api.example.com/users');

// Request with headers and body
$request = new Request(
    method: 'POST',
    uri: 'https://api.example.com/users',
    headers: [
        'Content-Type' => 'application/json',
        'Accept' => 'application/json',
    ],
    body: json_encode(['name' => 'John'])
);

Creating a Server Request from Globals

use Lighthouse\Http\ServerRequest;

// Create from PHP superglobals
$request = ServerRequest::fromGlobals();

// Access request data
$method = $request->getMethod();
$path = $request->getUri()->getPath();
$query = $request->getQueryParams();
$body = $request->getParsedBody();

Creating a Response

use Lighthouse\Http\Response;

// Simple response
$response = new Response(200);

// Response with body
$response = new Response(
    statusCode: 200,
    headers: ['Content-Type' => 'application/json'],
    body: json_encode(['status' => 'ok'])
);

// Check response status
if ($response->isSuccessful()) {
    // 2xx response
}

Working with Streams

use Lighthouse\Http\Stream;

// Create from string
$stream = Stream::create('Hello, World!');

// Create from file
$stream = Stream::createFromFile('/path/to/file.txt', 'r');

// Read and write
$content = $stream->getContents();
$stream->write('more data');

Working with URIs

use Lighthouse\Http\Uri;

$uri = new Uri('https://user:pass@example.com:8080/path?query=value#fragment');

$scheme = $uri->getScheme();     // 'https'
$host = $uri->getHost();         // 'example.com'
$port = $uri->getPort();         // 8080
$path = $uri->getPath();         // '/path'
$query = $uri->getQuery();       // 'query=value'

// Modify (returns new instance)
$newUri = $uri->withPath('/new-path')->withQuery('new=query');

Using Factories (PSR-17)

use Lighthouse\Http\Factory\RequestFactory;
use Lighthouse\Http\Factory\ResponseFactory;
use Lighthouse\Http\Factory\StreamFactory;
use Lighthouse\Http\Factory\UriFactory;

$requestFactory = new RequestFactory();
$request = $requestFactory->createRequest('GET', 'https://example.com');

$responseFactory = new ResponseFactory();
$response = $responseFactory->createResponse(200, 'OK');

$streamFactory = new StreamFactory();
$stream = $streamFactory->createStream('content');

$uriFactory = new UriFactory();
$uri = $uriFactory->createUri('https://example.com');

PSR-7 Interfaces Implemented

Interface	Implementation
`MessageInterface`	`Message` (abstract)
`RequestInterface`	`Request`
`ServerRequestInterface`	`ServerRequest`
`ResponseInterface`	`Response`
`StreamInterface`	`Stream`
`UriInterface`	`Uri`
`UploadedFileInterface`	`UploadedFile`

PSR-17 Interfaces Implemented

Interface	Implementation
`RequestFactoryInterface`	`RequestFactory`
`ServerRequestFactoryInterface`	`ServerRequestFactory`
`ResponseFactoryInterface`	`ResponseFactory`
`StreamFactoryInterface`	`StreamFactory`
`UriFactoryInterface`	`UriFactory`
`UploadedFileFactoryInterface`	`UploadedFileFactory`

Immutability

All PSR-7 objects are immutable. Methods that appear to modify the object actually return a new instance:

$request = new Request('GET', 'https://example.com');

// This returns a NEW request - doesn't modify original
$newRequest = $request->withMethod('POST');

$request->getMethod();    // Still 'GET'
$newRequest->getMethod(); // 'POST'

Testing

composer test

License

MIT License. See LICENSE for details.

Part of the Lighthouse Framework

This package is part of the Lighthouse Framework, an educational PHP framework designed to teach how modern frameworks work internally.

lighthouse / http

Maintainers

Details