Download the PHP package amsrafid/piper-framework without Composer

Piper

This repository is the framework itself. To build something with it, start from amsrafid/piper by running composer create-project amsrafid/piper my-api. That gives you the directory layout, the config files and the console script, and pulls this in as a dependency. Everything below is what you get once it's there.

A small PHP framework for building APIs. I wrote it in 2022, on my own, to learn what a framework has to do. Routing, a container, middleware, migrations, a token guard and a code generator, each one built rather than read about.

It still runs. In 2026 I went back through it, fixed what was broken and added attribute routing. The commit history has both halves in it.

How it differs from a smaller Laravel: you don't have to declare your routes. A controller method is reachable as soon as you write it, and you declare a route only when you want something the convention can't give you.

Requirements

PHP 8.0, 8.1, 8.2 or 8.3. The composer.json says >=8.0 <8.4 and means it. On 8.4 the deprecations inside illuminate/database 8.x fail, not Piper's own code.

Routing

Three ways to reach a controller method. They work together, and later ones win.

Convention, the default

The URI maps to a controller and a method. App\Http\Controllers\ShopController::index() answers /shop/index, and numeric segments after that become arguments.

Nothing to register. This is what you get by writing a method.

The convention has one limit worth knowing: a segment only becomes an argument if it is numeric. /shop/42 reaches index(42), but /shop/blue-cap looks for a Shop\BlueCapController. That is what attributes are for.

Attributes, when the convention is not enough

#[Get] #[Post] #[Put] #[Patch] #[Delete] #[Options] #[Head] and the generic #[Route] all take an optional path. Leave the path out and the convention still supplies it. All of them are repeatable, so one method can answer more than one path.

Placeholders: {id}, {id?}, {id:\d+}, {id?:\d+}. The ? goes before the :, because {id:\d+?} would be ambiguous. ? is a regex quantifier too.

#[Prefix] on the class prefixes every route in it, including the convention-derived ones. Note that it stacks with the namespace. A controller in App\Http\Controllers\Api that also declares #[Prefix('/api/v2')] ends up under /api/v2/api/..., so put the controller where you want it or set the whole path explicitly.

#[Middleware] works on the class and on the method. It merges with the kernel's global and prefix middleware instead of replacing it.

The constructor, from 2022

Still supported, still works. An attribute on the same method wins.

Middleware

Global and prefix middleware live in the application's app/Http/Kernel.php:

A middleware receives the request and the next handler. Returning a response instead of calling $next stops the request there.

Console

Database

Eloquent, through illuminate/database. Models extend Piper\Database\Model, migrations are plain classes with up() and down(), and the connection is configured in config/database.php and env.xml.

Authentication

A JWT guard with pluggable drivers and providers, configured in config/auth.php. $this->auth() inside a controller gives you the guard.

auth:api refuses a request with a 401 — no token, an expired one, one that will not decode, all the same answer. Override handleResponse() on AuthApiMiddleware to say it differently.

Responses

$this->response($body, $status, $headers) inside a controller or a middleware. An array or an object is encoded as JSON; anything else is sent as it is. The headers you pass are sent, and a Content-Type is always set — application/json for an array or an object, text/html for everything else — unless you passed one of your own.

resolveHeaders() answers what a response will send without sending it.

What it does not do

Worth knowing before you pick it up:

• No view layer. No templates, no compiler, no view() helper. The 2022 README said one was coming in the next version; it never got written, and this is an API framework. A string body does go out as text/html, so serving a page you rendered yourself is one line — it just is not the job this framework is for.
• No route cache yet. The scanner reflects over your controllers on each request that reaches the dispatcher. That is a handful of files and no database work, but on a large application you will want route:cache. It is the next thing on the list.
• No route:list yet. The table exists and is complete. The command that prints it comes with the cache.
• Apache assumed. The framework itself reads nothing Apache-specific, but the starter application routes through a public/.htaccess, so nginx with FPM needs the same rewrite written by hand.
• One application per install. No multi-tenancy, no package discovery, no events.

Tests

The suite is small on purpose. It covers the parts that break quietly:

Each test boots a fixture application under tests/Fixtures/App, so the boot path is the same one a front controller takes. CI runs the suite on 8.0, 8.1, 8.2 and 8.3.

Not covered yet: migrations, an authenticated request that succeeds, and the console commands. Those need a database, which the fixture deliberately does not have. Note what that leaves out and what it does not: a request the guard refuses never reaches the user provider, so AuthTokenTest covers it without a database — and that is exactly where the 401 bug fixed in v1.1.0 had been hiding.

Contributing

Issues and pull requests are welcome. Run composer test before opening one. The framework is expected to boot, serve and run its console on 8.0 through 8.3.

Author

A. M. Sadman Rafid, amsrafid.com · github.com/amsrafid

Security

If you find a security problem, please email [email protected] rather than opening a public issue.

License

MIT.