README

Waffle Commons - HTTP Component

A lightweight, strict, and fully tested PSR-7 and PSR-17 implementation for the Waffle Framework ecosystem. This component provides the fundamental HTTP message objects (Request, Response, Stream, URI, UploadedFile) required for modern PHP applications.

Features

PSR-7 Compliance: Full implementation of HTTP Message interfaces (Request, Response, ServerRequest, Stream, Uri, UploadedFile).
PSR-17 Factories: Includes factories for creating all HTTP objects, ensuring interoperability with other libraries.
Strict Typing: Built with PHP 8.4+ strict types for reliability.
Zero Dependencies: No external dependencies other than psr/http-message and psr/http-factory.
Secure by Design: Robust handling of headers, file uploads, and streams.

Installation

You can install the package via Composer:

composer require waffle-commons/http

Usage

1. Creating a Request from Globals (Bootstrap)

The GlobalsFactory is designed to capture the current PHP environment (superglobals like $_SERVER, $_POST, $_FILES) and convert it into a PSR-7 ServerRequestInterface. This is typically used at the entry point of your application (index.php).

use Waffle\Commons\Http\Factory\GlobalsFactory;

// Create the factory
$factory = new GlobalsFactory();
// Capture the current request
$request = $factory->createFromGlobals();

echo $request->getMethod();
// e.g., "GET"  echo $request->getUri()->getPath();
// e.g., "/api/users"

2. Creating Responses

You can create responses manually or using the PSR-17 ResponseFactory.

Manual Instantiation:

use Waffle\Commons\Http\Response;

// Create a 200 OK response with JSON content
$response = new Response(
    200,
    ['Content-Type' => 'application/json'],
    json_encode(['status' => 'ok'])
);

Using Factory (Recommended for decoupling):

use Waffle\Commons\Http\Factory\ResponseFactory;

$factory = new ResponseFactory();
$response = $factory->createResponse(404, 'Resource Not Found');

3. Emitting a Response

To send the response to the client (browser), use the ResponseEmitter.

use Waffle\Commons\Http\Emitter\ResponseEmitter;

$emitter = new ResponseEmitter();
$emitter->emit($response);

4. Using PSR-17 Factories

This package provides implementations for all PSR-17 factory interfaces, allowing you to create HTTP objects in a standard way.

Waffle\Commons\Http\Factory\RequestFactory: Creates client-side requests.
Waffle\Commons\Http\Factory\ServerRequestFactory: Creates server-side requests.
Waffle\Commons\Http\Factory\ResponseFactory: Creates responses.
Waffle\Commons\Http\Factory\StreamFactory: Creates streams from strings, files, or resources.
Waffle\Commons\Http\Factory\UriFactory: Creates URI objects.
Waffle\Commons\Http\Factory\UploadedFileFactory: Creates uploaded file objects.

Example creating a stream:

use Waffle\Commons\Http\Factory\StreamFactory;

$factory = new StreamFactory();
$stream = $factory->createStream('Hello World');

echo $stream->getContents(); // "Hello World"

Testing

This component is fully tested with PHPUnit.

composer tests

Contributing

Contributions are welcome! Please refer to CONTRIBUTING.md for details.

License

This project is licensed under the MIT License. See the LICENSE.md file for details.

waffle-commons / http

Maintainers

Details