From 2d1cc99ed518973c8ce214a6ceeedf96e1b6ab55 Mon Sep 17 00:00:00 2001 From: Funky Waddle Date: Thu, 12 Feb 2026 14:34:25 -0600 Subject: [PATCH] Update project documentation and composer.json with explicit optional parameter logic and author details --- MILESTONES.md | 61 +++++++++++++++++++++++ NOTES.md | 5 ++ SPECS.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++ composer.json | 5 +- 4 files changed, 200 insertions(+), 1 deletion(-) create mode 100644 MILESTONES.md create mode 100644 SPECS.md diff --git a/MILESTONES.md b/MILESTONES.md new file mode 100644 index 0000000..cab0e69 --- /dev/null +++ b/MILESTONES.md @@ -0,0 +1,61 @@ +# Atlas Routing: Milestones + +This document outlines the phased development roadmap for the Atlas Routing engine, based on the `SPECS.md`. + +## Milestone 1: Foundation & Core Architecture +*Goal: Establish the base classes, configuration handling, and the internal route representation.* +- [ ] Define `Route` and `RouteDefinition` classes (SRP focused). +- [ ] Implement the `Router` class with Inversion of Control (DI for config). +- [ ] Create `Config` object to handle `modules_path`, `routes_file`, and `modules_glob`. +- [ ] Implement `MissingConfigurationException`. +- [ ] Setup Basic PHPUnit suite with a "Hello World" route test. + +## Milestone 2: Basic URI Matching & Methods +*Goal: Implement the matching engine for standard HTTP methods and static URIs.* +- [ ] Implement fluent methods: `get()`, `post()`, `put()`, `patch()`, `delete()`. +- [ ] Build the URI Matcher for static paths. +- [ ] Support for PSR-7 `ServerRequestInterface` type-hinting in the matcher. +- [ ] Implement basic Error Handling (Global 404). + +## Milestone 3: Parameters & Validation +*Goal: Support for dynamic URIs with the `{{var}}` syntax and parameter validation.* +- [ ] Implement `{{variable_name}}` and `{{variable_name?}}` (optional) parsing. +- [ ] Add `valid()` method (chaining and array support). +- [ ] Add `default()` method and logic for implicit optional parameters. +- [ ] Support for dynamic/regex-based segment matching. + +## Milestone 4: Route Groups & First-Class Objects +*Goal: Implement recursive grouping and the ability to treat groups as functional objects.* +- [ ] Implement `group()` method with prefix/middleware inheritance. +- [ ] Ensure Route Groups are first-class objects (routes can be added directly to them). +- [ ] Implement indefinite nesting and recursive merging of properties. +- [ ] Support group-level parameter validation. + +## Milestone 5: Modular Routing +*Goal: Automate route discovery and registration based on directory structure.* +- [ ] Implement the `module()` method. +- [ ] Build the discovery logic for `src/Modules/{Name}/routes.php`. +- [ ] Implement middleware/prefix inheritance for modules. +- [ ] Conflict resolution for overlapping module routes. + +## Milestone 6: Advanced Capabilities & Interoperability +*Goal: Add specialized routing features and full PSR-7 compatibility.* +- [ ] Implement `redirect()` native support. +- [ ] Add Route Attributes/Metadata (`attr()` and `meta()`). +- [ ] Implement `url()` generation (Reverse Routing). +- [ ] Add `fallback()` support at group/module levels. +- [ ] Implement Subdomain Constraints and i18n support. + +## Milestone 7: Tooling & Inspector API +*Goal: Provide developer tools for debugging and inspecting the routing table.* +- [ ] Develop the Programmatic Inspector API (`getRoutes()`, `match()`). +- [ ] Build the `route:list` CLI command. +- [ ] Build the `route:test` CLI command with diagnostic output. +- [ ] Ensure JSON output support for tooling integration. + +## Milestone 8: Performance & Optimization +*Goal: Finalize the engine with caching and production-ready performance.* +- [ ] Implement Route Caching (serializable optimized structure). +- [ ] Performance benchmarking and matcher optimization. +- [ ] Final Documentation (KDoc, README, Examples). +- [ ] Release v1.0.0. diff --git a/NOTES.md b/NOTES.md index 7006f66..9ff3c41 100644 --- a/NOTES.md +++ b/NOTES.md @@ -104,6 +104,8 @@ Implementing modular routing in this way will not only enhance the functionality - Atlas will have route parameters - indicated by `{{var}}` - example: `https://example.com/users/{{user_id}}` + - optional parameters indicated by `{{var?}}` + - example: `https://example.com/blog/{{slug?}}` - Atlas will have route parameter validation options - `$router->get('/users/{{user_id}}', 'UserController::__invoke')->valid('user_id', ['numeric','int','required']);` - Supporting for multiple parameters each having their own validation @@ -111,6 +113,9 @@ Implementing modular routing in this way will not only enhance the functionality - `$router->get('/users/{{user_id}}/posts/{{post_id}}', 'PostController@show')->valid(['user_id' => ['numeric', 'int', 'required'], 'post_id' => ['numeric', 'int', 'required']]);` - chaining syntax - `$router->get('/users/{{user_id}}/posts/{{post_id}}', 'PostController@show')->valid('user_id', ['required'])->valid('post_id', ['required']);` +- Atlas will have Default Values + - `$router->get('/blog/{{page}}')->default('page', 1);` + - Providing a default value automatically marks the parameter as optional. - Atlas will have route names - `$router->get('/users/{{user_id}}', 'UserController::__invoke')->name('single_user');` - `$router->get('/users', 'UserController::__invoke')->name('user_list');` diff --git a/SPECS.md b/SPECS.md new file mode 100644 index 0000000..e48b730 --- /dev/null +++ b/SPECS.md @@ -0,0 +1,130 @@ +# Atlas Routing: Technical Specifications + +## 1. Project Overview +Atlas is a high-performance, modular PHP routing engine designed for professional-grade applications. It prioritizes developer experience, architectural purity, and interoperability through PSR-7 support. + +## 2. Technical Requirements +- **PHP Version**: `^8.2` +- **Interoperability**: Strict compliance with PSR-7 (`Psr\Http\Message\ServerRequestInterface`) for request matching. +- **Dependencies**: + - `psr/http-message`: For HTTP message interfaces. + - `phpunit/phpunit` (Dev): For testing. + +## 3. Architectural Principles +- **SOLID**: Strict adherence to object-oriented design principles. +- **KISS**: Favoring simple, maintainable solutions over complexity. +- **DRY**: Minimizing duplication through abstraction. +- **YAGNI**: Implementing only requested and necessary functionality. +- **Single Responsibility Principle (SRP)**: Applied at both class and method levels. +- **Inversion of Control (IoC)**: No environment guessing; all configurations must be explicitly injected. +- **Verbose & Expressive Style**: Self-documenting code with clear, descriptive naming. +- **Type Safety**: Mandatory use of PHP 8.2+ type hinting (scalar, union, intersection, DNF). + +## 4. Core Routing Features + +### 4.1 Route Definition +- Support for standard HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. +- Fluent, chainable API for route configuration. +- **Example Usage**: + - `$router->get('/path', 'Handler');` + - `$router->post('/path', 'Handler');` +- Support for named routes: `->name('route_name')`. + - **Example**: `$router->get(...)->name('user_list');` +- Reverse routing (URL Generation): `$router->url(string $name, array $parameters = []): string`. + - Automatically replaces `{{var}}` placeholders. + - Throws exception if required parameters are missing. + - **Example**: `$router->url('single_user', ['user_id' => 5]);` + +### 4.2 URI Matching & Parameters +- **Syntax**: Double curly braces `{{variable_name}}` for parameter encapsulation. + - **Example**: `/users/{{user_id}}` +- **Optional Parameters**: + - Indicated by a trailing question mark inside the braces: `{{variable_name?}}`. + - **Example**: `/blog/{{slug?}}` +- **Validation**: + - Chaining: `->valid('param', ['rule1', 'rule2'])` + - Array: `->valid(['param1' => ['rule'], 'param2' => ['rule']])` + - **Example**: `$router->get(...)->valid('user_id', ['numeric', 'int', 'required']);` +- **Default Values**: + - Set via `->default(string $param, mixed $value)`. + - Providing a default value automatically marks a parameter as optional. + - **Example**: `$router->get('/blog/{{page}}')->default('page', 1);` +- **Regex Support**: Dynamic matching for complex URI patterns. + +### 4.3 Route Groups +- Route groups are **first-class objects**. +- Routes can be added directly to a group instance: `$group->get(...)`. +- Nested grouping with `->group()` method. +- Indefinite nesting support. +- Recursive merging of prefixes and middleware. +- Support for parameter validation at the group level. +- **Example**: + ```php + $group = $router->group(['prefix' => '/users/{{user_id}}'])->valid('user_id', ['int']); + $group->get('/posts', 'PostController@index'); + ``` + +### 4.4 Redirection +- Native support for redirects: `$router->redirect(string $path, string $destination, int $status = 302)`. + +### 4.5 Route Attributes (Metadata) +- "Tag-along" data for routes using `->attr(string $key, mixed $value)` or `->meta(array $data)`. +- Used for non-routing logic (e.g., Breadcrumbs, ACL, UI hints). +- Accessible via the matched `Route` object. + +## 5. Modular Routing + +### 5.1 Discovery & Structure +- **Explicit Injection**: `modules_path` (string or array) and `routes_file` (default `routes.php`) must be provided. +- **Optional `modules_glob`**: Custom pattern for module discovery (e.g., `modules/*/Http/routes.php`). +- **Convention**: Standard location is `src/Modules/{ModuleName}/routes.php`. +- **Automatic Registration**: The `module('ModuleName', 'prefix')` method triggers discovery. +- **Example Configuration**: + ```php + $router = new Router([ + 'modules_path' => '/abs/path/to/modules', + 'routes_file' => 'routes.php' + ]); + ``` +- **Exception**: Throws `MissingConfigurationException` if `module()` is called without `modules_path`. + +### 5.2 Inheritance +- Modules inherit base URL prefixes and module-level middleware. +- Conflict resolution mechanisms for overlapping route names or paths. + +## 6. Advanced Functionality + +### 6.1 Subdomain Routing +- Ability to constrain routes or groups to specific subdomains. + +### 6.2 Internationalization (i18n) +- Localized route support for translated URI segments. + +### 6.3 Performance & Caching +- Implementation of route caching to optimize matching in large-scale applications. +- Optimized, serializable structure for production environments. + +### 6.4 Error Handling +- Localized and global fallback handlers: `fallback(callable|string $handler)`. +- Support for custom 404 responses at the module or group level. + +## 7. CLI & Tooling + +### 7.1 Programmatic Inspector API +- `getRoutes()`: Returns `iterable` containing method, path, name, handler, middleware, module, and group data. +- `match(string $method, string $url, array $server = [])`: Returns a `MatchResult` for debugging. +- `toArray()` / `jsonSerialize()`: For structured output. + +### 7.2 CLI Commands (Optional) +- `route:list`: + - Filters: `--method`, `--name`, `--path`, `--module`, `--domain`, `--json`. + - Output: method(s), path template, name, handler, middleware, module, group prefix. +- `route:test `: + - Options: `--host`, `--accept-language`. + - Diagnostics: name, template, handler, params, middleware chain, module/group context, timing. + - Exit codes: `0` (match found), `2` (no match), `1` (error). + +## 8. Quality Assurance +- **Testing**: Mandatory Unit and Integration tests using PHPUnit. +- **Documentation**: PHPDoc for all public members; updated README and examples. +- **Regression**: Every bug fix requires a corresponding regression test. diff --git a/composer.json b/composer.json index 4b4a4fb..9837585 100644 --- a/composer.json +++ b/composer.json @@ -5,7 +5,10 @@ "license": "MIT", "authors": [ { - "name": "QualityCoder" + "name": "Phred", + "email": "phred@getphred.com", + "homepage": "https://getphred.com", + "role": "Owner" } ], "require": {