Atlas/MILESTONES.md

Atlas Routing: Milestones

This document outlines the phased development roadmap for the Atlas Routing engine, based on the SPECS.md.

Rules of Development

• One at a Time: Milestones must be implemented one at a time. Do not move to the next milestone until the current one is fully completed and verified.
• Definition of Done: A milestone is considered complete only when:
  • The full suite of tests passes.
  • There are no deprecation warnings.
  • There are no errors.
  • There are no failures.
• Manual Transition: Do not automatically proceed to the next milestone without explicit verification of the current milestone's completion.

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: Comprehensive Test Coverage

Goal: Bring the testing suite up to standards by covering untested core functionality and edge cases.

• Implement unit tests for RouteGroup to verify prefixing and registration logic.
• Implement integration tests for Router::module() using mock/temporary files for discovery.
• Expand Router::url() tests to cover parameter replacement and error cases (missing parameters).
• Add unit tests for Router::fallback() and its handler execution.
• Implement comprehensive unit tests for Config class methods and interface implementations.
• Add regression tests for MissingConfigurationException in module discovery.

Milestone 4: Architectural Refinement (SRP & SOLID)

Goal: Decompose the Router into focused components for better maintainability and testability.

• Extract route storage and retrieval into RouteCollection.
• Extract matching logic into a dedicated RouteMatcher class.
• Extract module discovery and loading logic into ModuleLoader.
• Refactor Router to act as a Facade/Orchestrator delegating to these components.
• Update existing tests to maintain compatibility with the refactored Router architecture.

Milestone 5: Code Quality & Error Standardization

Goal: Eliminate duplication and unify the exception handling strategy.

• Create PathHelper to centralize and standardize path normalization.
• Consolidate NotFoundRouteException and RouteNotFoundException into a single expressive exception.
• Refactor matchOrFail() to utilize match() to eliminate logic duplication (DRY).
• Update and expand the test suite to reflect centralized normalization and consolidated exceptions.

Milestone 6: Fluent Configuration & Dynamic Matching

Goal: Implement the complete fluent interface and support for dynamic URIs.

• Add fluent configuration methods to RouteDefinition (name, valid, default, middleware, attr).
• Implement {{parameter}} and {{parameter?}} syntax support in the matching engine.
• Implement regex generation for dynamic URI patterns.
• Enable nested RouteGroup support with recursive merging of prefixes and middleware.
• Create comprehensive tests for dynamic matching, parameter extraction, and nested group logic.

Milestone 7: Documentation & Quality Assurance

Goal: Ensure professional-grade quality through comprehensive docs and tests.

• Conduct a full PHPDoc audit and ensure 100% documentation coverage.
• Add integration tests for nested groups and modular loading.
• Add regression tests for consolidated exceptions and path normalization.
• Verify that all existing and new tests pass with 100% success rate.

Milestone 8: 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.
• Add unit tests for parameter parsing, optionality, and validation rules.

Milestone 9: 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.
• Add tests for nested group inheritance and group-level validation logic.

Milestone 10: 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.
• Add integration tests for module discovery and route registration.

Milestone 11: 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.
• Add tests for redirection, attributes, subdomain constraints, and i18n.

Milestone 12: 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.
• Add tests for Inspector API and CLI command outputs.

Milestone 13: 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).
• Implement performance regression tests and benchmark verification.
• Release v1.0.0.