README

A PHP web framework for quickly spinning up a web site or HTTP service. The same app runs unchanged under the PHP built-in web server, PHP-FPM, FrankenPHP (classic and worker mode), and Workerman — only the entry point differs.

• Routes map to plain PHP files
• Each route file gets exactly one variable, $here, for everything about the request and response
• Output is just echo, classic PHP style
• Requires PHP 8.4+

Install

composer require josephscott/brilkic

A Minimal App

my-app/
├── composer.json
├── url-routes.php
├── routes/
│   ├── home.php
│   └── hello.php
└── public/
    └── index.php

url-routes.php registers routes on the provided $router. Callback file paths are relative to the routes file:

<?php
$router->get( '/', 'routes/home.php' );
$router->get( '/hello/{name}', 'routes/hello.php' );

routes/home.php:

<?php
echo 'Hello from brilkic';

routes/hello.php:

<?php
echo 'Hello ' . $here->param( 'name' );

public/index.php:

<?php
require __DIR__ . '/../vendor/autoload.php';

$server = new Brilkic\Server( __DIR__ . '/../url-routes.php' );
$server->run();

That is the whole app. A complete example using every feature lives in demo/, with make targets that spin it up under each runtime.

Running It

PHP Built-In Web Server

Good for development and trying things out. No configuration:

php -S 127.0.0.1:8080 public/index.php

PHP-FPM

Use the same public/index.php, pointed at by your web server. A minimal nginx example:

server {
    listen 8080;
    root /path/to/my-app/public;

    location / {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_param SCRIPT_FILENAME $document_root/index.php;
        include fastcgi_params;
    }
}

Under PHP-FPM the routes are compiled on every request, so give fastroute a cache file:

$server = new Brilkic\Server( __DIR__ . '/../url-routes.php' );
$server->cache_file( '/tmp/my-app-routes.cache' );
$server->run();

The cache file is not updated automatically when routes change, see The Route Cache File below.

A self-contained PHP-FPM + nginx config to copy from is in demo/config/.

FrankenPHP - Classic Mode

FrankenPHP behaves like a normal SAPI in classic mode, so the same public/index.php works as is:

frankenphp php-server --root public/ --listen 127.0.0.1:8080

FrankenPHP - Worker Mode

In worker mode the app boots once and then handles requests in a loop, skipping per-request startup cost. Create a worker.php in the app root:

<?php
require __DIR__ . '/vendor/autoload.php';

$server = new Brilkic\Server( __DIR__ . '/url-routes.php' );
$server->run_frankenphp_worker();

Then point a Caddyfile at it:

{
    frankenphp {
        worker ./worker.php
    }
}

localhost:8080 {
    root * public/
    php_server
}

frankenphp run

Workerman

Workerman is a pure PHP application server, no web server needed. Create a workerman.php in the app root:

<?php
require __DIR__ . '/vendor/autoload.php';

$server = new Brilkic\Server( __DIR__ . '/url-routes.php' );
$server->listen( 'http://0.0.0.0:8080' );
$server->workers( 4 );
$server->run_workerman();

composer require workerman/workerman
php workerman.php start

listen() sets the address to serve on (default http://0.0.0.0:8080), workers() the number of worker processes (default 1).

The Route Cache File

The optional cache file set with $server->cache_file() is written once, the first time it is missing, and trusted as is from then on — fastroute never checks whether the routes have changed. Adding, changing, or removing a route in url-routes.php has no effect until the cache file is removed, so make deleting it part of every deploy or update:

rm -f /tmp/my-app-routes.cache

The next request rebuilds it from the current routes. Two related notes:

• brilkic re-reads url-routes.php itself on every request, so the custom error page settings (not_found(), not_allowed(), error()) stay current even with a stale cache — it is the route patterns and their callback files that go stale
• The worker runtimes (FrankenPHP worker mode, Workerman) do not use a cache file at all; they compile the routes once at boot, and restarting the workers picks up route changes

Route Files and $here

A route callback file is isolated from the rest of the environment: no globals, no superglobals. The only variable in scope is $here. This is what makes the same file work under every runtime above.

Reading the request:

$here->method();                      // 'GET', 'POST', ...
$here->path();                        // '/hello/world'
$here->param( 'name' );               // route parameter, e.g. {name}
$here->query( 'page', '1' );          // query string argument
$here->post( 'title', '' );           // form / POST body field
$here->header( 'Accept', '' );        // request header, case insensitive
$here->cookie( 'session', '' );       // cookie value
$here->body();                        // raw request body

Every read takes an optional default, returned when the value is missing.

Writing the response:

$here->set_status( 201 );
$here->set_header( 'Content-Type', 'application/json' );
$here->redirect( '/elsewhere' );      // 302 by default

The response body is whatever the file echoes:

<?php
$here->set_header( 'Content-Type', 'application/json' );
echo json_encode( [ 'id' => $here->param( 'id' ) ] );

Routing

Patterns use fastroute syntax:

<?php
$router->get( '/articles', 'routes/articles.php' );
$router->get( '/articles/{id:\d+}', 'routes/article.php' );
$router->post( '/articles', 'routes/article-create.php' );
$router->put( '/articles/{id}', 'routes/article-update.php' );
$router->delete( '/articles/{id}', 'routes/article-delete.php' );
$router->add( 'PURGE', '/cache', 'routes/cache-purge.php' );

get, post, put, patch, delete, head, and options are built in, add() covers anything else. Note that nonstandard methods like PURGE only reach the app under PHP-FPM and FrankenPHP — the PHP built-in server and Workerman both reject them before PHP runs.

Error Pages

brilkic ships minimal built-in responses for 404 (not found), 405 (method not allowed, with a correct Allow header), and 500 (a route file threw). Each can be replaced with your own file in url-routes.php:

<?php
$router->not_found( 'routes/errors/not-found.php' );
$router->not_allowed( 'routes/errors/not-allowed.php' );
$router->error( 'routes/errors/error.php' );

These files receive $here like any other route, with the status already set. An error in a route file never kills a worker process: the partial output is discarded, the error is logged, and the error response is sent.

License

MIT, see LICENSE.