Kusala Tech » thatnerdjosh

# PHP Lightweight MVC

# Table of Contents

1.  [Front controller](#org9c7b4c8)

2.  [Bootstrap and autoloading](#orgd97911a)

3.  [Core primitives](#orgbc694b2)

    1.  [Router](#org85fe152)

    2.  [Controller base class](#org02d2927)

    3.  [View renderer](#org7067757)

    4.  [Database helper](#org0ac8e7d)

4.  [App configuration](#orgc8e69ca)

5.  [Domain model: Inventory](#org65b2d22)

    1.  [InventoryItem](#orgde15914)

    2.  [Repository interface](#org5216bbd)

    3.  [Session-backed repository (design mode)](#org52f1f8c)

    4.  [DB-backed repository (production mode)](#org2e5e208)

    5.  [Repository factory and legacy alias](#orge48a85c)

6.  [Inventory controller and views](#org7820e2f)

    1.  [Controller](#orgb815a5a)

    2.  [Views](#org38818cd)

7.  [Switching from design to DB mode](#org2b26eb8)

This document describes the tiny MVC framework used in this directory.

It is written as a **literate program**: prose explains the design, and

source blocks tangle into the PHP files under `core/`, `app/`, and

`public/`. The goal is to keep development easy and make the transition

from in-memory prototypes to a real database very clear.

<a id="org9c7b4c8"></a>

# Front controller

All web requests enter through a single front controller:

    <?php

    declare(strict_types=1);

    require __DIR__ . '/../core/bootstrap.php';

    use Core\Router;

    use App\Config;

    $router = new Router(Config::BASE_URL);

    $router->get('/', 'InventoryController@index');

    $router->get('/inventory', 'InventoryController@index');

    $router->get('/inventory/show/{id}', 'InventoryController@show');

    $router->post('/inventory', 'InventoryController@store');

    $router->dispatch($_SERVER['REQUEST_METHOD'], $_SERVER['REQUEST_URI']);

<a id="orgd97911a"></a>

# Bootstrap and autoloading

The bootstrap file sets error reporting, wires up PSR-4-style autoloading

for `Core\\` and `App\\` namespaces, starts a PHP session for

in-memory development, and conditionally bootstraps the database layer

when we switch to DB-backed storage.

    <?php

    declare(strict_types=1);

    error_reporting(E_ALL);

    ini_set('display_errors', '1');

    // Simple PSR-4-style autoloader for Core and App namespaces.

    spl_autoload_register(function (string $class): void {

        $prefixes = [

            'Core\\' => __DIR__ . '/',

            'App\\'  => __DIR__ . '/../app/',

        ];

        foreach ($prefixes as $prefix => $baseDir) {

            $len = strlen($prefix);

            if (strncmp($class, $prefix, $len) !== 0) {

                continue;

            }

            $relative = substr($class, $len);

            $file = $baseDir . str_replace('\\', '/', $relative) . '.php';

            if (is_file($file)) {

                require $file;

                return;

            }

        }

    });

    // Simple session-based state so in-memory models can persist

    // across requests during the design phase.

    if (session_status() !== PHP_SESSION_ACTIVE) {

        session_start();

    }

    // If inventory storage is configured as 'db', bootstrap the database

    // connection once for the request. When using 'session' storage, the

    // DB layer is completely skipped.

    use App\Config;

    use Core\Database;

    $storageMode = getenv('INVENTORY_STORAGE') ?: Config::INVENTORY_STORAGE;

    if ($storageMode === 'db') {

        Database::init(Config::dbDsn(), Config::DB_USER, Config::DB_PASSWORD);

    }

<a id="orgbc694b2"></a>

# Core primitives

<a id="org85fe152"></a>

## Router

The `Router` maps HTTP methods and paths to controller actions.

    <?php

    namespace Core;

    class Router

    {

        private string $baseUrl;

        private array $routes = [

            'GET'  => [],

            'POST' => [],

        ];

        public function __construct(string $baseUrl = '')

        {

            $this->baseUrl = rtrim($baseUrl, '/');

        }

        public function get(string $path, string $handler): void

        {

            $this->addRoute('GET', $path, $handler);

        }

        public function post(string $path, string $handler): void

        {

            $this->addRoute('POST', $path, $handler);

        }

        private function addRoute(string $method, string $path, string $handler): void

        {

            $this->routes[$method][] = [

                'pattern' => $this->compilePath($path),

                'handler' => $handler,

                'raw'     => $path,

            ];

        }

        private function compilePath(string $path): string

        {

            $regex = preg_replace('#\\{([a-zA-Z_][a-zA-Z0-9_]*)\\}#', '(?P<$1>[^/]+)', $path);

            return '#^' . rtrim($regex, '/') . '/?$#';

        }

        public function dispatch(string $method, string $uri): void

        {

            $path = parse_url($uri, PHP_URL_PATH) ?? '/';

            $path = preg_replace('#^' . preg_quote($this->baseUrl, '#') . '#', '', $path) ?: '/';

            foreach ($this->routes[$method] ?? [] as $route) {

                if (preg_match($route['pattern'], $path, $matches)) {

                    [$controllerName, $action] = explode('@', $route['handler']);

                    $controllerClass = 'App\\Controllers\\' . $controllerName;

                    if (!class_exists($controllerClass)) {

                        http_response_code(500);

                        echo "Controller {$controllerClass} not found.";

                        return;

                    }

                    $controller = new $controllerClass();

                    if (!method_exists($controller, $action)) {

                        http_response_code(500);

                        echo "Action {$action} not found on controller {$controllerClass}.";

                        return;

                    }

                    $params = array_filter(

                        $matches,

                        fn($key) => !is_int($key),

                        ARRAY_FILTER_USE_KEY

                    );

                    call_user_func_array([$controller, $action], $params);

                    return;

                }

            }

            http_response_code(404);

            echo "404 Not Found";

        }

    }

<a id="org02d2927"></a>

## Controller base class

Controllers use a thin base class that knows how to render views and

redirect.

    <?php

    namespace Core;

    class Controller

    {

        protected function render(string $view, array $data = []): void

        {

            View::render($view, $data);

        }

        protected function redirect(string $url): void

        {

            header("Location: {$url}");

            exit;

        }

    }

<a id="org7067757"></a>

## View renderer

Views are plain PHP templates under `app/Views`. The view renderer just

finds the file and exposes the data array as local variables.

    <?php

    namespace Core;

    class View

    {

        public static string $basePath = __DIR__ . '/../app/Views/';

        public static function render(string $view, array $data = []): void

        {

            $file = self::$basePath . $view . '.php';

            if (!is_file($file)) {

                http_response_code(500);

                echo "View {$view} not found.";

                return;

            }

            extract($data, EXTR_SKIP);

            require $file;

        }

    }

<a id="org0ac8e7d"></a>

## Database helper

The DB helper is a light wrapper around PDO. It is only initialized when

we choose DB-backed storage.

    <?php

    namespace Core;

    use PDO;

    use PDOException;

    class Database

    {

        private static ?PDO $pdo = null;

        public static function init(string $dsn, string $user, string $password): void

        {

            if (self::$pdo !== null) {

                return;

            }

            try {

                self::$pdo = new PDO($dsn, $user, $password, [

                    PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,

                    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,

                ]);

            } catch (PDOException $e) {

                http_response_code(500);

                echo 'DB connection error: ' . htmlspecialchars($e->getMessage());

                exit;

            }

        }

        public static function pdo(): PDO

        {

            if (self::$pdo === null) {

                throw new \RuntimeException('Database::init() must be called first.');

            }

            return self::$pdo;

        }

    }

<a id="orgc8e69ca"></a>

# App configuration

The `Config` class centralizes app configuration, including how

inventory data is stored: purely in-memory/session for design, or in a

real database.

    <?php

    namespace App;

    /**

     * App-level configuration.

     */

    final class Config

    {

        /**

         * Base URL of the app (e.g. when deployed under a subdirectory).

         */

        public const BASE_URL = '';

        /**

         * Where inventory data is stored.

         * - 'session'  => in PHP session (design/dev mode, no DB required)

         * - 'db'       => MySQL via Core\\Database

         */

        public const INVENTORY_STORAGE = 'session';

        // --- Database configuration (used only when INVENTORY_STORAGE = 'db') ---

        public const DB_HOST = '127.0.0.1';

        public const DB_NAME = 'local';

        public const DB_USER = 'mysql';

        public const DB_PASSWORD = 'mysql';

        public static function dbDsn(): string

        {

            $host = getenv('DB_HOST') ?: self::DB_HOST;

            $db   = getenv('DB_NAME') ?: self::DB_NAME;

            return "mysql:host={$host};dbname={$db};charset=utf8mb4";

        }

    }

<a id="org65b2d22"></a>

# Domain model: Inventory

<a id="orgde15914"></a>

## InventoryItem

An `InventoryItem` is the core domain object.

    <?php

    namespace App\Models;

    class InventoryItem

    {

        public ?int $id;

        public string $name;

        public function __construct(?int $id, string $name)

        {

            $this->id   = $id;

            $this->name = $name;

        }

    }

<a id="org5216bbd"></a>

## Repository interface

We access inventory data through an `InventoryRepository` interface. The

rest of the app does not care whether data lives in memory or in a DB.

    <?php

    namespace App\Models;

    interface InventoryRepository

    {

        /** @return InventoryItem[] */

        public function all(): array;

        public function find(int $id): ?InventoryItem;

        public function create(string $name): InventoryItem;

    }

<a id="org52f1f8c"></a>

## Session-backed repository (design mode)

During the design phase we keep everything in PHP session state. This

requires no schema and is very forgiving.

    <?php

    namespace App\Models;

    /**

     * Inventory repository backed by PHP session data.

     *

     * This keeps development fluid: no real DB is required during

     * the design phase, but items persist across HTTP requests for

     * a single browser session. Later we can swap this for a

     * DB-backed implementation without touching controllers/views.

     */

    class SessionInventoryRepository implements InventoryRepository

    {

        private const SESSION_ITEMS_KEY = 'inventory_items';

        private const SESSION_NEXT_ID_KEY = 'inventory_next_id';

        public function __construct()

        {

            // Seed with a sample item to make first-run UX nicer.

            $items = $this->getStore();

            if (empty($items)) {

                $this->create('Sample item');

            }

        }

        /**

         * @return InventoryItem[]

         */

        public function all(): array

        {

            return array_values($this->getStore());

        }

        public function find(int $id): ?InventoryItem

        {

            $items = $this->getStore();

            return $items[$id] ?? null;

        }

        public function create(string $name): InventoryItem

        {

            $items =& $this->getStore();

            $nextId = $this->getNextId();

            $item = new InventoryItem($nextId, $name);

            $items[$nextId] = $item;

            $this->setNextId($nextId + 1);

            return $item;

        }

        /** @return array<int, InventoryItem> */

        private function &getStore(): array

        {

            if (!isset($_SESSION[self::SESSION_ITEMS_KEY]) || !is_array($_SESSION[self::SESSION_ITEMS_KEY])) {

                $_SESSION[self::SESSION_ITEMS_KEY] = [];

            }

            // Ensure everything in the store is a valid InventoryItem; if not,

            // drop it so views/controllers don't see incomplete objects.

            foreach ($_SESSION[self::SESSION_ITEMS_KEY] as $id => $value) {

                if (!$value instanceof InventoryItem) {

                    unset($_SESSION[self::SESSION_ITEMS_KEY][$id]);

                }

            }

            /** @var array<int, InventoryItem> $store */

            $store =& $_SESSION[self::SESSION_ITEMS_KEY];

            return $store;

        }

        private function getNextId(): int

        {

            if (!isset($_SESSION[self::SESSION_NEXT_ID_KEY])) {

                $_SESSION[self::SESSION_NEXT_ID_KEY] = 1;

            }

            return (int)$_SESSION[self::SESSION_NEXT_ID_KEY];

        }

        private function setNextId(int $nextId): void

        {

            $_SESSION[self::SESSION_NEXT_ID_KEY] = $nextId;

        }

    }

<a id="org2e5e208"></a>

## DB-backed repository (production mode)

When you are happy with the object design and ready to introduce a real

schema, you can switch to the DB-backed repository. It expects a table

like:

    CREATE TABLE inventory_items (

        id   INT AUTO_INCREMENT PRIMARY KEY,

        name VARCHAR(255) NOT NULL

    );

The implementation simply translates between DB rows and

`InventoryItem` objects.

    <?php

    namespace App\Models;

    use Core\Database;

    /**

     * Database-backed inventory repository.

     */

    class DbInventoryRepository implements InventoryRepository

    {

        /** @return InventoryItem[] */

        public function all(): array

        {

            $stmt = Database::pdo()->query('SELECT id, name FROM inventory_items ORDER BY id DESC');

            $rows = $stmt->fetchAll();

            return array_map(

                fn(array $r) => new InventoryItem((int)$r['id'], $r['name']),

                $rows

            );

        }

        public function find(int $id): ?InventoryItem

        {

            $stmt = Database::pdo()->prepare('SELECT id, name FROM inventory_items WHERE id = :id');

            $stmt->execute(['id' => $id]);

            $row = $stmt->fetch();

            if (!$row) {

                return null;

            }

            return new InventoryItem((int)$row['id'], $row['name']);

        }

        public function create(string $name): InventoryItem

        {

            $stmt = Database::pdo()->prepare('INSERT INTO inventory_items (name) VALUES (:name)');

            $stmt->execute(['name' => $name]);

            $id = (int)Database::pdo()->lastInsertId();

            return new InventoryItem($id, $name);

        }

    }

<a id="orge48a85c"></a>

## Repository factory and legacy alias

A tiny factory chooses the correct repository implementation based on

configuration. There is also a legacy `Inventory` class kept as a thin

alias for backwards compatibility.

    <?php

    namespace App\Models;

    use App\Config;

    final class InventoryRepositoryFactory

    {

        public static function make(): InventoryRepository

        {

            $mode = getenv('INVENTORY_STORAGE') ?: Config::INVENTORY_STORAGE;

            return $mode === 'db'

                ? new DbInventoryRepository()

                : new SessionInventoryRepository();

        }

    }

    <?php

    namespace App\Models;

    /**

     * Legacy alias kept for backwards compatibility.

     *

     * New code should type-hint against InventoryRepository and obtain

     * an instance via InventoryRepositoryFactory.

     */

    class Inventory extends SessionInventoryRepository

    {

    }

<a id="org7820e2f"></a>

# Inventory controller and views

<a id="orgb815a5a"></a>

## Controller

The controller depends only on the `InventoryRepository` interface and

obtains a concrete instance from the factory. It does not know whether

storage is session-based or database-backed.

    <?php

    namespace App\Controllers;

    use Core\Controller;

    use App\Models\InventoryRepository;

    use App\Models\InventoryRepositoryFactory;

    class InventoryController extends Controller

    {

        private InventoryRepository $inventory;

        public function __construct()

        {

            // Decide at runtime whether to use the session-backed or

            // DB-backed repository. Controllers and views don't care.

            $this->inventory = InventoryRepositoryFactory::make();

        }

        public function index(): void

        {

            $items = $this->inventory->all();

            $this->render('inventory/index', [

                'items' => $items,

            ]);

        }

        public function show(int $id): void

        {

            $item = $this->inventory->find($id);

            if ($item === null) {

                http_response_code(404);

                echo 'Item not found';

                return;

            }

            $this->render('inventory/show', [

                'item' => $item,

            ]);

        }

        public function store(): void

        {

            $name = trim($_POST['name'] ?? '');

            if ($name === '') {

                $this->render('inventory/index', [

                    'items' => $this->inventory->all(),

                    'error' => 'Name is required',

                ]);

                return;

            }

            $this->inventory->create($name);

            $this->redirect('/inventory');

        }

    }

<a id="org38818cd"></a>

## Views

Finally, two simple views display the inventory list and a single item.

They are deliberately dumb: just HTML + PHP echoing properties.

    <?php /** @var App\Models\InventoryItem[] $items */ ?>

    <!doctype html>

    <html>

    <head>

        <meta charset="utf-8">

        <title>Inventory</title>

    </head>

    <body>

    <h1>Inventory for teachingcode.org</h1>

    <?php if (!empty($error)): ?>

        <p style="color:red;"><?php echo htmlspecialchars($error, ENT_QUOTES, 'UTF-8'); ?></p>

    <?php endif; ?>

    <ul>

        <?php foreach ($items as $item): ?>

            <li>

                <?php echo htmlspecialchars($item->name, ENT_QUOTES, 'UTF-8'); ?>

                (<a href="/inventory/show/<?php echo (int)$item->id; ?>">details</a>)

            </li>

        <?php endforeach; ?>

    </ul>

    <form method="post" action="/inventory">

        <label>

            New item name:

            <input type="text" name="name">

        </label>

        <button type="submit">Add</button>

    </form>

    </body>

    </html>

    <?php /** @var App\Models\InventoryItem $item */ ?>

    <!doctype html>

    <html>

    <head>

        <meta charset="utf-8">

        <title>Item: <?php echo htmlspecialchars($item->name, ENT_QUOTES, 'UTF-8'); ?></title>

    </head>

    <body>

    <h1><?php echo htmlspecialchars($item->name, ENT_QUOTES, 'UTF-8'); ?></h1>

    <p>Item ID: <?php echo (int)$item->id; ?></p>

    <p><a href="/inventory">Back to list</a></p>

    </body>

    </html>

<a id="org2b26eb8"></a>

# Switching from design to DB mode

-   During design, you can rely entirely on the session-backed repository:

    -   `Config::INVENTORY_STORAGE` is `'session'`

    -   No schema or running database is required.

-   When you are ready to move to a real database:

    1.  Create the `inventory_items` table as shown above.

    2.  Set the environment variable `INVENTORY_STORAGE=db` (or change

        `Config::INVENTORY_STORAGE` to `'db'`).

    3.  Ensure MySQL credentials in `Config` match your `docker-compose`

        service.

Controllers and views do not need to change; only configuration and the

repository implementation determine where data actually lives.