Download the PHP package puff/puff without Composer

Puff

PHP Unison Fiber Framework — a modular, Fiber-native framework for PHP 8.2+.

Puff is a collection of focused Composer packages assembled by puff/puff, the application skeleton and composition root. It provides an event-loop runtime, Fiber-aware dependency injection, PSR HTTP messages, compiled routing, HTTP and WebSocket servers, authentication, database integrations, and application services without Swoole, Amp, Workerman, or Symfony HttpFoundation.

Highlights

• Native PHP Fibers, futures, timers, channels, deferred callbacks, and an event loop.
• Independent process groups for HTTP and WebSocket applications.
• Puff-owned PSR-7 and PSR-17 HTTP messages, streams, uploads, and URI objects.
• Compiled static and dynamic routing with request-local parameters.
• PSR-11 DI container with Fiber-scoped request services and automatic cleanup.
• Composer discovery for providers, configuration, applications, and CLI commands.
• Optional JWT/PASETO authentication, events, sessions, cookies, Redis, views, databases, migrations, jobs, and seeds.

Requirements

• PHP 8.2 or newer.
• Composer 2.
• pcntl and posix for multi-process workers on Unix-like systems.
• fileinfo, mbstring, and simplexml for the default HTTP application.

The process supervisor depends on pcntl_fork() and POSIX signals, so it is not natively supported on Windows.

Install and Run

The workspace uses Composer path repositories; installed packages are symlinked under vendor/puff, so local component changes are immediately visible.

Set a secure JWT signing key before using the token endpoint:

For automatic development restart:

Docker

The Docker image installs local Puff components through Composer path repositories. Build it from the workspace root, not from the puff/ application directory:

Architecture

Each request has its own Fiber scope. The HTTP dispatcher clears that scope after producing a response, preventing request-scoped services from leaking into another request.

Fiber concurrency is cooperative: only event-loop-aware work yields without blocking a worker. Use Puff asynchronous clients for concurrent network I/O; ordinary blocking I/O still blocks its worker.

Packages

Foundation

Networking and HTTP

Application services

Packages are optional unless included by the skeleton's composer.json. A package may publish configuration and register providers or commands through Composer metadata.

Configuration

Shared runtime settings are in config/config.php:

config/server.php is a flat list of server instances. Each entry has a type, addr, route files, and type-specific options:

The root .env file overlays existing configuration keys. Double underscores represent nested keys, for example JWT__SECRET, LOGGER__LEVEL, or DATABASE__DEFAULT.

HTTP, Routing, and Authentication

Routes use a compact DSL. Dynamic route parameters use (name:type) syntax:

Built-in types include str, int, num, uuid, hex, hash, any, and *. Static routes use indexed lookup; dynamic patterns are compiled during boot and matches are request-local.

Controllers may return Puff\Http\Response, strings, arrays, or objects. Arrays and objects are serialized as JSON by the dispatcher:

Puff HTTP messages are immutable: withHeader() and all with*() methods return a new instance.

Skeleton endpoints

Get a token and call a protected endpoint:

Puff\Jwt\Pipeline verifies the token and stores claims in the jwt request attribute. Pipeline\Auth can require claims that were produced by JWT or PASETO middleware.

Pipelines, Pagination, and Async

Global pipelines are configured per HTTP server. Route groups can add their own stages:

Pipeline\Api normalizes output and adds CORS headers. Pipeline\Page paginates an unexecuted Puff query or Cycle-style select, using page and size; it returns data and meta.page, meta.size, meta.total, and meta.last.

Other helpers include puff_defer(), puff_channel(), puff_wait_group(), and puff_id(). Runnable examples are available under /api/async/*.

Domain Events

puff/event is synchronous and in-process. Use it to decouple one completed business action from independent side effects; it is not a queue, broker, retry mechanism, or cross-process transport.

The skeleton dispatches App\Event\TokenIssued after a JWT is signed. Its listener logs only the token subject, never the access token.

Listeners are resolved through DI in registration order. Exceptions stop dispatch and propagate to the caller. Use puff/job from a listener when a side effect needs asynchronous or scheduled execution.

Generate a generic event class with a readonly data payload:

Database, Migrations, and WebSocket

puff/database supplies Fiber-scoped PDO connections and a parameterized query API. Optional ORM adapters register when their packages are installed:

Puff does not force a shared model base class. The skeleton maps Database\Model and Database\Entity directly to database/Model and database/Entity.

Migrations are independent of the selected ORM:

WebSocket servers use the same config/server.php list:

The bundled WebSocket routes demonstrate event-based messages such as message.echo, as well as path and lifecycle handling.

CLI

Run ./puff to list commands installed by the current Composer dependency set. Commands are contributed by their owning components, so a component that is not installed does not expose a command.

Quality and benchmark commands:

Project Structure

Security Notes

• Configure a unique JWT__SECRET; never commit production secrets.
• Trusted proxy handling is disabled unless CIDRs are explicitly configured.
• HTTP messages validate headers, Host values, forwarded chains, uploads, and methods.
• Request-scoped services are cleared after dispatch.
• Do not log JWTs, PASETOs, passwords, or other credentials.
• Use a trusted TLS reverse proxy until native TLS is configured for the server layer.
• Avoid blocking I/O inside request Fibers.

Stability and License

Components currently use dev-main constraints with minimum-stability: dev and prefer-stable: true; public APIs may change before stable releases.

Puff is released under the MIT License.