README

liquidrazor/http-contracts defines the HTTP transport vocabulary for the LiquidRazor Framework.

It provides HTTP request and response contracts, immutable scaffold implementations, concrete HTTP implementations of liquidrazor/transport-contracts, request-body parameter bag scaffolding, optional DTO gateway contracts/defaults, immutable HTTP exchange state, and HTTP lifecycle event contracts/value objects.

It does not implement an HTTP kernel or runtime.

Table of Contents

• Purpose
• Architectural Position
• Implemented Surface
• Not Implemented
• Request and Response
• Request Body
• Transport Integration
• DTO Gateway
• HTTP Exchange
• Lifecycle Events
• Directory Layout
• Focused Docs
• License

Purpose

This package describes HTTP-shaped input and output for LiquidRazor. It provides stable HTTP contracts and small immutable defaults without taking ownership of request execution.

Architectural Position

This package sits on top of liquidrazor/transport-contracts and supplies the HTTP-specific payload model used by future HTTP runtime layers.

Current mapping:

HttpRequestInterface
  -> HttpTransportInput
  -> TransportInputInterface

HttpResponseInterface
  -> HttpTransportOutput
  -> TransportOutputInterface

Implemented Surface

Implemented here:

• HttpRequestInterface and immutable HttpRequest
• HttpResponseInterface and immutable HttpResponse
• RequestBodyInterface, RequestBodyType, and immutable RequestBody
• request-side URI, header, and uploaded-file scaffolds
• response-side header and cookie scaffolds
• HttpTransportInput, HttpTransportOutput, and HttpTransportContext
• HttpExchangeInterface and immutable HttpExchange
• HttpRequestDtoResolverInterface and HttpResponseDtoResolverInterface
• NullHttpRequestDtoResolver and NullHttpResponseDtoResolver
• HTTP lifecycle event interfaces and immutable lifecycle event classes

Not Implemented

This package intentionally does not provide:

• an HTTP kernel
• routing
• controller resolution or invocation
• middleware runtime
• request capture from globals
• response emission
• SAPI adapters
• PSR bridges
• Symfony bridges
• RoadRunner bridges
• FrankenPHP bridges
• dependency injection wiring
• MicroKernel execution integration

Request and Response

The request contract models an already-normalized HTTP request. The response contract models a response description ready for a later runtime or emitter layer.

Minimal example:

<?php

declare(strict_types=1);

use LiquidRazor\HttpContracts\Include\Enum\RequestBodyType;
use LiquidRazor\HttpContracts\Lib\Request\HeaderBag;
use LiquidRazor\HttpContracts\Lib\Request\HttpRequest;
use LiquidRazor\HttpContracts\Lib\Request\RequestBody;
use LiquidRazor\HttpContracts\Lib\Request\Uri;
use LiquidRazor\HttpContracts\Lib\Response\HttpResponse;

$request = new HttpRequest(
    method: 'POST',
    uri: new Uri(
        scheme: 'https',
        host: 'example.com',
        path: '/contracts',
        query: 'page=1',
    ),
    path: '/contracts',
    headers: new HeaderBag(['Content-Type' => 'application/json']),
    body: '{"name":"LiquidRazor"}',
    requestBody: new RequestBody(
        type: RequestBodyType::JSON_ASSOCIATIVE,
        raw: '{"name":"LiquidRazor"}',
        parameters: ['name' => 'LiquidRazor'],
    ),
    protocolVersion: '1.1',
);

$response = new HttpResponse(
    statusCode: 201,
    reasonPhrase: 'Created',
    body: '{"ok":true}',
    protocolVersion: '1.1',
);

Request Body

Structured request body access is explicit:

requestBody(): RequestBodyInterface

This package does not expose parsed body as mixed, and it does not put an anonymous parsed-body array directly on the request contract.

RequestBodyInterface separates raw body from structured body:

• body() on HttpRequestInterface exposes the raw string body or null
• requestBody() exposes structured request-body state

Implemented body types:

EMPTY
RAW_STRING
FORM_FIELDS
JSON_ASSOCIATIVE
JSON_OBJECT
MULTIPART
UNKNOWN

Minimal example:

<?php

declare(strict_types=1);

use LiquidRazor\HttpContracts\Include\Enum\RequestBodyType;
use LiquidRazor\HttpContracts\Lib\Request\RequestBody;

$body = new RequestBody(
    type: RequestBodyType::FORM_FIELDS,
    raw: 'name=LiquidRazor',
    parameters: ['name' => 'LiquidRazor'],
);

$body->type();       // RequestBodyType::FORM_FIELDS
$body->raw();        // 'name=LiquidRazor'
$body->has('name');  // true
$body->get('name');  // 'LiquidRazor'
$body->all();        // ['name' => 'LiquidRazor']

Transport Integration

HttpTransportInput, HttpTransportOutput, and HttpTransportContext implement the upstream contracts from liquidrazor/transport-contracts.

Transport name:

http

HttpTransportInput always carries an HttpRequestInterface payload.

HttpTransportOutput always carries an HttpResponseInterface payload.

Generic TransportStatus belongs to the transport output wrapper. HTTP response status code belongs to the HTTP response object itself.

Minimal example:

<?php

declare(strict_types=1);

use LiquidRazor\HttpContracts\Lib\Request\HttpRequest;
use LiquidRazor\HttpContracts\Lib\Response\HttpResponse;
use LiquidRazor\HttpContracts\Lib\Transport\HttpTransportInput;
use LiquidRazor\HttpContracts\Lib\Transport\HttpTransportOutput;
use LiquidRazor\TransportContracts\Enum\TransportStatus;

$input = new HttpTransportInput(new HttpRequest(), operationName: 'contracts.index');
$output = new HttpTransportOutput(new HttpResponse(), TransportStatus::Success);

$input->transportName();   // 'http'
$output->transportName();  // 'http'
$output->status();         // TransportStatus::Success

DTO Gateway

DTO support is optional.

This package provides:

• HttpRequestDtoResolverInterface
• HttpResponseDtoResolverInterface
• NullHttpRequestDtoResolver
• NullHttpResponseDtoResolver

DTOs are not mandatory, and this package does not require DTO marker interfaces.

Default behavior:

• NullHttpRequestDtoResolver returns the original HttpRequestInterface
• NullHttpResponseDtoResolver returns an existing HttpResponseInterface unchanged
• NullHttpResponseDtoResolver returns null for non-response input

This package does not perform:

• serialization
• validation
• route-aware DTO mapping
• controller dispatch

HTTP Exchange

HttpExchange is an immutable lifecycle carrier for:

• request
• optional response
• transport context
• optional request DTO
• optional response DTO

Progression is represented through immutable with*() methods.

Minimal example:

<?php

declare(strict_types=1);

use LiquidRazor\HttpContracts\Lib\Request\HttpRequest;
use LiquidRazor\HttpContracts\Lib\Response\HttpResponse;
use LiquidRazor\HttpContracts\Lib\Transport\HttpExchange;

$exchange = new HttpExchange(new HttpRequest());
$response = new HttpResponse(statusCode: 200, reasonPhrase: 'OK');

$next = $exchange->withResponse($response);

Lifecycle Events

This package provides lifecycle event value objects only.

Implemented event catalog:

HttpRequestReceivedEvent
HttpRequestPreparedEvent
HttpRequestDtoResolvedEvent
HttpResponseDtoResolvedEvent
HttpResponsePreparedEvent
HttpResponseFinalizedEvent

Each event carries HttpExchangeInterface.

This package does not provide:

• an event dispatcher
• a listener registry
• event discovery
• event priority rules

Directory Layout

Production code exists only in:

include/
lib/

There is no src/ directory by design.

Focused Docs

• Request and Response
• Request Body
• Transport Integration
• DTO Gateway
• HTTP Exchange
• Lifecycle Events

License

MIT License.