lumi/lumi-php

A tiny PHP framework for learning routing, middleware, and HTTP abstractions.

v0.1.1 2026-05-02 02:39 UTC

Requires

• php: >=8.4

MIT

• Ikhlashmulya

README

Lumi is a tiny PHP framework for learning and experimenting how routing, middleware, and HTTP abstractions work internally.

Installation

Install Lumi with Composer:

composer require lumi/lumi-php

Development

For local development, install dependencies first:

composer install

Run the sample application:

php -S localhost:9000 test/application-test.php

Basic Usage

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Lumi\LumiPHP\Application;
use Lumi\LumiPHP\Context;

$app = new Application();

$app->get('/', function (Context $ctx) {
    $ctx->res->text('Hello World');
});

$app->run();

Routing

Lumi supports common HTTP method helpers:

$app->get('/users', $handler);
$app->post('/users', $handler);
$app->put('/users/{id}', $handler);
$app->patch('/users/{id}', $handler);
$app->delete('/users/{id}', $handler);
$app->options('/users', $handler);
$app->head('/users', $handler);
$app->trace('/users', $handler);

Route parameters can be read from the request object:

$app->get('/users/{id}', function (Context $ctx) {
    $id = $ctx->req->getParam('id');

    $ctx->res->text("User ID: $id");
});

To get all route parameters:

$params = $ctx->req->getParam();

Middleware

Global middleware runs before matched route handlers:

$app->use(function (Context $ctx) {
    $ctx->set('fromMiddleware', 'global');
    $ctx->next();
});

Path-scoped middleware only runs when the request URI matches the prefix:

$app->use('/users', function (Context $ctx) {
    $ctx->set('scope', 'users');
    $ctx->next();
});

$app->get('/users/{id}', function (Context $ctx) {
    $scope = $ctx->get('scope');

    $ctx->res->text("Matched scope: $scope");
});

Context

Handlers receive a Context instance:

$app->get('/hello', function (Context $ctx) {
    $ctx->set('name', 'Lumi');

    $ctx->res->text('Hello ' . $ctx->get('name'));
});

Available context properties:

$ctx->req;
$ctx->res;

Available context methods:

$ctx->next();
$ctx->set('key', 'value');
$ctx->get('key');

Request

Read headers:

$authorization = $ctx->req->header('Authorization');

Read JSON request body:

$data = $ctx->req->json();

Response

Send plain text:

$ctx->res->text('Hello World');

Send JSON:

$ctx->res->json([
    'message' => 'Hello World',
]);

Set a response header:

$ctx->res->header('X-App', 'Lumi');

Views

Set the view directory:

$app->setView(__DIR__ . '/views');

Render a PHP view file:

$ctx->res->view('index', [
    'name' => 'Lumi',
]);

This will load:

views/index.php

View data is available through the $_ variable:

<h1>Hello <?= $_['name'] ?></h1>

TODO

• Route groups with GoFiber-style API:

  $api = $app->group('/api');
  $api->get('/users', $handler);
  
  $admin = $app->group('/admin', $authMiddleware);
  $admin->get('/dashboard', $handler);

• Not found and error handlers:

  $app->notFound($handler);
  $app->onError($handler);

• Built-in middleware:

  • CORS middleware
  • request logger middleware
  • JSON body parser middleware
  • static file middleware

• Testing utility:

  $response = $app->test('GET', '/users/1');

• Simple dependency injection container. (priority: low)