README

Typed HTTP routing and application structure for the PAM runtime.
Routing, middleware, dependency injection, validation, resources, streaming, OpenAPI and production lifecycle controls, running in persistent PHP workers.

Install · Quick example · Features · Docs · Issues

Install

Start a new API with the HTTP template, which already requires pushinbr/pam-http:

pam init my-api --template http
cd my-api
pam dev

In an existing PAM project, add the router with pam composer require pushinbr/pam-http; PAM runs Composer inside its private Embed SAPI. Run pam doctor after dependency changes and before creating a release. The project remains a normal Composer project with a standard manifest, lockfile, PSR-4 autoloading, and vendor/autoload.php.

Quick example

<?php

declare(strict_types=1);

use Pam\Api\RouteConstraint;
use Pam\App;
use Pam\Http\Request;
use Pam\Http\Response;

$app = new App;

$app->get('/api/ping', static fn (Request $request, Response $response): Response => $response->json([
    'message' => 'pong',
]));

$app->get('/users/{id}', [UserController::class, 'show'])
    ->where('id', RouteConstraint::Integer)
    ->name('users.show');

$app->listen((int) (getenv('PAM_PORT') ?: 3000));

Route parameters are available through $request->route(). A path that exists for another method produces 405 behavior; an unknown path produces 404 behavior. Register error handling with onError() and keep transport-level timeouts and request limits in the PAM listener options.

What you can build

Typed JSON APIs and backend services
Streaming and event-driven HTTP endpoints
Structured applications with controllers, services, repositories, and resources


Role	HTTP framework
Execution path	Persistent PHP · PAM transport
This repository owns	HTTP routing and application structure
Boundary	PAM owns the runtime; databases and framework integrations stay optional

Features

Area	What you get	Guide
Routing	Route groups, prefixes, `apiResource`, constraints, automatic `HEAD` and `OPTIONS`, bounded router limits	Route groups
Container	`bind`, `singleton` and request-`scoped` lifetimes, discarded even when the handler throws	Container lifetimes
Configuration	Typed environment definitions that fail at boot, redacted diagnostics	Typed configuration
Validation	`FormRequest` rules, `JsonResource` envelopes, Problem Details with stable integer codes	Validation and resources
Security	Rate limiting with pluggable stores, HS256 bearer tokens with key rotation and revocation	Rate limiting, tokens
Production	Idempotency, response cache, tenancy, transactions, jobs with leases and dead letters, retries, circuit breakers	Building blocks
Observability	Request lifecycle observers and the bounded `MemoryProfiler`	Observers
Contracts	OpenAPI output and generated TypeScript, Kotlin and Swift clients	OpenAPI
Database (optional)	Legacy Eloquent bridge with per-Fiber connections, query budgets, tenant guard	Eloquent ORM
Testing	In-memory `TestClient` from `pushinbr/pam-http-testing`	In-memory testing

Performance contract: compiled hot paths and enforced throughput, tail-latency, startup, and memory budgets.

API guide

Surface	Use it for
`App`	Register routes, middleware, providers, error boundaries, and the listener.
`Router`	Compile and match method/path routes with typed results.
`Pipeline`	Execute middleware and the destination handler in order.
`CorsMiddleware`	Apply explicit origin, method, and header policy.
`RateLimitMiddleware`	Apply bounded per-key request limits.
`SecurityHeadersMiddleware`	Set conservative browser security headers.

The public API reference is generated from the reviewed api-surface.json baseline.

Production checklist

Keep request data and mutable state scoped to the current request.
Test success, validation failure, exception, cancellation, and timeout paths.
Configure explicit limits and avoid unbounded payloads, queues, or retained collections.
Run pam doctor, pam test, and the relevant integration suite before release.
Validate real dependencies and workload behavior; compatibility is not inferred from package installation alone.

Build hygiene: every local, CI, benchmark, and release build must remove project-scoped regenerable outputs after success or failure. Source, Composer dependencies, and declared evidence are retained. Native consumers inherit PAM's Gradle/Xcode/Rust cleanup contract; this package never deletes another package's artifacts or requires PAM Native.

Troubleshooting notes are in the guide. See CONTRIBUTING.md to contribute (the composer verify quality gate). Report security vulnerabilities through GitHub private vulnerability reporting or the PAM security policy, not a public issue.

Docs

Official documentation
Guide: database, routing, container, configuration, validation, security, jobs, observers, OpenAPI, testing
Architecture
Performance contract
Public API reference
PAM API 2 design and delivery contract
Upgrade guide
Changelog
Package ecosystem
Runtime compatibility

Part of the PAM ecosystem

PAM

PAM runs PHP natively on servers, desktops and phones. This repository is one piece of it.

PAM	PAM Desktop	PAM Native	Ecosystem
the runtime and CLI	native desktop apps in PHP	native Android and iOS apps in PHP	every official package and plugin

_{Docs: push-in.github.io/pam-docs · Issues}

_{Apache License 2.0: use, modify and distribute for any purpose, including commercially · Made in Brazil by Pushin}

pushinbr / pam-http

Package info

Security

Statistics