docs: document boot-callback dialect override pattern for postgres-wire-compatible databases#85
Merged
Merged
Conversation
Adds an integration test and documentation proving that postgres-wire- compatible databases (CockroachDB, YugabyteDB, etc.) can ship as sibling packages by depending on marko/database-pgsql and overriding the 4 dialect bindings via a boot callback — no package splits, no framework changes. - Integration test in packages/database-pgsql proves a downstream module can override SqlGenerator/Introspector/QueryBuilder/QueryBuilderFactory while inheriting PgSqlConnection, and confirms the static-bindings path correctly throws BindingConflictException. - New "Overriding another module's bindings" section in the DI concept doc documents the generic pattern (applies to any sibling driver). - New "Wire-compatible database variants" section in the database guide with a worked CockroachDB-style example. - Cross-link from database-pgsql page to the database guide. Closes #31 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
the
documentation
The marko/ vendor namespace is reserved for core Marko packages, so variant driver packages must ship under their own vendor namespace. Updates the worked CockroachDB example in database.md and the override example in dependency-injection.md to use acme/database-cockroachdb and Acme\Database\CockroachDb\ accordingly. Also corrects the sequence.after example in dependency-injection.md to use the composer package name format (marko/database-pgsql) rather than a PHP class name, matching how sequence.after is actually parsed. 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.
Summary
Closes #31 by proving and documenting that postgres-wire-compatible databases (CockroachDB, YugabyteDB, etc.) can ship as sibling packages depending on
marko/database-pgsqland overriding only the 4 dialect-specific bindings via abootcallback — without splitting packages, renaming anything, or changing the framework.Why this approach
packages/database-pgsql/module.phpalready exposes 5 separate bindings, andPgSqlConnectionis dialect-clean (PDO +SET NAMESonly). The architectural split the issue asks for is largely already done. The missing piece was a supported way for a downstream sibling package to override the dialect bindings without triggeringBindingConflictException.Investigation surfaced that
Container::bind()is a direct write that bypassesBindingRegistry's conflict detection, and modulebootcallbacks run after all static bindings are registered. So a sibling dialect package can override the 4 dialect interfaces in its ownmodule.phpboot closure today — zero framework changes needed.What's in this PR
packages/database-pgsql/tests/Module/DialectOverrideTest.php) — proves a downstream module can overrideSqlGeneratorInterface,IntrospectorInterface,QueryBuilderInterface, andQueryBuilderFactoryInterfacevia boot while inheritingPgSqlConnection. Includes a regression guard asserting the pgsql manifest declares nosingletonsfor the 4 dialect interfaces (since a cached singleton would defeat the override), and a loud-error guarantee that the static-bindings path throwsBindingConflictException.concepts/dependency-injection.mddocuments the generic pattern (applies to any sibling driver, not just database).packages/database.mdwith a worked CockroachDB-stylecomposer.json+module.phpexample.packages/database-pgsql.mdpointing to the variants guide.Test plan
composer test— 5282 tests pass (1 pre-existing unrelated failure inSplitWorkflowTestaboutSPLIT_TOKEN)npm --prefix docs run build— clean, no warnings./vendor/bin/phpcsclean on touched filesCloses #31
🤖 Generated with Claude Code