René's URL Explorer Experiment


Title: [RFC]: Named exception constructors for the PostgreSQL adapter · Issue #15 · php-db/phpdb-pgsql · GitHub

Open Graph Title: [RFC]: Named exception constructors for the PostgreSQL adapter · Issue #15 · php-db/phpdb-pgsql

X Title: [RFC]: Named exception constructors for the PostgreSQL adapter · Issue #15 · php-db/phpdb-pgsql

Description: Proposed Version 0.1.0 Basic Information core#189 established a convention: no exception is constructed with a message assembled at the throw site. Every throw goes through a static named constructor on a component-owned exception class,...

Open Graph Description: Proposed Version 0.1.0 Basic Information core#189 established a convention: no exception is constructed with a message assembled at the throw site. Every throw goes through a static named construct...

X Description: Proposed Version 0.1.0 Basic Information core#189 established a convention: no exception is constructed with a message assembled at the throw site. Every throw goes through a static named construct...

Opengraph URL: https://github.com/php-db/phpdb-pgsql/issues/15

X: @github

direct link

Domain: github.com


Hey, it has json ld scripts:
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[RFC]: Named exception constructors for the PostgreSQL adapter","articleBody":"### Proposed Version\n\n0.1.0\n\n### Basic Information\n\ncore#189 established a convention: no exception is constructed with a message assembled at the throw site. Every throw goes through a `static` named constructor on a component-owned exception class, with the message template beside it as a `final public const string`. That work is merged on core `0.6.x` across six pull requests, leaving one `throw new` in the whole package. This proposes the same for this adapter.\n\nThis package has **16 throw sites and no `Exception` namespace**. Every one reaches into core's `PhpDb\\Adapter\\Exception\\*` classes and supplies its message inline:\n\n| File | Sites |\n|---|---|\n| `Connection.php` | 9 |\n| `Pdo/Connection.php` | 2 |\n| `Container/ConnectionInterfaceFactory.php` | 1 |\n| `Container/PdoConnectionInterfaceFactory.php` | 1 |\n| `Driver.php` | 1 |\n| `Result.php` | 1 |\n| `Statement.php` | 1 |\n\nThrown types: `Exception\\RuntimeException` 9, `Exception\\InvalidQueryException` 2, `Exception\\InvalidArgumentException` 2, `InvalidConnectionParametersException` 2, `Exception\\InvalidConnectionParametersException` 1.\n\nThe convention, as merged in core#190 to core#195 and documented in `docs/book/exceptions.md`:\n\n- Named constructors are `static`, return `self` and start with `for`.\n- Each has a single `final public const string` template beside it, named for the method: `forMissingDsn()` uses `MISSING_DSN`.\n- `new self(self::CONST)` when the template has no placeholder, `new self(sprintf(self::CONST, ...))` when it does.\n- Quote a `%s` holding a caller-supplied identifier; leave a class name, method name or count unquoted.\n- **There is one marker interface, `PhpDb\\Exception\\ExceptionInterface`, and it extends `Throwable`.** Components do not declare their own. A class inherits the marker from the core class it extends, so no `implements` clause is needed or wanted.\n- A condition earns its own exception class only when it carries something a named constructor cannot: extra state with accessors, an external interface contract, or a condition a consumer can act on. Everything else is a named constructor on the component's SPL-shaped class.\n\n### Background\n\n**Two spellings of one condition inside this package.** `Container/ConnectionInterfaceFactory.php:32` says `Connection configuration must be an array of parameters passed via $options[\"connection\"]`; `Container/PdoConnectionInterfaceFactory.php:44` says `Connection configuration must be an array of parameters` — the same guard, one message truncated.\n\n**Driver error text passed through verbatim** at `Connection.php:170` (`pg_last_error($this->resource)`) and `Statement.php:88` (`pg_last_error()`). Core added a `DRIVER_ERROR` template of `'%s'` for this shape.\n\n**Two ways of naming the same method in adjacent guards.** `Connection.php:107` prefixes `self::class . '::connect: '`; `:120` uses `sprintf('%s: …', __METHOD__)`. `:128` also interpolates `$this->connectionParameters['charset']`.\n\n**One message concatenated inside a `match` arm** at `Connection.php:293`: `'Connection parameter \"' . $name . '\" is not valid for Pgsql adapter'`.\n\n### The same conditions are worded differently in every package\n\nThese are not adapter-specific messages. They are one condition reported four slightly different ways, which is what core#189 found inside core and what no adapter can see on its own.\n\n| Condition | core 0.6.x | phpdb-mysql | phpdb-pgsql | phpdb-sqlite |\n|---|---|---|---|---|\n| Result is not a query result | `NON_QUERY_RESULT` | identical text, `Result.php:156` | identical text, `Result.php:74` | — |\n| Rollback while disconnected | `DISCONNECTED_ROLLBACK` | same **plus a full stop**, `Connection.php:296` | identical, `Connection.php:235` | — |\n| Rollback without a transaction | `ROLLBACK_WITHOUT_TRANSACTION` | same **plus a full stop**, `Connection.php:300` | identical, `Connection.php:239` | — |\n| Statement already prepared | `ALREADY_PREPARED` | `has **already been** prepared`, `Statement.php:143` | — | — |\n| Extension not loaded | `MISSING_PDO_EXTENSION`, says **adapter** | says **adapter**, `Driver.php:55` | says **Driver**, `Driver.php:54` | — |\n| No DSN | `MISSING_DSN` | — | `A dsn was not provided or could not be constructed from your parameters` | `A dsn was not provided` |\n| Connection config not an array | — | same string ×2 | same string once, truncated variant once | same string once |\n| Connect failed | — | `\"Connect Error: {$e->getMessage()}\"` | `\"Connect Error: {$e->getMessage()}\"` | `'Connect Error: ' . $e->getMessage()` |\n| Driver's own error text | `DRIVER_ERROR = '%s'` | `$this->resource->error` ×2, `$statement->error` | `pg_last_error()` ×2 | — |\n\nNine conditions, roughly twenty-five throw sites, four packages.\n\n### Where a shared template should live\n\ncore#189 made every template a `final public const string`, which is what lets an adapter stop hard-coding literals. Three cases follow from that:\n\n- **Core already names the condition** — reuse core's constant rather than redeclaring the string. The rollback, extension, prepared, query-result and driver-error templates all exist on `PhpDb\\Adapter\\Exception\\RuntimeException`.\n- **Shared between adapters, absent from core** — the connection-configuration and connect-failure messages. These want one home. The proposal is to add them to core as adapter-facing templates; the alternative is three copies that drift again.\n- **Genuinely adapter-specific** — stays in the adapter. An adapter-specific message does not belong in a core constant, which is the line core drew when it left `InvalidConnectionParametersException` with a plain constructor.\n\nWhere wording has drifted, core's is canonical, because every adapter already depends on it.\n\n### Considerations\n\n- **This depends on core 0.6.0.** The convention, the guards and the public constants are merged on `0.6.x` but unreleased; the current tag is 0.5.0. Nothing here can be built until it ships.\n- **No adapter-owned `ExceptionInterface`.** Core removed the five component interfaces in core#190. `Pgsql\\Exception\\RuntimeException` extending `PhpDb\\Adapter\\Exception\\RuntimeException` implements the single marker by inheritance, so the class body carries no `implements`.\n- **`too-many-methods` has a threshold of 10**, verified against mago 1.50.0, so a message catalogue trips it by construction. Core excludes the paths in its own `mago.toml` rather than baselining:\n  `too-many-methods = {{ exclude = [\"test/\", \"src/Pgsql/Exception/\"] }}`\n- **`#[CoversMethod]` restricts coverage attribution.** Once a test class declares any, PHPUnit records coverage only for the listed methods, so a PR touching an undeclared method fails `codecov/patch` with passing tests. This failed core#194 on a method four existing tests already exercised.\n- **Call factories in the test body, not the data provider.** A provider runs outside the coverage-collected region, so factories called there record no coverage at all while every assertion still passes.\n- **Verify each template against the original literal** rather than by eye. Core did this with a throwaway script before touching any call site, and it caught wording drift that reading would not.\n- **core#194 removed `VunerablePlatformQuoteException`.** `test/integration/AdapterPlatformTest.php` names it at lines 7, 24 and 35. Those move to `PhpDb\\Adapter\\Exception\\RuntimeException`, which the class already extended, so a `catch` of that type is unaffected. This must follow core 0.6.0 shipping, and is worth its own small PR ahead of the rest.\n\n### Proposal(s)\n\n- [ ] **PR 1: update the `VunerablePlatformQuoteException` references** in `test/integration/AdapterPlatformTest.php` once core 0.6.0 ships. Unblocks CI; independent of everything below.\n- [ ] **PR 2: add `PhpDb\\Pgsql\\Exception`.** `RuntimeException` and `InvalidArgumentException` extending core's, plus the `mago.toml` exclude. No throw sites change.\n- [ ] **PR 3: `Connection.php`, 9 sites.** Includes the two `pg_last_error()` passthroughs reusing core's `DRIVER_ERROR`, settling one way of naming the method in the connect guards, and the `match`-arm concatenation.\n- [ ] **PR 4: `Pdo/Connection.php`, `Driver.php`, `Result.php`, `Statement.php`, 5 sites.** Reuse core's templates for the query-result and extension messages, converging `required for this Driver` on core's `adapter` wording.\n- [ ] **PR 5: `Container/*`, 2 sites.** Collapse the two connection-configuration spellings onto one template, per whatever phpdb-sqlite#41 settles.\n\nTest plan, per PR: every named constructor gets a test asserting the returned type and the rendered message, driven by a `#[DataProvider]` per exception class; existing message assertions move from literals onto the templates; each PR runs `mago format --check`, `mago lint` and `mago analyze`, and regenerates the baselines it moves.\n\n### Appendix/Additional Info\n\n- core#189 is the originating RFC. core#190 carries the convention doc, the single marker interface and the structural guards. core#194 covers the `Adapter` component this package builds on.\n- Sibling RFCs: php-db/phpdb-mysql#82 and php-db/phpdb-sqlite#41. All three follow the same structure and defer the shared-template question to phpdb-sqlite.\n- Counts and line references are from `0.1.x` at the time of filing.\n","author":{"url":"https://github.com/simon-mundy","@type":"Person","name":"simon-mundy"},"datePublished":"2026-09-28T23:33:44Z","url":"https://github.com/php-db/phpdb-pgsql/issues/15"}

react-profiling0
react-import-mapreact,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322
route-pattern/_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format)
route-controllervoltron_issues_fragments
route-actionissue_layout
fetch-noncev2:d9f42c88-c273-f3b6-a104-450279749a14
current-catalog-service-hash81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114
request-idD908:47F34:330412:49217F:6AFD6795
html-safe-nonceaafb38f787b5e52b8217c0357b816e79602a802577cf9c24fef11960ce8a22e2
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEOTA4OjQ3RjM0OjMzMDQxMjo0OTIxN0Y6NkFGRDY3OTUiLCJ2aXNpdG9yX2lkIjoiNjA3MjIyMDExNzcyNTE3Nzc0OSIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9
visitor-hmac4f6664d5abc02eaafdf365ea1a4b51b65e30f1f74b7019a060a6aa23ede515b2
hovercard-subject-tagissue:5622710308
github-keyboard-shortcutsrepository,issues,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///voltron/issues_fragments/issue_layout
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/php-db/phpdb-pgsql/15/issue_layout
twitter:imagehttps://opengraph.githubassets.com/8e8e1da6871c1372377e39170a8aa8590de81b07ac48bee1bf1174f1fa6d0f1c/php-db/phpdb-pgsql/issues/15
twitter:cardsummary_large_image
og:imagehttps://opengraph.githubassets.com/8e8e1da6871c1372377e39170a8aa8590de81b07ac48bee1bf1174f1fa6d0f1c/php-db/phpdb-pgsql/issues/15
og:image:altProposed Version 0.1.0 Basic Information core#189 established a convention: no exception is constructed with a message assembled at the throw site. Every throw goes through a static named construct...
og:image:width1200
og:image:height600
og:site_nameGitHub
og:typeobject
og:author:usernamesimon-mundy
hostnamegithub.com
expected-hostnamegithub.com
None42a67d7c7488271ca8d7e6dc3942424e6de3bff43b1ed4a9c6f0e1a69b73b389
turbo-cache-controlno-preview
go-importgithub.com/php-db/phpdb-pgsql git https://github.com/php-db/phpdb-pgsql.git
octolytics-dimension-user_id219474457
octolytics-dimension-user_loginphp-db
octolytics-dimension-repository_id946781573
octolytics-dimension-repository_nwophp-db/phpdb-pgsql
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id946781573
octolytics-dimension-repository_network_root_nwophp-db/phpdb-pgsql
turbo-body-classeslogged-out env-production page-responsive
disable-turbofalse
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release5c3779ac05f3590d8d7ea0c02b14e678ae8179ae
ui-targetfull
theme-color#1e2327
color-schemelight dark
react-app-nameissues

Links:

Skip to contenthttps://github.com/php-db/phpdb-pgsql/issues/15#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fphp-db%2Fphpdb-pgsql%2Fissues%2F15
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fphp-db%2Fphpdb-pgsql%2Fissues%2F15
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fvoltron%2Fissues_fragments%2Fissue_layout&source=header-repo&source_repo=php-db%2Fphpdb-pgsql
Reloadhttps://github.com/php-db/phpdb-pgsql/issues/15
Reloadhttps://github.com/php-db/phpdb-pgsql/issues/15
Reloadhttps://github.com/php-db/phpdb-pgsql/issues/15
php-dbhttps://github.com/php-db
phpdb-pgsqlhttps://github.com/php-db/phpdb-pgsql
Codehttps://github.com/php-db/phpdb-pgsql
Issues2 (2)https://github.com/php-db/phpdb-pgsql/issues
Pull requests1 (1)https://github.com/php-db/phpdb-pgsql/pulls
Actionshttps://github.com/php-db/phpdb-pgsql/actions
Projectshttps://github.com/php-db/phpdb-pgsql/projects
Security and qualityhttps://github.com/php-db/phpdb-pgsql/security
Insightshttps://github.com/php-db/phpdb-pgsql/insights
https://github.com/php-db/phpdb-pgsql
New issuehttps://github.com/login?return_to=https://github.com/php-db/phpdb-pgsql/issues/15
New issuehttps://github.com/login?return_to=https://github.com/php-db/phpdb-pgsql/issues/15
Featurehttps://github.com/php-db/phpdb-pgsql/issues?q=type:"Feature"
[RFC]: Named exception constructors for the PostgreSQL adapterhttps://github.com/php-db/phpdb-pgsql/issues/15#top
https://github.com/simon-mundy
RFCRFC issue or PRhttps://github.com/php-db/phpdb-pgsql/issues?q=state%3Aopen%20label%3A%22RFC%22
https://github.com/simon-mundy
simon-mundyhttps://github.com/simon-mundy
on Sep 28, 2026https://github.com/php-db/phpdb-pgsql/issues/15#issue-5622710308
[RFC]: Named exception constructors for the MySQL adapter phpdb-mysql#82https://github.com/php-db/phpdb-mysql/issues/82
[RFC]: Named exception constructors, and where shared message templates should live phpdb-sqlite#41https://github.com/php-db/phpdb-sqlite/issues/41
simon-mundyhttps://github.com/simon-mundy
RFCRFC issue or PRhttps://github.com/php-db/phpdb-pgsql/issues?q=state%3Aopen%20label%3A%22RFC%22
on Sep 28, 2026https://github.com/php-db/phpdb-pgsql/issues/15#event-32036775714
simon-mundyhttps://github.com/simon-mundy
on Sep 28, 2026https://github.com/php-db/phpdb-pgsql/issues/15#event-32036890903
simon-mundyhttps://github.com/simon-mundy
Featurehttps://github.com/php-db/phpdb-pgsql/issues?q=type:"Feature"
on Sep 28, 2026https://github.com/php-db/phpdb-pgsql/issues/15#event-32036894339
simon-mundyhttps://github.com/simon-mundy
on Sep 29, 2026https://github.com/php-db/phpdb-pgsql/issues/15#event-32049723176
Sign up for freehttps://github.com/signup?return_to=https://github.com/php-db/phpdb-pgsql/issues/15
Sign in to commenthttps://github.com/login?return_to=https://github.com/php-db/phpdb-pgsql/issues/15
simon-mundyhttps://github.com/simon-mundy
RFCRFC issue or PRhttps://github.com/php-db/phpdb-pgsql/issues?q=state%3Aopen%20label%3A%22RFC%22
Featurehttps://github.com/php-db/phpdb-pgsql/issues?q=type:"Feature"
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.