Update project documentation and composer.json with explicit optional parameter logic and author details

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.

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');`

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<RouteDefinition>` 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 <METHOD> <URL>`: 
+    - 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.

composer.json

@@ -5,7 +5,10 @@
     "license": "MIT",
     "authors": [
         {
-            "name": "QualityCoder"
+            "name": "Phred",
+            "email": "phred@getphred.com",
+            "homepage": "https://getphred.com",
+            "role": "Owner"
         }
     ],
     "require": {