README

Designed for decades, not release cycles.

LLMs and senior developers: read MINI-STYLE.md before working on Mini projects.

composer require fubber/mini
mkdir _routes
echo '<?php return date("c");' > _routes/time.php
composer exec mini serve

Visit http://localhost/time - you're running.

Philosophy

Mini is built on a Lindy perspective: if a pattern has worked for 40 years, it will likely work for 40 more. We reject patterns that trigger frequent redesign.

Use PHP's engine, not userland abstractions. Traditional frameworks reinvent locale handling, date formatting, routing, and templating in PHP code. Mini uses PHP's C-level engine: intl extension for ICU, file system for routing, PHP files for templates.

Dependency locator, not dependency injection. DI in PHP forces proxy classes, scattered configuration, and compilation steps. We locate dependencies via db(), cache(), auth() - simple functions resolving from Mini::$mini. Same testability (swap the container service), no proxy explosion.

Embrace PHP's short-lived request cycle. PHP bootstraps fresh for each request - no memory leaks, no stale state, predictable cleanup. We optimize for this reality instead of fighting it.

Multiple routing paradigms. _routes/ files can echo output like classic PHP, return values (converted to PSR-7 via converter registry), return controllers with attribute-based routing, or return PSR-15 handlers (mount Slim, Mezzio, etc.). We don't reject patterns that have been idiomatic PHP for 20+ years.

Fiber-safe globals. $_GET, $_POST, $_COOKIE, $_SESSION are ArrayAccess proxies routing to the current PSR-7 request context - works in FPM, Swoole, ReactPHP, and Fiber-based async.

Full-stack, lazy-loaded. ORM, auth, i18n, templates, validation - all included, nothing loads until touched. Hello World uses ~300KB. Zero required dependencies enables mounting PSR-15 apps without dependency conflicts.

Engine-Native, Not Userland-Native

We use PHP's C-level engine, not userland reimplementations. Modern frameworks reimplement locale handling, date formatting, and number formatting in PHP code. Mini uses PHP's intl extension (ICU library in C) and native functions.

Engine-Level Performance

Internationalization:

// Mini: Use PHP's intl extension (C-level ICU)
\Locale::setDefault('de_DE');           // Sets locale for entire engine
echo fmt()->currency(19.99, 'EUR');     // "19,99 €" - formatted by ICU in C
echo t("Hello, {name}!", ['name' => 'World']);  // MessageFormatter in C

// Framework approach: Load massive translation arrays, parse ICU in PHP
$translator->trans('messages.welcome', ['name' => 'World'], 'en_US');

Routing:

// Mini: File system IS the routing table (OS-cached, instant lookup)
_routes/users/_.php  // Wildcard matches any ID, captured in $_GET[0]

// Framework approach: Parse regex routes on every request (slow)
$router->addRoute('GET', '/users/{id}', [UserController::class, 'show']);

Templates:

// Mini: PHP IS the template language (no parsing overhead)
<?= h($user->name) ?>  // Direct output buffering, closure-based inheritance

// Framework approach: Parse string templates into PHP (Blade, Twig)
{{ $user->name }}

What We Use (And Why)

Request/Response:

$_GET, $_POST, $_COOKIE, $_SESSION - Request-scoped proxies (fiber-safe for future async)
header(), http_response_code(), echo - Direct output control in SAPI environments
\Locale::setDefault(), date_default_timezone_set() - Engine-level configuration

Helpers when they genuinely simplify:

$users = db()->query("SELECT * FROM users WHERE active = ?", [1])->fetchAll();
echo render('user/profile', ['user' => $user]);
echo t("Hello, {name}!", ['name' => 'World']);
session();  // Starts session if needed

Lazy-Loading Architecture

All features exist, but nothing loads until touched:

mail();        // Loads symfony/mailer only if installed
table(User::class);  // Loads ORM only when used
auth()->check();     // Loads authentication system on demand

This "soft dependency" pattern means:

A "Hello World" app uses ~300KB of memory
Full-stack enterprise app uses what it needs
No bootstrap penalty for unused features

Configuration over code. Override framework services via config files, not subclassing:

Create _config/Psr/Log/LoggerInterface.php to return your logger
Create _config/PDO.php to return your database connection
Framework loads these automatically - no service registration needed

Two Paradigms: Choose What Fits

Mini supports both PSR-7 standard patterns and native PHP patterns. You can mix them in the same application.

PSR-7 Pattern (Standards-Based)

Use PSR-7 ServerRequestInterface and ResponseInterface for framework-agnostic code:

// _routes/api/users.php
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\ResponseInterface;

return function(ServerRequestInterface $request): ResponseInterface {
    $id = $request->getQueryParams()['id'] ?? null;

    $response = response();
    $response->getBody()->write(json_encode(['user' => $id]));
    return $response->withHeader('Content-Type', 'application/json');
};

When to use: Libraries, packages, sub-applications (Slim, Symfony), testability, framework portability.

Native PHP Pattern (Direct)

Use PHP's native request/response mechanisms directly:

// _routes/api/users.php
$id = $_GET['id'] ?? null;

header('Content-Type: application/json');
echo json_encode(['user' => $id]);

When to use: Simple applications, SAPI environments (FPM, mod_php, RoadRunner), rapid prototyping.

How They Coexist

Mini provides request-scoped proxies for $_GET, $_POST, $_COOKIE, $_SESSION that interact with the PSR-7 ServerRequest:

In SAPI environments (FPM, CGI, mod_php): Proxies read from PHP's native superglobals
In non-SAPI environments (Swoole, ReactPHP, phasync with Fibers): Proxies read from the PSR-7 request object
Controllers can return PSR-7 responses OR echo output - Mini handles both
Use header() in SAPI or mini\header() in non-SAPI environments

This design enables:

Sub-application mounting: Mount PSR-15 compliant frameworks (Slim, Mezzio, etc.) without dependency conflicts (see "Mounting Sub-Applications")
Gradual complexity: Start with echo and $_GET, grow into PSR-7 and controllers as needs evolve
Future async support: Native PHP patterns will work in Fiber-based async environments (Swoole, ReactPHP)

Installation

composer require fubber/mini

Quick Start

Create the entry point:

// html/index.php
<?php
require '../vendor/autoload.php';
mini\router();

Create your first route:

// _routes/index.php
<?php
echo "<h1>Hello, World!</h1>";

Start the development server:

vendor/bin/mini serve

Visit http://localhost - you're running!

Routing: File System as Routing Table

Mini uses the file system as its routing table. No regex parsing, no route compilation, no routing cache - just OS-level file lookups (microseconds, cached by the kernel).

File-Based Routing

Routes map directly to PHP files in _routes/:

_routes/index.php        → /
_routes/users.php        → /users
_routes/api/posts.php    → /api/posts

Wildcard Routing with `_`

Use _ as a filename or directory name to match any single path segment:

// _routes/users/_.php - Matches /users/123, /users/john, /users/anything
$userId = $_GET[0];  // Captured value: "123", "john", "anything"
$user = db()->queryOne("SELECT * FROM users WHERE id = ?", [$userId]);
echo json_encode($user);

// _routes/users/_/posts/_.php - Matches /users/{userId}/posts/{postId}
$postId = $_GET[0];   // Rightmost wildcard (nearest to file)
$userId = $_GET[1];   // Next wildcard to the left
$post = db()->queryOne("SELECT * FROM posts WHERE id = ? AND user_id = ?", [$postId, $userId]);
echo json_encode($post);

Wildcard behavior:

_.php matches any single segment (e.g., /users/123)
_/index.php matches any single segment with trailing slash (e.g., /users/123/)
Exact matches take precedence over wildcards
Captured values stored in $_GET[0], $_GET[1], etc. (right to left - nearest wildcard is [0])
Wildcards match single segments only (won't match across /)

Examples:

URL: /users/123           → _routes/users/_.php          ($_GET[0] = "123")
URL: /users/123/          → _routes/users/_/index.php    ($_GET[0] = "123")
URL: /users/john/posts/5  → _routes/users/_/posts/_.php  ($_GET[0] = "5", $_GET[1] = "john")

Why right-to-left? If you move _routes/users/_/posts/_.php to _routes/_/posts/_.php, the code using $_GET[0] for post ID still works - only $_GET[1] changes.

Trailing Slash Redirects

The router automatically redirects to ensure consistency:

If only _.php exists: /users/123/ → 301 redirect to /users/123
If only _/index.php exists: /users/123 → 301 redirect to /users/123/
If both exist: Each URL serves its respective file (no redirect)

What route files can return:

Nothing (echo output directly)
PSR-7 ResponseInterface
Callable that returns PSR-7 response
Controller instance with attributes
PSR-15 RequestHandlerInterface

// _routes/users.php - Direct output (native PHP)
header('Content-Type: application/json');
echo json_encode(['users' => db()->query("SELECT * FROM users")->fetchAll()]);

// _routes/users.php - PSR-7 response
return response()->json(['users' => db()->query("SELECT * FROM users")->fetchAll()]);

Controller-Based Routing

File-based routing doesn't mean "no OOP." Use __DEFAULT__.php to mount controllers with attribute-based routing:

// _routes/users/__DEFAULT__.php - Handles /users/*
use mini\Controller\AbstractController;
use mini\Controller\Attributes\{GET, POST, PUT, DELETE};

return new class extends AbstractController {
    #[GET('/')]
    public function index(): array
    {
        return db()->query("SELECT * FROM users")->fetchAll();
    }

    #[GET('/{id}/')]
    public function show(int $id): array
    {
        $user = db()->query("SELECT * FROM users WHERE id = ?", [$id])->fetch();
        if (!$user) throw new \mini\Exceptions\NotFoundException();
        return $user;
    }

    #[POST('/')]
    public function create(): array
    {
        db()->exec(
            "INSERT INTO users (name, email) VALUES (?, ?)",
            [$_POST['name'], $_POST['email']]
        );
        return ['id' => db()->lastInsertId(), 'message' => 'Created'];
    }

    #[PUT('/{id}/')]
    public function update(int $id): array
    {
        db()->exec(
            "UPDATE users SET name = ?, email = ? WHERE id = ?",
            [$_POST['name'], $_POST['email'], $id]
        );
        return ['message' => 'Updated'];
    }

    #[DELETE('/{id}/')]
    public function delete(int $id): ResponseInterface
    {
        db()->exec("DELETE FROM users WHERE id = ?", [$id]);
        return $this->empty(204);
    }
};

Key benefits:

Scoped routing: /users/123/ becomes /{id}/ inside the controller
Type-aware parameters: int $id automatically extracts and casts URL parameter
Converter integration: Return arrays, strings, or domain objects - auto-converted to JSON/text
Attribute-based: Routes declared with method attributes (no manual registration)

URL mapping:

GET /users/ → index() → returns array → JSON response
GET /users/123/ → show(int $id) → $id = 123 (typed!)
POST /users/ → create() → uses $_POST directly
DELETE /users/123/ → delete(int $id) → returns 204 No Content

When to use controllers:

Multiple related endpoints (CRUD operations)
Type-safe URL parameters
Return value conversion (arrays → JSON)
Clean, declarative routing

Exception Handling

Mini uses transport-agnostic exceptions that are mapped to appropriate responses by the dispatcher:

// Throw domain exceptions - dispatcher handles HTTP mapping
throw new \mini\Exceptions\NotFoundException('User not found');        // → 404
throw new \mini\Exceptions\AccessDeniedException('Login required');           // → 401/403
throw new \mini\Exceptions\BadRequestException('Invalid email format');       // → 400

Debug mode shows detailed error pages with stack traces. In production, clean error pages are shown.

Custom error pages: Create _errors/404.php, _errors/500.php, etc. to override default error pages. The exception is available as $exception.

For complete coverage of routing, error handling, converters, and web app patterns, see docs/web-apps.md.

Dynamic Routes with `DEFAULT.php`

Handle dynamic segments with pattern matching:

// _routes/blog/__DEFAULT__.php
return [
    '/' => 'index.php',                              // /blog/
    '/{slug}' => fn($slug) => "post.php?slug=$slug", // /blog/my-post
    '/{year}/{month}' => 'archive.php',              // /blog/2025/11
];

Mounting Sub-Applications

Mini's zero-dependency design enables mounting entire frameworks as sub-applications without dependency conflicts. Each sub-app can have its own vendor/ directory with different dependency versions.

Example: Mount a Slim 4 Application

// _routes/api/__DEFAULT__.php
require_once __DIR__ . '/api-app/vendor/autoload.php';  // Slim's autoloader

use Slim\Factory\AppFactory;

$app = AppFactory::create();

// Define Slim routes
$app->get('/users', function ($request, $response) {
    $response->getBody()->write(json_encode(['users' => []]));
    return $response->withHeader('Content-Type', 'application/json');
});

$app->post('/users', function ($request, $response) {
    $data = $request->getParsedBody();
    // ... handle user creation
    return $response->withStatus(201);
});

// Return the Slim app (implements RequestHandlerInterface)
return $app;

Project structure with mounted apps:

project/
├── _routes/
│   ├── index.php              # Mini native route
│   ├── api/
│   │   ├── __DEFAULT__.php    # Mounts Slim app
│   │   └── api-app/           # Complete Slim application
│   │       ├── composer.json  # Slim's dependencies (guzzle 7.x)
│   │       └── vendor/        # Slim's vendor directory
│   └── admin/
│       ├── __DEFAULT__.php    # Mounts Symfony app
│       └── admin-app/         # Complete Symfony application
│           ├── composer.json  # Symfony's dependencies (guzzle 6.x)
│           └── vendor/        # Symfony's vendor directory
├── composer.json              # Mini (no dependencies!)
└── vendor/                    # Mini's vendor directory

How It Works

Mini has zero required dependencies - only PSR interfaces (dev/suggest)
Sub-apps are isolated - each has its own vendor/autoload.php
PSR-7 bridges everything - Mini provides ServerRequestInterface, sub-apps return ResponseInterface
No conflicts - Slim can use guzzlehttp/psr7:7.x, Symfony can use 6.x, no collision

Supported Sub-Applications

Any framework/application that:

Implements Psr\Http\Server\RequestHandlerInterface (PSR-15), OR
Is a callable accepting ServerRequestInterface and returning ResponseInterface (PSR-7)

Examples:

Slim 4 - Native PSR-15 support
Mezzio (formerly Zend Expressive) - Native PSR-15 support
Symfony - Via PSR-15 adapters (e.g., symfony/psr-http-message-bridge)
Custom PSR-15 middleware stacks
Any PSR-7/PSR-15 compliant application

Why This Matters

Traditional monorepos fail when dependencies conflict. With Mini:

Marketing team uses Slim 4 with latest dependencies
Support team maintains legacy Symfony 4 app with old dependencies
API team writes new endpoints in Mini native code
All three run in one application - no Docker, no microservices, no reverse proxy routing

Database

Mini implements DatabaseInterface with two backends:

PDODatabase - Thin wrapper over PDO:

$users = db()->query("SELECT * FROM users WHERE active = ?", [1]);
$user = db()->queryOne("SELECT * FROM users WHERE id = ?", [123]);

db()->exec("INSERT INTO users (name, email) VALUES (?, ?)", ['John', 'john@example.com']);
db()->transaction(function() {
    db()->exec("INSERT INTO users (name) VALUES (?)", ['John']);
});

VirtualDatabase - SQL interface to non-SQL data (CSV, JSON, APIs):

$vdb = new VirtualDatabase();
$vdb->registerTable('countries', CsvTable::fromFile('data/countries.csv'));

// Query CSV files with SQL
foreach ($vdb->query("SELECT * FROM countries WHERE continent = ?", ['Europe']) as $row) {
    echo $row['name'];
}

Security Pattern: ::mine() as Authorization Boundary

Prevent accidental data leaks by making authorization the default:

class User {
    public static function mine(): PartialQuery {
        $userId = auth()->getUserId();
        // Only return users accessible to current user
        return self::query()->where('id = ? OR EXISTS (...)', [$userId]);
    }
}

// Secure by default - always use ::mine()
$user = User::mine()->eq('id', 123)->one();  // Returns null if not authorized
$friends = User::mine()->limit(50);          // Only authorized users
db()->update(User::mine()->eq('id', 123), ['bio' => 'New']);  // Authorization enforced

// Key insight: ::mine() is shorter than ::query(), so developers naturally use the secure method!

See src/Database/README.md for complete documentation.

Tables - ORM with Repository Pattern (Optional)

Define POPOs (Plain Old PHP Objects) with attributes, managed by repositories.

Like Entity Framework's POCO (Plain Old CLR Object) approach, entities are plain classes without database logic:

use mini\Tables\Attributes\{Entity, Key, Generated, VarcharColumn};

#[Entity(table: 'users')]
class User {
    #[Key] #[Generated]
    public ?int $id = null;

    #[VarcharColumn(100)]
    public string $username;

    public string $email;
}

// Find by primary key
$user = table(User::class)->find($id);

// Query with conditions
$admins = table(User::class)->where('role = ?', ['admin'])->all();

// Save
$user = new User();
$user->username = 'john';
$user->email = 'john@example.com';
table(User::class)->save($user);

Internationalization

Best Practice: Use t() and fmt() everywhere to make your app translatable from day one.

// Always use t() for user-facing text (even in English)
echo t("Hello, {name}!", ['name' => $user->name]);
echo t("You have {count, plural, =0{no messages} one{# message} other{# messages}}",
    ['count' => $messageCount]);

// Always use fmt() for numbers, dates, and currency
echo fmt()->currency($price, 'USD');     // Locale-aware: "$1,234.56" or "1 234,56 $"
echo fmt()->dateShort($order->date);     // "11/15/2025" or "15.11.2025"
echo fmt()->number($revenue);            // "1,234,567.89" or "1.234.567,89"

Per-Request Locale/Timezone

Set locale and timezone per request based on user preferences:

// bootstrap.php (autoloaded via composer.json)
use mini\Mini;
use mini\Phase;

Mini::$mini->phase->onEnteringState(Phase::Ready, function() {
    // Get user's preferred locale from session, cookie, or Accept-Language header
    $locale = $_SESSION['locale'] ?? $_COOKIE['locale'] ?? 'en_US';
    $timezone = $_SESSION['timezone'] ?? 'UTC';

    // Set for this request
    \Locale::setDefault($locale);
    date_default_timezone_set($timezone);
});

Translation files mirror your source code structure in _translations/. For example, strings in _routes/index.php go to _translations/de/_routes/index.php.json:

{
    "Hello, {name}!": "Hallo, {name}!",
    "You have {count, plural, =0{no messages} one{# message} other{# messages}}":
        "Sie haben {count, plural, =0{keine Nachrichten} one{# Nachricht} other{# Nachrichten}}"
}

See src/I18n/README.md for complete documentation, including the vendor/bin/mini translations tool for managing translation files.

Authentication

Simple authentication with pluggable user providers:

// Check authentication
if (!auth()->check()) {
    redirect('/login');
}

// Require login (throws exception if not authenticated)
mini\require_login();

// Role-based access
mini\require_role('admin');

// Login
if (auth()->login($username, $password)) {
    redirect('/dashboard');
}

// Logout
auth()->logout();

Templates

Pure PHP templates with inheritance support:

// Render a template
echo render('user/profile', ['user' => $user]);

Templates support multi-level inheritance:

// _views/user/profile.php
<?php $extend('layouts/main.php'); ?>
<?php $block('title', 'User Profile'); ?>
<?php $block('content'); ?>
    <h1><?= htmlspecialchars($user->name) ?></h1>
    <p><?= t("Member since {date}", ['date' => fmt()->dateShort($user->created)]) ?></p>
<?php $end(); ?>

// _views/layouts/main.php
<!DOCTYPE html>
<html>
<head><title><?php $show('title', 'Untitled'); ?></title></head>
<body><?php $show('content'); ?></body>
</html>

See src/Template/README.md for complete documentation.

Lifecycle Hooks

Hook into application lifecycle via phase transitions:

use mini\Mini;
use mini\Phase;

// Before Ready phase (authentication, CORS, rate limiting)
Mini::$mini->phase->onEnteringState(Phase::Ready, function() {
    // Check authentication
    if (!isset($_SESSION['user_id']) && str_starts_with($_SERVER['REQUEST_URI'], '/admin')) {
        http_response_code(401);
        exit;
    }
});

// After Ready phase (output buffering, response processing)
Mini::$mini->phase->onEnteredState(Phase::Ready, function() {
    ob_start(function($buffer) {
        // Minify HTML
        return preg_replace('/\s+/', ' ', $buffer);
    });
});

Configuration

Environment Variables (.env)

Create a .env file in your project root for environment-specific configuration:

# .env - Not committed to version control

# Database (MySQL/PostgreSQL)
DATABASE_DSN="mysql:host=localhost;dbname=myapp;charset=utf8mb4"
DATABASE_USER="myapp_user"
DATABASE_PASS="secret_password"

# Or use SQLite (default if no config)
# DATABASE_DSN="sqlite:/path/to/database.sqlite3"

# Mini framework settings
MINI_LOCALE="en_US"
MINI_TIMEZONE="America/New_York"
DEBUG=true

# Application salt for security (generate with: openssl rand -hex 32)
MINI_SALT="your-64-character-random-hex-string-here"

# Optional: Custom paths
MINI_ROOT="/path/to/project"
MINI_DOC_ROOT="/path/to/project/html"

Load environment variables with vlucas/phpdotenv or similar:

composer require vlucas/phpdotenv

// bootstrap.php
require __DIR__ . '/vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

Bootstrap File (bootstrap.php)

Create a bootstrap file for application initialization, autoloaded via composer.json:

{
    "autoload": {
        "files": ["bootstrap.php"]
    }
}

// bootstrap.php - Runs before every request
require __DIR__ . '/vendor/autoload.php';

// Load environment variables
if (file_exists(__DIR__ . '/.env')) {
    $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
    $dotenv->load();
}

// Register lifecycle hooks
use mini\Mini;
use mini\Phase;

// Set locale/timezone per request from user session
Mini::$mini->phase->onEnteringState(Phase::Ready, function() {
    session();  // Start session

    // Get user's preferred locale/timezone
    $locale = $_SESSION['locale'] ?? $_ENV['MINI_LOCALE'] ?? 'en_US';
    $timezone = $_SESSION['timezone'] ?? $_ENV['MINI_TIMEZONE'] ?? 'UTC';

    \Locale::setDefault($locale);
    date_default_timezone_set($timezone);
});

// Global error handler (optional)
set_error_handler(function($severity, $message, $file, $line) {
    throw new ErrorException($message, 0, $severity, $file, $line);
});

Database Configuration

Create _config/PDO.php to configure your database:

// _config/PDO.php
$dsn = $_ENV['DATABASE_DSN'] ?? 'sqlite:' . __DIR__ . '/../_database.sqlite3';
$user = $_ENV['DATABASE_USER'] ?? null;
$pass = $_ENV['DATABASE_PASS'] ?? null;

return new PDO($dsn, $user, $pass, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);

Don't forget to run composer dump-autoload after modifying composer.json!

APCu Polyfill

Mini provides zero-configuration APCu polyfills enabling you to use apcu_* functions even when the APCu extension isn't installed. This is particularly useful for:

L1 caching - Sub-millisecond cache operations faster than filesystem or network I/O
Shared memory - Data shared across requests/workers (where supported)
Framework internals - Mini uses APCu for hot-path optimizations (e.g., PathsRegistry file resolution)

How It Works

Mini automatically provides APCu functionality through the best available driver:

Native APCu (when apcu extension is installed) - Uses real shared memory
Swoole\Table (when Swoole extension is installed) - Coroutine-safe shared memory
PDO SQLite (when pdo_sqlite extension available) - Persistent storage in /dev/shm (tmpfs)
Array fallback - Process-scoped only (no cross-request persistence)

No configuration required - the polyfill loads automatically and selects the best driver.

Usage

Use APCu functions as if the extension were installed:

// Store value with 60-second TTL
apcu_store('user:123', $userData, 60);

// Fetch value
$user = apcu_fetch('user:123', $success);
if ($success) {
    echo "Cache hit!";
}

// Atomic entry (fetch-or-compute pattern)
$config = apcu_entry('app:config', function() {
    return loadHeavyConfiguration();
}, ttl: 300);

// Check existence
if (apcu_exists('session:abc123')) {
    echo "Session exists";
}

// Delete
apcu_delete('user:123');

// Clear all
apcu_clear_cache();

Driver Configuration

Swoole Table Driver:

# .env
MINI_APCU_SWOOLE_SIZE=4096          # Number of rows (default: 4096)
MINI_APCU_SWOOLE_VALUE_SIZE=4096    # Max value size in bytes (default: 4096)

SQLite Driver:

# .env
MINI_APCU_SQLITE_PATH=/dev/shm/my_custom_cache.sqlite  # Custom path (optional)

By default, SQLite uses /dev/shm/apcu_mini_{hash}.sqlite on Linux (tmpfs-backed, RAM speed with persistence) or sys_get_temp_dir() otherwise.

Performance Characteristics

Driver	Speed	Persistence	Cross-Request	Cross-Process
Native APCu	Fastest	RAM only	✓	✓
Swoole\Table	Very Fast	RAM only	✓	✓ (workers)
SQLite (/dev/shm)	Fast	✓	✓	✓
Array	Instant	None	✗	✗

When Mini Uses APCu

Mini uses APCu internally for L1 caching in performance-critical paths:

PathsRegistry (src/Util/PathsRegistry.php) - Caches file resolution results (views, routes, translations, config) with 1-second TTL
Future: Translation file loading, metadata caching (opt-in)

Garbage Collection

APCu polyfill drivers implement probabilistic garbage collection (similar to PHP sessions):

1% chance of GC on each apcu_store() or apcu_entry() call
Automatically removes expired entries
No manual cleanup required

Complete API

All standard APCu functions are polyfilled:

apcu_add() - Store if key doesn't exist
apcu_cache_info() - Get cache statistics
apcu_cas() - Compare-and-swap (atomic update)
apcu_clear_cache() - Clear all entries
apcu_dec() - Decrement numeric value
apcu_delete() - Delete one or more keys
apcu_enabled() - Check if APCu is available
apcu_entry() - Atomic fetch-or-compute
apcu_exists() - Check if key(s) exist
apcu_fetch() - Fetch value(s)
apcu_inc() - Increment numeric value
apcu_key_info() - Get key metadata
apcu_sma_info() - Get shared memory info
apcu_store() - Store value(s)

Installation for Production

For best performance in production, install the native APCu extension:

# Debian/Ubuntu
sudo apt-get install php-apcu

# Alpine Linux (Docker)
apk add php83-apcu

# PECL
pecl install apcu

The polyfill automatically detects and uses native APCu when available.

Directory Structure

Directories starting with _ are not web-accessible:

project/
├── .env               # Environment variables (not committed)
├── bootstrap.php      # Application initialization (autoloaded)
├── composer.json      # Dependencies and autoload configuration
├── _routes/           # Route handlers
├── _views/            # Templates
├── _config/           # Service configuration
├── _translations/     # Translation files
├── html/              # Document root (web-accessible)
│   ├── index.php      # Entry point
│   └── assets/        # CSS, JS, images
└── vendor/            # Composer dependencies

Development Server

vendor/bin/mini serve                    # http://localhost
vendor/bin/mini serve --port 3000        # Custom port
vendor/bin/mini serve --host 0.0.0.0     # Bind to all interfaces

Documentation

Essential Guides

docs/WHY-MINI.md - Why choose Mini? Honest discussion of trade-offs vs. Laravel/Symfony
PATTERNS.md - Service overrides, middleware patterns, output buffering
REFERENCE.md - Complete API reference
CHANGE-LOG.md - Breaking changes (Mini is in active development)

Feature Documentation

Detailed documentation for each framework feature:

src/Database/README.md - PDO abstraction, queries, transactions, configuration
src/Template/README.md - Template rendering, inheritance, blocks, partials
src/I18n/README.md - Translations, ICU MessageFormat, locale formatting
src/Tables/README.md - ORM, repositories, entities, query building
src/Auth/README.md - Authentication, user providers, sessions, JWT
src/Cache/README.md - PSR-16 caching, APCu, SQLite, filesystem
src/Mailer/README.md - Email sending via Symfony Mailer
src/Validator/README.md - JSON Schema validation, attributes
src/Logger/README.md - PSR-3 logging, custom loggers
src/Router/README.md - File-based routing, dynamic routes, PSR-15
src/Http/README.md - PSR-7 HTTP messages, error handling
src/Dispatcher/README.md - Request lifecycle, exception handling
src/Converter/README.md - Type conversion for dependency injection
src/Util/README.md - Utility classes (Path, IdentityMap, QueryParser, etc.)
src/Hooks/README.md - Event system, phase lifecycle, state machines
src/UUID/README.md - UUID v4/v7 generation
src/Metadata/README.md - JSON Schema annotations via attributes

CLI Documentation Browser

vendor/bin/mini docs --help              # See available commands
vendor/bin/mini docs mini                # Browse mini namespace
vendor/bin/mini docs "mini\Mini"         # Class documentation

License

MIT License - see LICENSE file.

fubber / mini

Maintainers

Details

README

Philosophy

Engine-Native, Not Userland-Native

Engine-Level Performance

What We Use (And Why)

Lazy-Loading Architecture

Two Paradigms: Choose What Fits

PSR-7 Pattern (Standards-Based)

Native PHP Pattern (Direct)

How They Coexist

Installation

Quick Start

Routing: File System as Routing Table

File-Based Routing

Wildcard Routing with _

Trailing Slash Redirects

Controller-Based Routing

Exception Handling

Dynamic Routes with __DEFAULT__.php

Mounting Sub-Applications

Example: Mount a Slim 4 Application

How It Works

Supported Sub-Applications

Why This Matters

Database

Tables - ORM with Repository Pattern (Optional)

Internationalization

Per-Request Locale/Timezone

Authentication

Templates

Lifecycle Hooks

Configuration

Environment Variables (.env)

Bootstrap File (bootstrap.php)

Database Configuration

APCu Polyfill

How It Works

Usage

Driver Configuration

Performance Characteristics

When Mini Uses APCu

Garbage Collection

Complete API

Installation for Production

Directory Structure

Development Server

Documentation

Essential Guides

Feature Documentation

CLI Documentation Browser

License

Wildcard Routing with `_`

Dynamic Routes with `DEFAULT.php`