README

Just Enough PHP for a bit of a framework.

A minimal PHP routing framework built on FastRoute. Define routes, match HTTP methods, and handle requests with closures, files, or classes.

Requirements

PHP >= 8.3
nikic/fast-route 1.3.0

Installation

composer require jeph/frame

Basic Usage

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

$frame = new JEPH\Frame();

$frame->get( '/', function() {
    echo 'Hello World!';
} );

$frame->run();

HTTP Methods

Supports GET, POST, PUT, DELETE, PATCH, OPTIONS, and HEAD:

$frame->get( '/resource', $handler );
$frame->post( '/resource', $handler );
$frame->put( '/resource', $handler );
$frame->delete( '/resource', $handler );
$frame->patch( '/resource', $handler );
$frame->options( '/resource', $handler );
$frame->head( '/resource', $handler );

Use any() to match all methods:

$frame->any( '/api', function() {
    echo 'Handles any HTTP method';
} );

Route Parameters

Named parameters with regex patterns:

$frame->get( '/user/{id:\d+}', function( $vars ) {
    echo "User ID: {$vars['id']}";
} );

$frame->get( '/hello/{name:\w+}', function( $vars ) {
    echo "Hello {$vars['name']}!";
} );

Optional parameters:

$frame->get( '/page[/{slug:\w+}]', function( $vars ) {
    $slug = $vars['slug'] ?? 'home';
    echo "Page: $slug";
} );

Handler Types

Closures

$frame->get( '/hello', function( $vars ) {
    echo 'Hello!';
} );

File Includes

$frame->get( '/dashboard', __DIR__ . '/routes/dashboard.php' );

In the included file, route parameters are available via the $_frame array:

<?php
$id = $_frame['id'] ?? null;
echo "ID: $id";

Class Handlers

class ApiResource {
    public function get( $vars ) {
        echo "GET request";
    }
    public function post( $vars ) {
        echo "POST request";
    }
}

$frame->get( '/api/resource', [ 'ApiResource' ] );
$frame->post( '/api/resource', [ 'ApiResource' ] );

The class method matching the HTTP method is called automatically.

Route Caching

By default, routes are compiled on every request, which is ideal for development since changes take effect immediately.

For production, enable route caching to avoid recompiling routes on each request:

$frame = new JEPH\Frame();
$frame->set_cache_file( '/tmp/routes.cache' );

$frame->get( '/', function() {
    echo 'Hello World!';
} );

$frame->run();

A common pattern is to enable caching based on environment:

$frame = new JEPH\Frame();

if ( getenv( 'APP_ENV' ) === 'production' ) {
    $frame->set_cache_file( '/tmp/routes.cache' );
}

$frame->get( '/', function() {
    echo 'Hello World!';
} );

$frame->run();

When routes change in production, delete the cache file to regenerate it on the next request.

Custom Error Handlers

By default, unmatched routes return a plain text "404 Not Found" or "405 Method Not Allowed" response. You can customize these with your own handlers.

Error handlers support the same handler types as routes: closures, file includes, and classes.

404 Not Found Handler

$frame->set_not_found_handler( function( $vars ) {
    echo "Page not found: {$vars['uri']}";
} );

The handler receives:

$vars['uri'] - The requested URI that was not found

405 Method Not Allowed Handler

$frame->set_method_not_allowed_handler( function( $vars ) {
    $allowed = implode( ', ', $vars['allowed'] );
    echo "Method not allowed. Try: $allowed";
} );