René's URL Explorer Experiment


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

direct link

Domain: github.com


Hey, it has json ld scripts:
{"@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-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:6745a623-f25d-d622-8f7d-b4fc02969212
current-catalog-service-hash81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114
request-idDDD2:9A536:2AD14CB:3C1659F:6AFD65A1
html-safe-nonce446bec8ad1c827b09c6c0539f9c323cd1c98e49262345c51bef15ed47b9d0fdc
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEREQyOjlBNTM2OjJBRDE0Q0I6M0MxNjU5Rjo2QUZENjVBMSIsInZpc2l0b3JfaWQiOiIyNDc3Mzk4NTcyMzE1MDQ4MDEiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ==
visitor-hmac0d58bbd3812770d95e66a02b9a1cd2269981d060fa72da7e8163d4d60b21263b
hovercard-subject-tagissue:5622710530
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-sqlite/41/issue_layout
twitter:imagehttps://opengraph.githubassets.com/19295d12a5359001edf33bcc70867aa2a9fcf04bfd3c5f097bbcfde80fce0599/php-db/phpdb-sqlite/issues/41
twitter:cardsummary_large_image
og:imagehttps://opengraph.githubassets.com/19295d12a5359001edf33bcc70867aa2a9fcf04bfd3c5f097bbcfde80fce0599/php-db/phpdb-sqlite/issues/41
og:image:altProposed 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: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-sqlite git https://github.com/php-db/phpdb-sqlite.git
octolytics-dimension-user_id219474457
octolytics-dimension-user_loginphp-db
octolytics-dimension-repository_id946916064
octolytics-dimension-repository_nwophp-db/phpdb-sqlite
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id946916064
octolytics-dimension-repository_network_root_nwophp-db/phpdb-sqlite
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-sqlite/issues/41#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fphp-db%2Fphpdb-sqlite%2Fissues%2F41
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-sqlite%2Fissues%2F41
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-sqlite
Reloadhttps://github.com/php-db/phpdb-sqlite/issues/41
Reloadhttps://github.com/php-db/phpdb-sqlite/issues/41
Reloadhttps://github.com/php-db/phpdb-sqlite/issues/41
php-dbhttps://github.com/php-db
phpdb-sqlitehttps://github.com/php-db/phpdb-sqlite
Codehttps://github.com/php-db/phpdb-sqlite
Issues2 (2)https://github.com/php-db/phpdb-sqlite/issues
Pull requests2 (2)https://github.com/php-db/phpdb-sqlite/pulls
Actionshttps://github.com/php-db/phpdb-sqlite/actions
Projectshttps://github.com/php-db/phpdb-sqlite/projects
Security and qualityhttps://github.com/php-db/phpdb-sqlite/security
Insightshttps://github.com/php-db/phpdb-sqlite/insights
https://github.com/php-db/phpdb-sqlite
New issuehttps://github.com/login?return_to=https://github.com/php-db/phpdb-sqlite/issues/41
New issuehttps://github.com/login?return_to=https://github.com/php-db/phpdb-sqlite/issues/41
Featurehttps://github.com/php-db/phpdb-sqlite/issues?q=type:"Feature"
[RFC]: Named exception constructors, and where shared message templates should livehttps://github.com/php-db/phpdb-sqlite/issues/41#top
https://github.com/simon-mundy
RFCRFC issue or PRhttps://github.com/php-db/phpdb-sqlite/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-sqlite/issues/41#issue-5622710530
[RFC]: Named exception constructors for the MySQL adapter phpdb-mysql#82https://github.com/php-db/phpdb-mysql/issues/82
[RFC]: Named exception constructors for the PostgreSQL adapter phpdb-pgsql#15https://github.com/php-db/phpdb-pgsql/issues/15
simon-mundyhttps://github.com/simon-mundy
RFCRFC issue or PRhttps://github.com/php-db/phpdb-sqlite/issues?q=state%3Aopen%20label%3A%22RFC%22
on Sep 28, 2026https://github.com/php-db/phpdb-sqlite/issues/41#event-32036776897
simon-mundyhttps://github.com/simon-mundy
on Sep 28, 2026https://github.com/php-db/phpdb-sqlite/issues/41#event-32037054835
simon-mundyhttps://github.com/simon-mundy
Featurehttps://github.com/php-db/phpdb-sqlite/issues?q=type:"Feature"
on Sep 28, 2026https://github.com/php-db/phpdb-sqlite/issues/41#event-32037057607
Sign up for freehttps://github.com/signup?return_to=https://github.com/php-db/phpdb-sqlite/issues/41
Sign in to commenthttps://github.com/login?return_to=https://github.com/php-db/phpdb-sqlite/issues/41
simon-mundyhttps://github.com/simon-mundy
RFCRFC issue or PRhttps://github.com/php-db/phpdb-sqlite/issues?q=state%3Aopen%20label%3A%22RFC%22
Featurehttps://github.com/php-db/phpdb-sqlite/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.