Clean Framework · DOCUMENTATION
Framework gaps and competitive roadmap
Framework gaps and competitive roadmap
Bounded candidate reference — 2026-10-20: 0.2.0-rc.1 is committed locally through 84f415b3098af5653577b2c65eea31fca21df79c, unpublished and not production-approved; stable PHP >=8.5.11 <8.6.0 is required. This is documentation, not adoption: this knowledge base retains its installed 0.1.0-rc.1 dependency and PHP 8.2.11 local profile. Dated PHP 8.2 evidence is historical; earlier dirty-source reports retain their original test provenance, not retroactive clean-commit proof. Candidate examples are illustrative: API signatures were reviewed, but candidate code was not executed by this editorial update. See current checkpoint, open criteria and adoption boundary.
Historical roadmap reading rule: the 145/18 introductory snapshot, older gap rows and environment-blocked/0.1.0 statements below are historical, not the latest local result. The original register is now 148 PASS / 15 TO VERIFY / four N/A. Atomic SQL handoff, module policy, audit and native/Q03 tooling have scoped local proof. Independent, host, human, optional-module and release gates remain OPEN. Use current checkpoint and qualification profile, not old rows alone, to assess the candidate. Comparison scores remain historical and are not raised.
Current Next Generation source/qualification status is recorded in the final local report: 145 scoped PASS, 18 TO VERIFY and four optional benchmark N/A on the documented PHP 8.5 pilot profile. Older dated counts/roadmap statements below remain historical or broader host requirements; do not relabel them as current production proof.
Purpose and status
2026-10-16 update: the owner authorized framework-local implementation of the next-generation program, including a breaking PHP >=8.5.11 <8.6.0 target. WP-00 baseline is recorded; WP-01 source preparation and WP-02 guard preparation do not close runtime/database gates. Actual PHP 8.5, disposable DB, process/host and independent review remain open. Earlier authorization restrictions and comparison scores below are historical; other apps, external installs, commits and deployment still require separate scope.
Recorded 2026-10-15, America/New_York. This is a planning register, not an implementation or production-readiness declaration. Its purpose is to make Clean Framework a demonstrably better choice for selected applications, not to claim universal superiority over Laravel or Symfony.
The owner authorized documenting gaps, improvement targets, and a development pipeline. That does not authorize implementing this backlog, changing the PHP minimum, running external services, provisioning credentials, or deploying. Prosperous Pairs source, website, server, accounts, and credentials remain out of scope without new action-specific permission.
Subsequent owner authorization on 2026-10-15 selected PHP 8.2.x and implemented CF-G01's local runtime/Apache work in the independent framework only. See actual compatibility evidence. Other gaps remain OPEN; this does not authorize their implementation or knowledge-base edits. The target-host/current-security-patch portion of CF-G01 remains open.
The neutral framework remains a local 0.1.0-rc.1 candidate. Read implementation status, the platform matrix, and deferred components before selecting capabilities. The knowledge base is a separate application: its local HTTP/Apache evidence and account provisioning do not certify every framework adapter or runtime.
Comparison snapshot, not an acceptance gate
These 1-to-10 scores preserve the 2026-10-15 advisory comparison. They are subjective assessments, not measurements, independent audits, vulnerability probabilities, or evidence that one application will be secure or fast. The overall assessment is weighted judgment, not an arithmetic average. Reassess after evidence changes; do not raise a score merely because a class exists.
| Category | Clean Framework | Laravel | Symfony |
|---|---|---|---|
| Architecture and separation of responsibilities | 8 | 9 | 10 |
| HTTP, routing, middleware, dependency injection | 8 | 9 | 10 |
| Database tooling and persistence options | 4 | 10 | 9 |
| Authentication and security tooling maturity | 6 | 9 | 9 |
| Queues, scheduling, background processing | 5 | 9 | 9 |
| Testing and debugging developer experience | 5 | 9 | 9 |
| Documentation and onboarding | 7 | 10 | 9 |
| Reusable packages and integrations | 2 | 10 | 9 |
| Production-readiness evidence | 4 | 9 | 9 |
| Maintenance continuity and support | 3 | 9 | 9 |
| Fit for the owner's native-PHP and explicit-code preferences | 9 | 8 | 8 |
| Overall general-purpose assessment | 6 | 9 | 9 |
Fit is preference-specific. Native PHP templates, explicit SQL, and explicit dependency injection are deliberate design choices, not defects to replace with an ORM, template compiler, or automatic service discovery for points.
Gap register
CF-G01 is locally implemented/verified with patch/target-host acceptance OPEN; all other rows remain OPEN. P0 blocks a corresponding production-support claim; P1 improves sustainable development; P2 is optional differentiation. A named owner must be assigned before implementation. Closure requires linked test artifacts and review, not this document. Proposed additions remain NOT STARTED unless the implementation ledger records existing mechanics separately.
| ID | Priority and type | Current boundary and source | Required work and closure evidence |
|---|---|---|---|
| CF-G01 | P0: runtime/hosting verification | Next candidate requires PHP >=8.5.11 <8.6.0; policy/metadata are source-prepared. Actual PHP 8.5 execution is ENVIRONMENT BLOCKED. The older 8.2 module/FPM evidence remains historical. | Supply approved isolated PHP 8.5 CLI/FPM, run complete local/deprecation/HTTP gates, then qualify the exact current-patch OS/Apache/handler/proxy host. See migration. No new-candidate support closure follows from policy simulation. |
| CF-G02 | P0: database verification; P1: breadth | Prepared mysqli access, transaction ownership and migrations exist; real MySQL/MariaDB acceptance remains TO VERIFY. See database guide. | Prove fresh/upgrade migrations, checksum drift, advisory locking, rollback, nontransactional DDL failure, binary/decimal/Unicode data, connection loss and concurrent writers. Restore a matched code/database backup. Evaluate pagination/query composition and optional adapters only against actual application needs; an ORM is not mandatory. |
| CF-G03 | P0: security assurance | Session/CSRF, token, authorization, upload and machine-credential mechanisms exist; deployment/application and shared-store proofs are incomplete. See security guide. | Threat-model trust boundaries; exercise object-level denial, proxy spoofing, session fixation, token replay/races, revocation, file traversal/symlinks/ranges and credential redaction. Add risk-based fuzz/property tests and independent review. Define supported security requirements and resolve findings under a severity policy. Do not claim greater security from test counts alone. |
| CF-G04 | P0: durability/concurrency | Queue, outbox, scheduler, locks and idempotency state machines exist; database/process evidence is incomplete. See background-work guide. | Run concurrent real connections; inject kill/restart, lease expiry, stale-worker completion, lock contention, transaction failure and duplicate delivery. Prove bounded retries, dead-letter/replay, overlap rules, unknown-outcome reconciliation and idempotent business effects. At-least-once transport is not exactly-once execution. |
| CF-G05 | P0 when enabled: integrations/media/AI | Provider/OAuth/webhook, native-media and AI/action mechanics have local or fake evidence. See deferred work. | Test one approved sandbox/adapter at a time, including timeouts/TLS, signature/replay, encrypted-token rotation, receipt/outbox atomicity and quota races. Sandbox hostile media with resource limits. Independently evaluate AI schema/injection/permission/cost/reconciliation behavior. Disabled optional modules do not block an otherwise qualified minimal release. |
| CF-G06 | P1: developer tooling | Local verification commands exist; broad static analysis, IDE diagnostics and safe debugging workflows are not established as a supported toolchain. See testing. | Evaluate and pin formatter/static-analysis/test tools; agree a legacy baseline without hiding new findings. Add safe correlation-based diagnostics, route/config/container inspection and reproducible fixtures. Diagnostics must redact secrets and be disabled or strongly controlled on hosted systems. No tool is installed by this plan. |
| CF-G07 | P1: onboarding/API usability | Walkthroughs, behavioral comments and a private knowledge base exist; documentation gates do not prove semantic correctness. See API guide. | Execute complete examples against the matching package; document failure/ownership/compatibility behavior; run unfamiliar-developer tasks; correct confusing wiring. Link each supported feature to a working recipe and failure example. Version the knowledge-base snapshot and show support limitations alongside examples. |
| CF-G08 | P0: operations/recovery | Observability contracts and local checks exist; deployment backend, capacity, recovery and incident ownership remain incomplete. See release checklist. | Select redacted logs/metrics/alerts; set workload-specific latency, errors, queue lag, RPO and RTO objectives before testing. Prove alert delivery, disk/storage failure, retention and encrypted-backup restoration on an isolated target. Assign on-call/incident and rollback owners. A backup file alone is not recovery evidence. |
| CF-G09 | P1: maintenance/release continuity | Proprietary local candidate with optional preserved legacy bridge; no established public-scale support operation. See portability. | Assign primary and backup maintainers, security-report channel, triage/patch targets, support windows and deprecation rules. Produce reproducible versioned artifacts, dependency inventory and migration notes. Verify the bridge stays opt-in; do not rewrite preserved files or expose proprietary code to create ecosystem appearances. |
| CF-G10 | P1: integration ecosystem | Neutral ports and some adapters exist; breadth is far below the established alternatives. See provider guide. | Prioritize the few adapters needed by real applications; require ownership, license/dependency review, contract suites, version policy and sandbox proof. Prefer maintained dependencies when appropriate rather than hand-building every integration. Package count is not a quality metric. |
| CF-G11 | P2: comparative performance | No controlled Clean/Laravel/Symfony benchmark exists. Smaller source or dependency count does not establish speed. | Build equivalent authorized test applications and execute the protocol below. Publish raw distributions, resource measurements, configuration and failed runs. Performance claims remain UNMEASURED until reproduced. |
| CF-G12 | P1: frontend/assets; P2: optimization | Native PHP and optional assets exist; generic AJAX, compiled-template caching and automatic CSS image sizing remain deferred. See views, assets, and AJAX contract. | First prove accessibility, escaping, CSP, cache validators/invalidation, bounded derivatives and responsive-image behavior. Benchmark PHP OPcache before proposing a template cache. Any private HTML cache needs identity/permission/locale-aware keys and revocation/invalidation proof; never bypass authorization. Frontend automation requires separate design and approval. |
Where Clean can aim to exceed the alternatives
The following are proposed targets, not observed results or promises. Target approval must name the workload, comparator versions, owner, budget and review date. Failure is recorded honestly; do not weaken a safety requirement to win.
| Target | Proposed measurable outcome | Prerequisites and evidence |
|---|---|---|
| CF-T01: explainable onboarding | At least five developers unfamiliar with Clean complete the same configuration-to-protected-CRUD task on all three frameworks. Clean's median completion time is at least 25% lower than each comparator, with equivalent tests/security and at least four successful completions. | CF-G02/03/06/07. Counterbalance task/framework order, record experience, interventions, elapsed time and defects. Treat this small study as directional, not population-wide proof. |
| CF-T02: resource efficiency | On at least two preselected representative workloads, Clean uses at least 20% less peak worker memory than each comparator, with p95 latency no more than 5% worse and no correctness/security regression. | CF-G01/02/04/11. Pin load/concurrency and define memory sampling/worker lifetime. Report uncertainty and all workloads, including losses. |
| CF-T03: faster safe diagnosis | In blinded configuration, authorization, database and worker-failure exercises, Clean reduces median correct time-to-diagnosis by at least 25% against each comparator without exposing sensitive data. | CF-G03/06/07/08. Define identical faults, access level and assistance; publish correct diagnoses, errors, redaction results and confidence limits. |
| CF-T04: traceable release safety | Every supported high-risk invariant links to a positive, denial and relevant concurrency/failure test; every artifact has an evidence manifest; no undispositioned release-blocking finding remains. | CF-G01 through CF-G09. This is Clean's own gate, not proof of superiority. Comparative claims require applying the same independent rubric to equivalent Laravel/Symfony applications. |
| CF-T05: predictable upgrades | Two unrelated applications upgrade from an actual prior supported artifact to the candidate with passing contract tests, bounded measured effort and rehearsed database recovery. | CF-G02/07/09. First establish real supported releases; do not fabricate historical upgrades. Compare equivalent supported version changes before claiming a better upgrade experience. |
Community size, years of deployment history and the number of experienced maintainers cannot be recreated by a coding phase. Reduce continuity risk through ownership, useful integrations, independent reviews and real adoption. Do not label Clean universally better because it wins a selected benchmark.
Fair comparison protocol
- Pre-register workloads and success thresholds: public native/server-rendered page, authenticated paginated CRUD with equivalent SQL/data, JSON validation, idempotent background work and a protected-file response. Record excluded features rather than silently simplifying one implementation.
- Pin exact framework/dependency/PHP/database versions, artifact hashes, hardware/OS, Apache handler, OPcache, workers, cache settings, dataset and network. Use a mutually supported, maintained PHP version. The existing PHP 8.2 standard cannot run Laravel 13, whose official release notes require PHP 8.3 or newer. Choose explicitly maintained comparator versions that share PHP 8.2, or obtain a new Clean runtime decision before a same-runtime comparison. Never bypass constraints or present mixed-runtime results as an isolated framework comparison; older-comparator wins do not prove superiority over the latest releases.
- Tune each framework using its documented production settings. Disable development debug/profilers equally. Compare standard documented stacks, and label specialized long-running-worker configurations separately.
- Match response semantics, validation, authentication/authorization, CSRF, error handling, database work, durability and serialization. Validate output and business effects before collecting performance samples.
- Measure cold start separately from warmed steady state. Warm up, randomize execution order, and collect at least five independent measured runs per scenario with enough requests to estimate tails. Publish throughput, p50, p95/p99, errors, CPU, memory, query counts and queue lag; disclose tooling, sampling, variance and confidence intervals. More runs are required when noise prevents a credible distinction.
- Preserve scripts, sanitized seeds, settings, raw measurements and failed runs. Have someone other than the implementation author reproduce them. Do not publish private datasets, credentials or source without approval.
- Use a bounded claim such as "lower peak worker memory in workload X under configuration Y." No blanket faster, safer or better claim follows from it.
Delivery order and tracking
Follow development pipeline. Work in order: evidence/scope, runtime/database, security/durability, operations/recovery, tooling/onboarding, controlled comparisons, then a limited pilot/release. Optional adapters may run in separate gated tracks; no release may advertise an unverified optional capability as supported.
For each gap, record: ID; owner and reviewer; current status; source/artifact revision; proposed contract; dependencies and permission; tests and exact commands; findings; evidence locations; unfinished risks; next action; and support/rollback impact. Use the existing implementation-ledger statuses. The register originally opened all gaps; only CF-G01 has subsequent scoped local implementation evidence. Other implementation remains NOT STARTED unless the ledger says otherwise. An overall score is never an exit gate.
Official reference baseline
Reviewed 2026-10-15. Links describe comparator capabilities and policies, not the subjective scores above; recheck and pin exact releases before experiments.
- Laravel release and support policy: version/support conventions and PHP requirements.
- Laravel databases and Eloquent: persistence capabilities to compare with explicit SQL.
- Laravel queues and deployment: worker operations and production configuration.
- Laravel testing and authentication: developer tooling and identity composition.
- Symfony service container and Doctrine integration: composition and persistence references.
- Symfony Messenger and security: messaging and security references.
- Symfony testing, profiler, and performance: diagnostic and benchmark configuration references.
- Symfony release process: release lifecycle reference.
Editorial provenance
Source: docs/FRAMEWORK_GAPS_AND_ROADMAP.md. Source SHA-256: 19189084448b164e2564708729fa38d2ebd3bbacad51011bb052036d54bfc38a.
Framework candidate reference; editorial checkpoint 2026-10-20. See candidate status and adoption boundary.