Title: [RFC]: Named exception constructors, and where shared message templates should live · Issue #41 · php-db/phpdb-sqlite · GitHub
Open Graph Title: [RFC]: Named exception constructors, and where shared message templates should live · Issue #41 · php-db/phpdb-sqlite
X Title: [RFC]: Named exception constructors, and where shared message templates should live · Issue #41 · php-db/phpdb-sqlite
Description: Proposed Version 0.3.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.3.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.3.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-sqlite/issues/41
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[RFC]: Named exception constructors, and where shared message templates should live","articleBody":"### Proposed Version\n\n0.3.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 is the smallest case by far — **3 throw sites and no `Exception` namespace** — and it is mostly a reuse exercise rather than a refactor, because all three of its messages are already said elsewhere:\n\n| Site | Message | Also in |\n|---|---|---|\n| `Container/PdoConnectionFactory.php:23` | `Connection configuration must be an array of parameters passed via $options[\"connection\"]` | phpdb-mysql ×2, phpdb-pgsql ×1 |\n| `Pdo/Connection.php:73` | `A dsn was not provided` | a longer variant in phpdb-pgsql, a different one in core |\n| `Pdo/Connection.php:111` | `'Connect Error: ' . $e->getMessage()` | phpdb-mysql and phpdb-pgsql, both interpolated rather than concatenated |\n\nSo the question this RFC mainly asks is not how to restructure this package, but **where the shared templates should live** so three adapters stop each keeping their own copy. The sibling RFCs both defer that decision here.\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\nAll three sites are covered by the table above; there is no package-local duplication to report beyond it. Thrown types: `InvalidConnectionParametersException` 1, `Exception\\InvalidConnectionParametersException` 1, `Exception\\RuntimeException` 1.\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. `Sqlite\\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/Sqlite/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/unit/AdapterPlatformTest.php` names it at lines 9, 155 and 164. 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- **Three sites may not justify a namespace.** With every message shared, it is worth deciding whether this package needs `PhpDb\\Sqlite\\Exception` at all or should simply consume shared templates. Adding a namespace holding nothing adapter-specific would be structure for its own sake. Decide here, then apply consistently to the siblings.\n- **`too-many-methods` would not be reached here**, so unlike the siblings no `mago.toml` change is expected.\n\n### Proposal(s)\n\n- [ ] **PR 1: update the `VunerablePlatformQuoteException` references** in `test/unit/AdapterPlatformTest.php` once core 0.6.0 ships. Unblocks CI; independent of everything below.\n- [ ] **PR 2: settle where the three shared templates live**, in discussion here rather than in code. The options are core as adapter-facing templates, one template per adapter, or a shared namespace. Both sibling RFCs defer to this.\n- [ ] **PR 3: convert the 3 throw sites** to whatever PR 2 decides, converging `A dsn was not provided` and the `Connect Error` concatenation on the agreed wording.\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-pgsql#15. All three follow the same structure and defer the shared-template question to phpdb-sqlite.\n- Counts and line references are from `0.3.x` at the time of filing.\n","author":{"url":"https://github.com/simon-mundy","@type":"Person","name":"simon-mundy"},"datePublished":"2026-09-28T23:33:46Z","url":"https://github.com/php-db/phpdb-sqlite/issues/41"}
| 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:6745a623-f25d-d622-8f7d-b4fc02969212 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | DDD2:9A536:2AD14CB:3C1659F:6AFD65A1 |
| html-safe-nonce | 446bec8ad1c827b09c6c0539f9c323cd1c98e49262345c51bef15ed47b9d0fdc |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEREQyOjlBNTM2OjJBRDE0Q0I6M0MxNjU5Rjo2QUZENjVBMSIsInZpc2l0b3JfaWQiOiIyNDc3Mzk4NTcyMzE1MDQ4MDEiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 0d58bbd3812770d95e66a02b9a1cd2269981d060fa72da7e8163d4d60b21263b |
| hovercard-subject-tag | issue:5622710530 |
| 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-sqlite/41/issue_layout |
| twitter:image | https://opengraph.githubassets.com/19295d12a5359001edf33bcc70867aa2a9fcf04bfd3c5f097bbcfde80fce0599/php-db/phpdb-sqlite/issues/41 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/19295d12a5359001edf33bcc70867aa2a9fcf04bfd3c5f097bbcfde80fce0599/php-db/phpdb-sqlite/issues/41 |
| og:image:alt | Proposed Version 0.3.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-sqlite git https://github.com/php-db/phpdb-sqlite.git |
| octolytics-dimension-user_id | 219474457 |
| octolytics-dimension-user_login | php-db |
| octolytics-dimension-repository_id | 946916064 |
| octolytics-dimension-repository_nwo | php-db/phpdb-sqlite |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 946916064 |
| octolytics-dimension-repository_network_root_nwo | php-db/phpdb-sqlite |
| 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