Scaffold miniroute routing/middleware kernel

1 files changed, 106 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..97be075
--- /dev/null
+++ b/README.md
@@ -0,0 +1,106 @@
+# miniroute
+
+A small attribute-based routing and middleware kernel for PHP applications.
+
+miniroute is the tiny piece of routing machinery extracted from
+[brett-parson.com](https://brett-parson.com). It provides attribute-declared
+routes, deterministic route matching, and an onion-style middleware pipeline —
+without being a framework.
+
+## Requirements
+
+- PHP >= 8.2
+
+## Install
+
+### Via Composer (VCS repository)
+
+```bash
+composer config repositories.miniroute vcs https://src.brett-parson.com/git/miniroute.git
+composer require brettparson/miniroute:^0.1
+```
+
+### Via a local path repository (development)
+
+```json
+{
+    "repositories": [
+        { "type": "path", "url": "../miniroute", "options": { "symlink": true } }
+    ],
+    "require": { "brettparson/miniroute": "@dev" }
+}
+```
+
+## Usage
+
+```php
+use BrettParson\MiniRoute\Attribute\Get;
+use BrettParson\MiniRoute\Attribute\Middleware;
+use BrettParson\MiniRoute\Attribute\Post;
+use BrettParson\MiniRoute\Http\RequestInterface;
+use BrettParson\MiniRoute\Http\ResponseInterface;
+use BrettParson\MiniRoute\Routing\Router;
+
+final class NoteController
+{
+    #[Get('/notes')]
+    public function index(RequestInterface $request): ResponseInterface
+    {
+        // ...
+    }
+
+    #[Post('/notes')]
+    #[Middleware(SomeMiddleware::class)]
+    public function store(RequestInterface $request): ResponseInterface
+    {
+        // ...
+    }
+}
+```
+
+The router needs a controller/middleware resolver — an app-owned seam for
+building objects:
+
+```php
+$router = new Router($resolver);
+
+$router->group('/admin', [RequireAdmin::class, RequireCsrf::class]);
+
+$router->registerControllers([
+    HomeController::class,
+    NoteController::class,
+]);
+
+$response = $router->dispatch($request);
+$response->send();
+```
+
+## What it does
+
+- **Route attributes** — `#[Get]`, `#[Post]`, `#[Put]`, `#[Patch]`, `#[Delete]`
+  declare routes directly on controller methods.
+- **Deterministic matching** — literal segments beat `{parameter}` segments,
+  so registration order never matters.
+- **Middleware** — `#[Middleware(...)]` on methods or classes, plus
+  router-level `group()` middleware by path prefix.
+- **Thin HTTP contracts** — `RequestInterface` and `ResponseInterface` keep
+  the kernel decoupled from any one application's HTTP objects.
+
+## What it is not
+
+No container, no template engine, no ORM, no auth, no session handling, no
+configuration loader. Those stay application concerns.
+
+## Tests
+
+```bash
+composer install
+vendor/bin/phpunit
+```
+
+Or, without Composer, drop a `phpunit.phar` into the repo root and run
+`php phpunit.phar`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).