Skip to content

Make public constants final and type NAMED_ADAPTER_KEY - #251

Merged
simon-mundy merged 3 commits into
php-db:0.6.xfrom
simon-mundy:qa/final-typed-constants
Nov 17, 2026
Merged

simon-mundy merged 3 commits into
php-db:0.6.xfrom
simon-mundy:qa/final-typed-constants

Conversation

@simon-mundy

Copy link
Copy Markdown
Member

Problem

An audit of every class constant on 0.6.x, done with PHP reflection over all classes, interfaces, traits and enums in src/ and test/, found two gaps in src/:

  • Typing: 264 of 265 constants are typed. ConfigProvider::NAMED_ADAPTER_KEY is the only one that isn't.
  • final: 45 public or protected constants are not final. Since PHP 8.1 a class that implements an interface can override the interface's constants unless they are final, and a subclass can override a parent's.

Fix

Type ConfigProvider::NAMED_ADAPTER_KEY as string. This also removes its missing-constant-type entry from the analyzer baseline.

Make 38 constants final. Nothing in phpdb, phpdb-mysql, phpdb-sqlite or phpdb-pgsql redeclares them. The drivers only read them, e.g. AdapterInterface::QUERY_MODE_EXECUTE and ParameterContainer::TYPE_*.

Type Constants
Adapter\AdapterInterface QUERY_MODE_*, PREPARE_TYPE_*, FUNCTION_*, VALUE_QUOTE_SEPARATOR (8)
Adapter\Driver\DriverInterface PARAMETERIZATION_* (2)
Adapter\Driver\Pdo\Result STATEMENT_MODE_*, VALID_FETCH_MODES (3)
Adapter\ParameterContainer TYPE_* (7)
Metadata\Source\AbstractSource DEFAULT_SCHEMA, a sentinel the drivers read through self:: (1)
ResultSet\ResultSet TYPE_ARRAYOBJECT, TYPE_ARRAY (2)
Sql\SqlInterface TYPE_IDENTIFIER, TYPE_VALUE, TYPE_LITERAL, TYPE_SELECT (4)
TableGateway\Feature\EventFeatureEventsInterface EVENT_* (10)
TableGateway\Feature\FeatureSet APPLY_HALT (1)

Left overridable on purpose

  • Insert::SPECIFICATION_INSERT, Update::SPECIFICATION_UPDATE and Delete::SPECIFICATION_DELETE: overriding these is how a subclass makes an INSERT IGNORE / REPLACE / UPDATE IGNORE / DELETE IGNORE statement, as the Replace, UpdateIgnore and DeleteIgnore test assets do.
  • AbstractResultSet::HOLDS_MAPPED_ROWS and HydratingResultSet::HOLDS_MAPPED_ROWS: HydratingResultSet overrides the parent's value.
  • ConfigProvider::NAMED_ADAPTER_KEY and TableIdentifier::SEPARATOR: both classes are final, so their constants cannot be overridden anyway.
  • The 9 private constants: PHP does not allow a private constant to be final.

BC

Third-party code that redeclares one of the 38 constants in a subclass or an interface implementation will now fail with a fatal error. Nothing in phpdb or the three driver packages does, and the constants are enum-like values that should not be redefined. Worth a line in the release notes.

Verification

  • mago format --check, mago lint, mago analyze and mago guard exit 0 on PHP 8.3, 8.4 and 8.5. The analyzer baseline no longer has a stale entry.
  • The full PHPUnit suite passes. Loading any class that redeclared a now-final constant would fail with a fatal error, and none does.
  • No behaviour changes; only constant declarations change.

Mark the 38 public constants that nothing in phpdb or the driver
packages redeclares as final, so implementers and subclasses cannot
override them. Since PHP 8.1 an implementing class can override an
interface constant unless it is final.

The SPECIFICATION_* constants on Insert, Update and Delete and
HOLDS_MAPPED_ROWS stay overridable, since subclasses override them by
design. ConfigProvider::NAMED_ADAPTER_KEY gains its missing string type,
which clears its analyzer baseline entry.
@codecov

codecov Bot commented Nov 17, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@simon-mundy simon-mundy self-assigned this Nov 17, 2026
@simon-mundy simon-mundy added enhancement New feature or request qa Improvements in quality assurance of the project Lang Feature Refactor Refactoring to new language features labels Nov 17, 2026
@github-project-automation github-project-automation Bot moved this to Todo in @phpdb Nov 17, 2026
@simon-mundy simon-mundy added this to the 0.6.0 milestone Nov 17, 2026
@github-project-automation github-project-automation Bot moved this from Todo to In Progress in @phpdb Nov 17, 2026
@simon-mundy
simon-mundy requested a review from tyrsson November 17, 2026 06:03
@simon-mundy
simon-mundy merged commit faafc17 into php-db:0.6.x Nov 17, 2026
29 checks passed
@github-project-automation github-project-automation Bot moved this from In Progress to Done in @phpdb Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request Lang Feature Refactor Refactoring to new language features qa Improvements in quality assurance of the project

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants