Download the PHP package jacksonsr451/php-easy-http without Composer

PHP Easy HTTP

Modern PSR-7/PSR-15 inspired toolkit for building lightweight HTTP services and FastAPI-like microservices in PHP. Ships with strict-typed message objects, a declarative router, middleware pipeline, and an ergonomic Application class for rapid development.

Requirements

• PHP 8.2+ (tested through PHP 8.3)
• Composer for dependency management

Installation

The package exposes all classes under the PhpEasyHttp\Http namespace through PSR-4 autoloading.

Key Features

• PSR-7 message implementations (Message, Request, Response, ServerRequest, Stream, Uri, UploadFiles).
• FastAPI-inspired Application with declarative routing helpers (get, post, put, patch, delete).
• Dependency Injection Container for constructor-free service registration and parameter auto-wiring.
• Middleware pipeline compatible with PSR-15 style process() methods plus helper registration (use, registerMiddleware).
• Automatic response normalization: arrays/objects become JSON, scalars become JSON payloads, strings become text responses.
• Route parameter binding & validation with typed handler signatures.

Project Structure

Quick Start

Visit http://localhost:8000/ping to receive a JSON payload.

Declarative Routing

• Paths can contain {param} placeholders; values are injected by name.
• Route metadata (name, summary, tags) is preserved for tooling or documentation generators.

FastAPI-Style Declarative Routes

Skip the manual route table by annotating controller methods with PHPDoc comments or native PHP attributes. Any public method that declares a route directive/attribute is automatically registered when you call registerControllers().

Using PHPDoc

Using Native PHP Attributes

• Use @Route or #[Route] to declare method + path; multiple HTTP verbs are allowed via arrays or GET|POST strings.
• Optional metadata: Summary, Tags, Middleware, and Name map 1:1 between PHPDoc directives and attribute named parameters.
• Add a class-level @RoutePrefix/@Prefix directive or #[RoutePrefix]/#[Prefix] attribute for shared path segments.
• Controllers can be registered as class names or instances (resolved through the container when available).

API Gateway Style Dynamic Routes

The jacksonsr45/api-gateway package ships with a thin layer on top of Application that mimics APISIX-style route management. Routes can be loaded from JSON/YAML files, database records, or an admin API (via custom GatewayRouteSource implementations). Each GatewayRoute entry accepts:

Exactly one of handler or proxy must be provided. Proxy handlers receive the current ServerRequestInterface (with route params stored as request attributes) and return a PSR-7 response. Unlike APISIX, proxying is fully in-process (no external HTTP hop) so you can encapsulate orchestration logic inside PHP classes.

Loading Routes from a File

gateway.yaml (JSON works the same):

Create additional GatewayRouteSource implementations (database, HTTP admin API, etc.) and feed them to Gateway::addSource() to merge multiple configuration backends. Because the router builds on top of the existing Application, you can reuse FastAPI-style handlers, middleware, and dependency injection with zero duplication.

Handler Parameter Binding

Handlers can type-hint any of the following and the application resolves them automatically:

If a parameter cannot be resolved and lacks a default value, an exception is thrown to highlight configuration issues early.

Dependency Injection

• register(string $id, callable|object|string $concrete) binds services.
• Singleton-style instantiation: the container caches resolved instances.
• String bindings are treated as class names and instantiated lazily.

Middleware

Implement MiddlewareInterface (PSR-15 style) or reuse existing classes.

• use() attaches middleware globally in the order registered.
• Route-level middleware can be provided via the middleware option array.
• When registering middleware by string name, Application looks it up in the middleware map before instantiating.

Response Handling

Your handler may return:

• A ResponseInterface if you need full control.
• An array/object → automatically encoded as JSON with application/json headers.
• A string → emitted as text/plain; charset=utf-8.
• Scalars/bools/null → wrapped in a JSON envelope ({"data": ...}).

You can create responses manually with ResponseFactory:

Working with Requests

• ServerRequest::getParsedBody() inspects content-type and will decode JSON or form data automatically.
• ServerRequest::withUploadedFiles() accepts PSR-7 UploadFileInterface objects.
• Helper methods such as inPost() or withAttribute() allow you to tag requests while processing middleware.

Running & Emitting Responses

$app->run() returns the generated response by default and also emits it (headers + body). To take control of the emission (useful in testing pipelines) set emit: false:

Testing

Create ServerRequest instances manually and pass them to run():

Roadmap

• Validation & schema-based request parsing
• Automatic OpenAPI generation from route metadata
• Async/worker adapters for popular PHP runtime servers

Contributing

1. Fork the repository and create a topic branch.
2. Run composer install followed by composer test (when available).
3. Submit a pull request with a concise description of your changes and any relevant tests.

Please open an issue if you encounter bugs or have feature requests.