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
Domain: github.com
{"@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-profiling | 0 |
| react-import-map | react,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-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:d9f42c88-c273-f3b6-a104-450279749a14 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | D908:47F34:330412:49217F:6AFD6795 |
| html-safe-nonce | aafb38f787b5e52b8217c0357b816e79602a802577cf9c24fef11960ce8a22e2 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEOTA4OjQ3RjM0OjMzMDQxMjo0OTIxN0Y6NkFGRDY3OTUiLCJ2aXNpdG9yX2lkIjoiNjA3MjIyMDExNzcyNTE3Nzc0OSIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 4f6664d5abc02eaafdf365ea1a4b51b65e30f1f74b7019a060a6aa23ede515b2 |
| hovercard-subject-tag | issue:5622710308 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/php-db/phpdb-pgsql/15/issue_layout |
| twitter:image | https://opengraph.githubassets.com/8e8e1da6871c1372377e39170a8aa8590de81b07ac48bee1bf1174f1fa6d0f1c/php-db/phpdb-pgsql/issues/15 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/8e8e1da6871c1372377e39170a8aa8590de81b07ac48bee1bf1174f1fa6d0f1c/php-db/phpdb-pgsql/issues/15 |
| og:image:alt | 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... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | simon-mundy |
| hostname | github.com |
| expected-hostname | github.com |
| None | 42a67d7c7488271ca8d7e6dc3942424e6de3bff43b1ed4a9c6f0e1a69b73b389 |
| turbo-cache-control | no-preview |
| go-import | github.com/php-db/phpdb-pgsql git https://github.com/php-db/phpdb-pgsql.git |
| octolytics-dimension-user_id | 219474457 |
| octolytics-dimension-user_login | php-db |
| octolytics-dimension-repository_id | 946781573 |
| octolytics-dimension-repository_nwo | php-db/phpdb-pgsql |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 946781573 |
| octolytics-dimension-repository_network_root_nwo | php-db/phpdb-pgsql |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 5c3779ac05f3590d8d7ea0c02b14e678ae8179ae |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width