Phred/MILESTONES.md

Phred Framework Milestones

← Back to README | SPECS.md

Phred supports REST and JSON:API via env setting; batteries-included defaults, swappable components.

↑ Back to Top

Table of Contents

• M0 — Project bootstrap (repo readiness)
• M1 — Core HTTP kernel and routing
• M2 — Configuration and environment
• M3 — API formats and content negotiation
• M4 — Error handling and problem details
• M5 — Dependency Injection and Service Providers
• M6 — MVC: Controllers, Views, Templates
• M7 — Modules (Django‑style app structure)
• M8 — Database access, migrations, and seeds
• M9 — CLI (phred) and scaffolding
• M10 — Security middleware and auth primitives
• M11 — Logging, HTTP client, and filesystem
• M12 — Serialization/validation utilities and pagination
• M13 — OpenAPI and documentation
• M14 — Testing, quality, and DX
• M15 — Caching and performance (optional default)
• M16 — Production hardening and deployment
• M17 — JSON:API enhancements (optional package)
• M18 — Examples and starter template
• M19 — Documentation site
• M20 — Dynamic Command Help
• M21 — Governance and roadmap tracking

M0 — Project bootstrap (repo readiness)

• Tasks:
  • Finalize composer.json (namespaces, scripts, suggests) and LICENSE.
  • Add .editorconfig, .gitattributes, .gitignore, example .env.example.
  • Set up CI (lint, static analysis, unit tests) and basic build badge.
• Acceptance:
  • Fresh clone installs (without running suggested packages) and passes linters/analysis/tests.

↑ Back to Top

M1 — Core HTTP kernel and routing

• Tasks:
  • Implement the HTTP kernel: PSR-15 pipeline via Relay.
  • Wire nyholm/psr7(-server) factories and server request creation.
  • Integrate nikic/fast-route with a RouteCollector and dispatcher.
  • Define route → controller resolution (invokable controllers).
  • Add minimal app bootstrap (front controller) and DI container wiring (PHP-DI).
  • Addendum: Route groups (prefix only) via Router::group()
• Acceptance:
  • Sample route returning a JSON 200 via controller.
  • Controllers are invokable (__invoke(Request)), one route per controller.
  • Route groups (prefix only) work and are tested.

↑ Back to Top

M2 — Configuration and environment

• Tasks:
  • Load .env via vlucas/phpdotenv and expose Phred\Support\Config.
  • Define configuration precedence and document keys (e.g., API_FORMAT, APP_ENV, APP_DEBUG).
• Acceptance:
  • App reads config from .env; unit test demonstrates override behavior.

↑ Back to Top

M3 — API formats and content negotiation

• Tasks:
  • Finalize ContentNegotiationMiddleware using .env and Accept header.
  • Bind ApiResponseFactoryInterface to RestResponseFactory or JsonApiResponseFactory based on format.
  • Provide developer‑facing helpers for common responses (ok, created, error).
• Acceptance:
  • Demo endpoints respond correctly as REST or JSON:API depending on API_FORMAT and Accept.

↑ Back to Top

M4 — Error handling and problem details

• Tasks:
  • Finalize ProblemDetailsMiddleware with RFC7807 (REST) and JSON:API error documents.
  • Integrate filp/whoops for dev mode (APP_DEBUG=true).
  • Map common exceptions to HTTP status codes; include correlation/request IDs in responses/logs.
• Acceptance:
  • Throwing an exception yields a standards‑compliant error response; debug mode shows Whoops page.

↑ Back to Top

M5 — Dependency Injection and Service Providers

• Tasks:
  • Define Service Provider interface and lifecycle (register, boot).
  • Module discovery loads providers in order (core → app → module).
  • Add examples for registering controllers, services, config, and routes via providers.
  • Define contracts: Template\Contracts\RendererInterface, Orm\Contracts\*, Flags\Contracts\FeatureFlagClientInterface, Testing\Contracts\TestRunnerInterface.
  • Define config/env keys for driver selection (e.g., TEMPLATE_DRIVER, ORM_DRIVER, FLAGS_DRIVER, TEST_RUNNER).
  • Provide “default adapter” Service Providers for the shipped packages and document swap procedure.
• Acceptance:
  • Providers can contribute bindings and routes; order is deterministic and tested.
  • Drivers can be switched via .env/config without changing controllers/services; example provider route covered by tests.

↑ Back to Top

M6 — MVC: Controllers, Views, Templates

• Tasks:
  • Controller base class and conventions (request/response helpers).
  • View layer (data preparation) with getphred/eyrie template engine integration.
  • Template rendering helper: $this->render(<template>, <data>).
• Acceptance:
  • Example page rendered through View → Template; API coexists with full‑site rendering.
  • Rendering works via RendererInterface and can be swapped (e.g., Eyrie → Twig demo) with only configuration/provider changes.

↑ Back to Top

M7 — Modules (Django‑style app structure)

• Tasks:
  • Define module filesystem layout (Nested Controllers/Views/Services/Models/Templates/Routes/Tests).
  • Module loader: auto‑register providers, routes, templates.
  • Namespacing and autoload guidance.
  • Core CLI: add create:module <name> command to scaffold a module with nested resources.
  • ORM‑agnostic module layout (to support Pairity DAO/DTO and Eloquent Active Record):
    • Modules/<X>/Models/ — domain models (pure PHP, ORM‑neutral)
    • Modules/<X>/Repositories/ — repository interfaces (DI targets for services)
    • Modules/<X>/Persistence/Pairity/ — DAOs, DTOs, mappers, repository implementations
    • Modules/<X>/Persistence/Eloquent/ — Eloquent models, scopes, repository implementations
    • Modules/<X>/Database/Migrations/* — canonical migrations for the module (no duplication per driver)
• Acceptance:
  • Creating a module with the CLI makes it discoverable; routes/templates work without manual wiring.
  • Switching ORM_DRIVER between pairity and eloquent requires no changes to services/controllers; providers bind repository interfaces to driver implementations.

↑ Back to Top

M8 — Database access, migrations, and seeds

• Tasks:
  • Integrate getphred/pairity for ORM/migrations/seeds.
  • Define config (DB_*), migration paths (app and modules), and seeder conventions.
  • CLI commands: migrate, migration:rollback, seed, seed:rollback.
  • All persistence usage in examples goes through Orm contracts; can be swapped (Pairity → Doctrine adapter demo optional).
  • Add register:orm <driver> command:
    • Verify or guide installation of the ORM driver package.
    • Update .env (ORM_DRIVER=<driver>) safely.
    • Create modules/*/Persistence/<Driver>/ directories for existing modules.
• Acceptance:
  • Running migrations modifies a test database; seeds populate sample data; CRUD demo works.
  • All persistence usage in examples goes through Orm contracts; can be swapped (Pairity → Doctrine adapter demo optional).

↑ Back to Top

M9 — CLI (phred) and scaffolding

• Tasks:
  • Implement Symfony Console app in bin/phred.
  • Generators: create:<module>:controller, create:<module>:model, create:<module>:migration, create:<module>:seed, create:<module>:test, create:<module>:view.
  • Utility commands: test[:<module>], run, db:backup, db:restore.
• Acceptance:
  • Commands generate files with correct namespaces/paths and pass basic smoke tests.

↑ Back to Top

M10 — Security middleware and auth primitives

• Tasks:
  • Add CORS, Secure Headers middlewares; optional CSRF for template routes.
  • JWT support (lcobucci/jwt) with simple token issue/verify service.
  • Configuration for CORS origins, headers, methods.
  • Bind FeatureFlagClientInterface with a default adapter (Flagpole); add small sample usage and env config.
• Acceptance:
  • CORS preflight and secured endpoints behave as configured; JWT‑protected route example works.

↑ Back to Top

M11 — Logging, HTTP client, and filesystem

• Tasks:
  • Monolog setup with handlers and processors (request ID, memory, timing).
  • Guzzle PSR‑18 client exposure; DI binding for HTTP client interface.
  • Flysystem integration with local adapter; abstraction for storage disks.
  • Standardize all core service providers with robust driver validation (similar to OrmServiceProvider).
  • Opportunity Radar: Multiple storage disks, log channel management, and HTTP client middleware.
  • Opportunity Radar 2: Storage Disk "Cloud" Adapters (S3), Advanced HTTP Middleware (Circuit Breaker), and Log Alerting (Slack/Sentry).
  • Opportunity Radar 3: Githook Integration, Breadcrumb Automation, and TOC for MILESTONES.md.
  • Opportunity Radar 4: Middleware Groups and Centralized Route List Command.
  • Opportunity Radar 5: FeatureTestCase, Middleware Group Auto-Mounting, and Route Caching.
• Acceptance:
  • Logs include correlation IDs; sample outbound HTTP call via client; file upload/storage demo works.

↑ Back to Top

M12 — Serialization/validation utilities and pagination

• Tasks:
  • REST default: Symfony Serializer normalizers/encoders; document extension points.
  • Add simple validation layer using Phred\Http\Middleware\Middleware base.
  • Pagination helpers (links/meta), REST and JSON:API compatible outputs.
  • URL extension negotiation: add XML support
    • Provide XmlResponseFactory (or encoder) and integrate with negotiation.
    • Enable xml in URL_EXTENSION_WHITELIST by default.
  • Opportunity Radar: Storage URL generation, Circuit Breaker persistence (PSR-16), and HTTP client profiling.
• Acceptance:
  • Example endpoint validates input, returns 422 with details; paginated listing includes links/meta.

↑ Back to Top

M13 — OpenAPI and documentation

• Tasks:
  • Integrate zircote/swagger-php annotations.
  • CLI/task to generate OpenAPI JSON; optional serve route and Redoc UI pointer.
  • Document auth, pagination, error formats.
• Acceptance:
  • Generated OpenAPI document validates; matches sample endpoints.

↑ Back to Top

M14 — Testing, quality, and DX

• Tasks:
  • Establish testing structure with Codeception (unit, integration, API suites).
  • Add fixtures/factories via Faker for examples.
  • PHPStan level selection and baseline; code style via php-cs-fixer ruleset.
  • Pre‑commit hooks (e.g., GrumPHP) or custom git hooks for staged files.
  • Define TestRunnerInterface and a Codeception adapter; otherwise, state tests are run via Composer script only.
• Acceptance:
  • composer test runs green across suites; static analysis passes.
  • CLI tests run via TestRunnerInterface;
  • CLI tests run green per module and across suites.

↑ Back to Top

M15 — Caching and performance (optional default)

• Tasks:
  • Provide PSR-16 cache interface binding; suggest symfony/cache when enabled.
  • Simple response caching middleware and ETag/Last‑Modified helpers.
  • Rate limiting middleware (token bucket) suggestion/integration point.
• Acceptance:
  • Sample endpoint demonstrates cached responses and conditional requests.

↑ Back to Top

M16 — Production hardening and deployment

• Tasks:
  • Config for envs (dev/test/stage/prod), error verbosity, trusted proxies/hosts.
  • Docker example, PHP‑FPM + Nginx config templates.
  • Healthcheck endpoint, readiness/liveness probes.
• Acceptance:
  • Containerized demo serves both API and template pages; healthchecks pass.

↑ Back to Top

M17 — JSON:API enhancements (optional package)

• Tasks:
  • If enabled, integrate neomerx/json-api fully: includes, sparse fieldsets, relationships, sorting, filtering, pagination params.
  • Adapters/Schema providers per resource type.
• Acceptance:
  • JSON:API conformance tests for selected endpoints pass; docs updated.

↑ Back to Top

M18 — Examples and starter template

• Tasks:
  • Create examples/shop module showcasing controllers, views, templates, ORM, auth, pagination, and both API formats.
  • Ensure examples use the external stubs and module-specific CLI command conventions.
  • Provide composer create-project skeleton template instructions.
• Acceptance:
  • New users can scaffold a working app in minutes following README.

↑ Back to Top

M19 — Documentation site

• Tasks:
  • Build the official documentation site (getphred.com) using the Phred framework.
  • Internal Documentation API: Design a "Documentation Module" that parses Markdown files from the repo to serve them dynamically.
  • Automated TOC Generation: Script to regenerate SPECS.md Table of Contents.
  • Versioned docs and upgrade notes.
• Acceptance:
  • Docs published; links in README; examples maintained.

↑ Back to Top

M20 — Dynamic Command Help

• Tasks:
  • Implement a docs command in phred (e.g., php phred docs <command>) that opens the relevant documentation page in the user's browser.
  • Build the docs command logic after the documentation site (getphred.com) is functional.
• Acceptance:
  • php phred docs create:module opens the correct URL in the default browser.

↑ Back to Top

M21 — Governance and roadmap tracking

• Tasks:
  • Define contribution guide, issue templates, RFC process for changes.
  • Public roadmap (this milestone list) tracked as GitHub Projects/Issues.
• Acceptance:
  • Contributors can propose features via RFC; roadmap is visible and updated.

↑ Back to Top