feat: centralize driver registries with known-drivers.php pattern#91
Merged
Conversation
Curated known-drivers.php per interface package as the single source of truth for each driver list. CI tests enforce sync between the file, each driver's composer.json conflict block, and skeleton's suggest block. Eliminates the three-locations-drift problem when adopting new drivers. 25 tasks, ~5 parallel batches. WIP — depends on PR #88 (view-twig) merging first so task 017 can be expanded to cover both view drivers. Relates to #89 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 27, 2026
PR #92 settled the architectural question: Marko relies on DI-level BindingConflictException for double-binding detection, not Composer `conflict` declarations. This plan no longer adds conflict blocks or validates them — every rollout task is correspondingly simpler. Changes: - Deleted task 004 (pilot conflict blocks) — no longer needed - Updated _plan.md task table, objective, success criteria, risks - Removed assertConflictBlocksMatch from KnownDriversValidator (task 001); helper now exposes assertSkeletonSuggestContainsAll + assertDocsUrlsResolveToValidPattern - Stripped conflict sub-step / requirement / acceptance criterion from rollout tasks 008-016 (multi-driver) and 011 (inertia) - Rewrote task 017 (view): both view-latte and view-twig now in monorepo post-PR #92, no conflicts, both belong in known-drivers.php - Cleaned up "vacuous conflict assertion" phrasing from single-driver tasks 018-024 - Simplified task 024 (page-cache): removed page-cache-entity conflict verification (moot when no drivers have conflicts) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…mark ready Closes the gap left by deleting the conflict-blocks pilot task in the previous commit. Tasks 005-025 each decrement by one (005 -> 004, 006 -> 005, ..., 025 -> 024). All cross-references updated: - File names - Task headers - Depends-on fields - _plan.md task table - Prose references Also updates two stale references to view-twig in Discovery Notes that predated PR #88 / #92 (both drivers are now in monorepo, view rollout is no longer a single-driver case). Status: planning -> ready (plan-orchestrate expects this). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ource of truth for driver discovery - Add KnownDriversValidator to marko/testing with assertSkeletonSuggestContainsAll and assertDocsUrlsResolveToValidPattern - Create known-drivers.php in all 18 interface packages (authentication, cache, database, encryption, errors, filesystem, http, inertia, log, mail, media, notification, page-cache, pubsub, queue, session, translation, view) - Refactor all 18 NoDriverException classes to read from known-drivers.php with descriptions and derived docs URLs - Create inertia NoDriverException (previously missing) - Rename page-cache NoDriverException factory from noBinding to noDriverInstalled for consistency - Add KnownDriversValidationTest to each interface package for CI skeleton-suggest parity enforcement - Extend errors-advanced PrettyHtmlFormatter to render context/suggestion fields and linkify URLs - Move view IntegrationTest from marko/view to marko/view-latte (zero-dependency cleanup) - Consolidate skeleton composer.json suggest block with all drivers and optional add-ons - Add cross-cutting KnownDriversSuggestParityTest to skeleton Closes #89 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
markshust
changed the title
…n-drivers.php files
Enforce a single canonical shape for driver descriptions:
- '{Tech} {category} driver ({parenthetical})'
- Category noun matches family name (mail/log not mailer/logger; errors/media not error handler/image processor; view not template engine driver)
- Recommended marker uses '(recommended; {justification})' — never '(recommended for X)' which read ambiguously
- At most one recommended driver per family (was previously multiple)
- All descriptive detail inside parens (no prose before/after the parenthetical)
- No em-dashes within driver descriptions
Document the convention at docs/concepts/known-drivers.md with format rules,
recommendation policy, punctuation, and the three category exceptions
(HTTP client, Inertia.js frontend, page cache).
Update skeleton composer.json suggest block to match new strings verbatim
so per-package KnownDriversValidationTest assertions pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements #89. Establishes
known-drivers.phpas the single curated source of truth for each interface package's drivers, eliminating hardcoded driver lists scattered acrossNoDriverExceptionclasses. CI tests mechanically enforce sync between this file and skeleton'ssuggestblock.What's in this PR
All 24 plan tasks implemented across 135 files (+2,535 / -396).
KnownDriversValidatorinmarko/testing— shared helper withassertSkeletonSuggestContainsAllandassertDocsUrlsResolveToValidPattern. Skips gracefully when skeleton isn't on disk or hasn't been populated yet; fails loudly on drift.known-drivers.phpin all 18 interface packages —authentication,cache,database,encryption,errors,filesystem,http,inertia,log,mail,media,notification,page-cache,pubsub,queue,session,translation,view. Flatpackage => descriptionarrays with recommended-first ordering.NoDriverExceptionclasses refactored — no more hardcodedDRIVER_PACKAGESconsts; suggestion text now includes description,composer requirecommand, and derivedmarko.build/docs/packages/{basename}/URL per driver.NoDriverExceptionformarko/inertia— previously missing.marko/page-cache's outliernoBinding()→noDriverInstalled()for cross-package consistency.KnownDriversValidationTest— enforces skeleton-suggest parity via CI on every interface.marko/errors-advancedimprovements —PrettyHtmlFormatternow renderscontextandsuggestionfields (previously silently dropped) and auto-linkifieshttp(s)://URLs withtarget="_blank" rel="noopener noreferrer".marko/viewtest cleanup —IntegrationTestmoved tomarko/view-latte; view package now has zero dependency on its own drivers in tests.composer.jsonsuggestblock contains all 29 drivers (recommended-first per interface) plus optional add-ons (marko/database-readwrite,marko/page-cache-entity). Cross-cuttingKnownDriversSuggestParityTestasserts everyknown-drivers.phpentry is present.Test results
5,611 tests passing (61 new). The 5 remaining failures (
MySqlConnectionFacx2,PackagingTestx2,SplitWorkflowTestx1) are pre-existing infrastructure-dependent failures unrelated to this work.Architectural alignment with merged PRs
conflictdeclarations (per PR refactor(view): drop mutual conflict; align with multi-driver pattern #92). Marko's DI-levelBindingConflictExceptionis the canonical detection for double-bindings.marko/viewhas both drivers inknown-drivers.php(per PR feat: add Twig template engine driver as sibling to Latte #88 + refactor(view): drop mutual conflict; align with multi-driver pattern #92).known-engines.phpis orthogonal (PR feat: extract admin-panel templates into engine-specific sibling packages #94) — lists registered view engines for cross-engine template parity, not driver packages.Closes #89