README

Depend on the extension boundary, not an entire framework.
Small, versioned interfaces for applications, middleware, providers, stability and runtime compatibility.

Install · Quick example · API · Docs · Issues

Install

Most applications receive this package transitively. Extension authors install it explicitly inside a PAM project:

pam composer require pushinbr/pam-contracts
pam doctor

New to PAM? Start with pam init my-app --template http and pam dev. Run pam doctor after dependency changes and before a release. The project stays a normal Composer project: standard manifest, lockfile, PSR-4 autoloading and vendor/autoload.php.

Quick example

<?php

declare(strict_types=1);

use Pam\Contracts\Http\ApplicationInterface;
use Pam\Contracts\Http\MiddlewareInterface;
use Pam\Contracts\Http\RequestHandlerInterface;
use Pam\Contracts\Package\ServiceProviderInterface;
use Pam\Contracts\Runtime\RuntimeCompatibility;
use Pam\Http\Request;
use Pam\Http\Response;

final class AuditMiddleware implements MiddlewareInterface
{
    public function process(Request $request, Response $response, RequestHandlerInterface $next): Response
    {
        // Inspect the request, then delegate to the next handler.
        return $next->handle($request, $response);
    }
}

final class AuditServiceProvider implements ServiceProviderInterface
{
    public function register(ApplicationInterface $application): void
    {
        $application->middleware(new AuditMiddleware());
    }

    public function boot(ApplicationInterface $application): void
    {
        // Fails fast when the package runs on an incompatible PAM runtime ABI.
        RuntimeCompatibility::discover()->assert();
    }
}

RuntimeCompatibility::discover() reads the ABI version and capabilities from the PAM runtime (Pam\Native\Api) and throws outside it. Pass a list of Pam\Native\Capability cases to assert() to require specific runtime features.

Why this exists

Small, versioned contracts for packages that extend PAM. It contains the HTTP application and middleware contracts, service providers, stability values and native runtime compatibility checks. It does not contain a router or server.

What you can build:

• Publishing framework-independent PAM extensions
• Testing runtime compatibility explicitly
• Sharing middleware and provider contracts without pulling a router

API guide

All classes live under Pam\Contracts\. This package intentionally contains no router, server, or application implementation. Depend on it when publishing reusable PAM extensions that need stable contracts without forcing PAM HTTP on consumers.

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.

Troubleshooting

• Class not found: run pam composer install, verify PSR-4 configuration, and rerun pam doctor.
• Behavior differs over the network: reproduce with PAM's transport integration tests; in-memory execution does not model the socket boundary.
• A dependency blocks a worker: use PAM-native I/O, a compatible event loop, a process pool, or additional isolated workers.

Docs

• PAM introduction
• Package ecosystem
• Runtime compatibility
• Report an issue: report security vulnerabilities through GitHub private vulnerability reporting or the PAM security policy, not a public issue

Part of the PAM ecosystem

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

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

_{Apache License 2.0 · free and open source, including commercial use · Made in Brazil by Pushin}