pilotphp/http

HTTP transport boundary and compiled route map for the PilotPHP Agent-First framework.

0.1.4 2026-08-02 19:19 UTC

Requires

• php: ^8.5
• pilotphp/contracts: ^0.1.2
• pilotphp/runtime: ^0.1.2
• psr/http-factory: ^1.1
• psr/http-message: ^2.0
• psr/http-server-handler: ^1.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.88
• nyholm/psr7: ^1.8
• phpstan/phpstan: ^2.1
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^11.5

MIT

• routing
• http
• transport
• psr-7
• agent-first
• pilotphp

Published on Packagist.org on 2026-08-02 16:22 UTC

README

HTTP transport boundary for the PilotPHP Agent-First framework.

pilotphp/http lets application packages declare HTTP routes, compiles those declarations into a deterministic http/route-map.json artifact, loads that artifact at runtime, matches PSR-7 requests, maps them into contracts-owned invocations, and maps results back to PSR-7 responses.

It is not a web application skeleton, HTTP server, DI container, operation dispatcher, or RoadRunner/FrankenPHP adapter.

Requirements

• PHP 8.5+
• pilotphp/contracts ^0.1.2
• pilotphp/runtime ^0.1.2 (Invocation / RequestContext value objects)
• PSR-7 / PSR-17 / PSR-15 interfaces

Install

composer require pilotphp/http

Discovery uses the fixed path pilot/package.json inside the Composer package root. This package does not publish extra.pilotphp.manifest.

Minimal declaration

use PilotPHP\Http\Declaration\HttpRouteDeclaration;

$registration->add(new HttpRouteDeclaration(
    routeId: 'users.show',
    methods: ['GET'],
    path: '/users/{id}',
    operationId: 'users.show',
    requestMapperServiceId: 'app.http.users.show.request',
    responseMapperServiceId: 'app.http.users.show.response',
    errorMapperServiceId: 'app.http.users.show.error',
));

Build flow

package registration
  → HttpRouteDeclaration
  → HttpBuildStage (registered by HttpPackage)
  → http/route-map.json

Runtime flow

validated finalized artifact bytes
  → HttpArtifactLoader
  → HttpRouteMap
  → HttpApplication (PSR-15)
  → KernelInterface::invoke(Invocation)
  → PSR-7 Response

Public API (summary)

Type	Role
HttpPackage	Package entrypoint; registers HttpBuildStage
HttpRouteDeclaration	Build-time route metadata
HttpBuildStage	Compiles declarations into the route-map artifact
HttpArtifactLoader	Validates and loads artifact bytes
HttpRouteMap / HttpRouteMatcher	Immutable matching
HttpApplication	PSR-15 request handler
HttpRequestMapperInterface	Request → Invocation
HttpResponseMapperInterface	Result → Response
HttpErrorMapperInterface	Expected failure → Response

Documentation

• Architecture
• Declarations
• Compilation
• Artifact schema
• Runtime
• Error model
• Integration
• Security

Development

COMPOSER=composer-local.json composer update --prefer-stable
composer check
composer test
composer analyse
composer cs-check

License

MIT