getphred/Phred
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
Phred/MILESTONES.md

15 KiB
Raw Blame History

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)

  • 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. ✓
  • 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/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

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

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.