269 lines
15 KiB
Markdown
269 lines
15 KiB
Markdown
# Phred Framework Milestones
|
||
|
||
[← Back to README](./README.md) | [SPECS.md](./SPECS.md)
|
||
|
||
Phred supports REST and JSON:API via env setting; batteries-included defaults, swappable components.
|
||
|
||
[↑ Back to Top](#table-of-contents)
|
||
## Table of Contents
|
||
- [~~M0 — Project bootstrap (repo readiness)~~](#m0-project-bootstrap-repo-readiness)
|
||
- [~~M1 — Core HTTP kernel and routing~~](#m1-core-http-kernel-and-routing)
|
||
- [~~M2 — Configuration and environment~~](#m2-configuration-and-environment)
|
||
- [~~M3 — API formats and content negotiation~~](#m3-api-formats-and-content-negotiation)
|
||
- [~~M4 — Error handling and problem details~~](#m4-error-handling-and-problem-details)
|
||
- [~~M5 — Dependency Injection and Service Providers~~](#m5-dependency-injection-and-service-providers)
|
||
- [~~M6 — MVC: Controllers, Views, Templates~~](#m6-mvc-controllers-views-templates)
|
||
- [~~M7 — Modules (Django‑style app structure)~~](#m7-modules-django-style-app-structure)
|
||
- [~~M8 — Database access, migrations, and seeds~~](#m8-database-access-migrations-and-seeds)
|
||
- [~~M9 — CLI (phred) and scaffolding~~](#m9-cli-phred-and-scaffolding)
|
||
- [~~M10 — Security middleware and auth primitives~~](#m10-security-middleware-and-auth-primitives)
|
||
- [~~M11 — Logging, HTTP client, and filesystem~~](#m11-logging-http-client-and-filesystem)
|
||
- [~~M12 — Serialization/validation utilities and pagination~~](#m12-serialization-validation-utilities-and-pagination)
|
||
- [M13 — OpenAPI and documentation](#m13-openapi-and-documentation)
|
||
- [M14 — Testing, quality, and DX](#m14-testing-quality-and-dx)
|
||
- [M15 — Caching and performance (optional default)](#m15-caching-and-performance-optional-default)
|
||
- [M16 — Production hardening and deployment](#m16-production-hardening-and-deployment)
|
||
- [M17 — JSON:API enhancements (optional package)](#m17-json-api-enhancements-optional-package)
|
||
- [M18 — Examples and starter template](#m18-examples-and-starter-template)
|
||
- [M19 — Documentation site](#m19-documentation-site)
|
||
- [M20 — Dynamic Command Help](#m20-dynamic-command-help)
|
||
- [M21 — Governance and roadmap tracking](#m21-governance-and-roadmap-tracking)
|
||
- [Notes on sequencing and parallelization](#notes-on-sequencing-and-parallelization)
|
||
|
||
## ~~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](#table-of-contents)
|
||
## ~~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](#table-of-contents)
|
||
## ~~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](#table-of-contents)
|
||
## ~~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](#table-of-contents)
|
||
## ~~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](#table-of-contents)
|
||
## ~~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](#table-of-contents)
|
||
## ~~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](#table-of-contents)
|
||
## ~~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](#table-of-contents)
|
||
## ~~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](#table-of-contents)
|
||
## ~~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](#table-of-contents)
|
||
## ~~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](#table-of-contents)
|
||
## ~~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.~~ ✓
|
||
* ~~Acceptance:~~
|
||
* ~~Logs include correlation IDs; sample outbound HTTP call via client; file upload/storage demo works.~~ ✓
|
||
|
||
[↑ Back to Top](#table-of-contents)
|
||
## ~~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](#table-of-contents)
|
||
## 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](#table-of-contents)
|
||
## 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](#table-of-contents)
|
||
## 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](#table-of-contents)
|
||
## 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](#table-of-contents)
|
||
## 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](#table-of-contents)
|
||
## M18 — Examples and starter template
|
||
* Tasks:
|
||
* Create `examples/blog` 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](#table-of-contents)
|
||
## 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](#table-of-contents)
|
||
## 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](#table-of-contents)
|
||
## 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](#table-of-contents)
|
||
## Notes on sequencing and parallelization
|
||
* M0–M4 are critical path for the HTTP core and should be completed sequentially.
|
||
* M5–M8 can progress in parallel with M9 (CLI) once the kernel is stable.
|
||
* Optional tracks (M15, M17) can be deferred without blocking core usability.
|