Skip to content

Clear Mago findings in the Sql platform layer - #252

Open
simon-mundy wants to merge 1 commit into
php-db:0.6.xfrom
simon-mundy:qa/mago-sql-platform
Open

simon-mundy wants to merge 1 commit into
php-db:0.6.xfrom
simon-mundy:qa/mago-sql-platform

Conversation

@simon-mundy

Copy link
Copy Markdown
Member

Problem

Sql\Platform\Platform and AbstractPlatform call getSqlString() and prepareStatement() on whatever getTypeDecorator() returns. That method's return type is PlatformDecoratorInterface|PreparableSqlInterface|SqlInterface. PlatformDecoratorInterface declares neither method, and each Sql interface lacks the other's, so Mago reports non-existent-method. At runtime, a decorator registered for a type it cannot render ends in a fatal "Call to undefined method" error.

There are related gaps in the same layer:

  • AbstractPlatform::$subject is non-nullable with no default, although setSubject() accepts null.
  • The decorator map is untyped, and Platform stores a nested map in it.
  • Platform::getDecorators() reads an undefined key when no decorators are registered for the default platform.
  • PlatformDecoratorInterface has no @api tag.

Fix

  • Decorator calls are checked first. Before each call, the resolved decorator is checked with instanceof, through one final protected helper on AbstractPlatform that Platform reuses. If the decorator doesn't implement the needed interface, the helper throws a new named exception, Sql\Exception\RuntimeException::forDecoratorNotImplementing(). PlatformDecoratorInterface is unchanged, so third-party decorators keep working.
  • AbstractPlatform::$subject is now SqlInterface|PreparableSqlInterface|null = null, matching setSubject().
  • The decorator map has a documented type, and Platform reads it through one private accessor that defaults to [].
  • PlatformDecoratorInterface is tagged @api.
  • AbstractSql has six findings that cannot be fixed without changing signatures subclasses depend on. They are now recorded inline with @mago-expect and a reason, following the existing pattern in FeatureSet and AbstractSource:
    • process{Name}() is dispatched by a name built at runtime;
    • the subject's state is copied onto the decorator;
    • the class size;
    • the protected processExpressionOrSelect() signature.
  • Baselines: the fixed entries are removed. The analyzer baseline goes from 284 to 266 issues, and the lint baseline from 153 to 150.

What stays the same

  • PlatformDecoratorInterface and all public and protected method signatures.
  • The order in which decorators are resolved: exact class match first, then an instanceof match.
  • The SQL produced by every existing decorator.
  • Platform stays non-final, and its class-must-be-final finding stays baselined.

Behaviour changes (fail-closed)

  • A decorator that lacks the needed interface now throws Sql\Exception\RuntimeException, instead of a fatal error.
  • Using a null or never-set subject now throws the existing "subject does not implement" RuntimeException, instead of a TypeError.
  • Platform::getDecorators() returns [] when no decorators are registered, instead of a warning followed by a TypeError.

BC note: a subclass that redeclares $subject with the old non-nullable type would need to widen it. None of the first-party driver packages do.

Verification

  • mago format --check, lint, analyze and guard exit 0 on PHP 8.3, 8.4 and 8.5, with no stale baseline entries.
  • The full PHPUnit suite passes.
  • Every changed src line is covered.
  • Infection finds no escaped mutants on changed lines.
  • New tests cover:
    • both decorator-mismatch paths, on both platform classes;
    • a cleared subject;
    • getDecorators() with nothing registered;
    • setTypeDecorator() keeping existing entries.

Platform and AbstractPlatform called getSqlString() and prepareStatement()
on whatever getTypeDecorator() returned, typed as
PlatformDecoratorInterface|PreparableSqlInterface|SqlInterface. Neither
PlatformDecoratorInterface nor the opposite Sql interface declares those
methods, so a decorator registered for a type it does not render ended in
an "undefined method" Error. The result is now narrowed with instanceof at
the call site and a named RuntimeException (forDecoratorNotImplementing)
is thrown instead. PlatformDecoratorInterface itself is unchanged, so
third-party decorators are not affected.

AbstractPlatform::$subject is now nullable with a null default, matching
PlatformDecoratorInterface::setSubject(), which accepts null. Using a
cleared or never-set subject now raises the existing "subject does not
implement" RuntimeException instead of a TypeError or an uninitialised
property Error.

Platform::getDecorators() returns an empty list when nothing is
registered for the default platform, instead of an undefined-key warning
followed by a TypeError. The decorator map is documented, and Platform
reads it through one private accessor.

PlatformDecoratorInterface is marked @api. AbstractSql's runtime
process{Name}() dispatch, subject state copy, class size and protected
processExpressionOrSelect() signature are recorded as @mago-expect,
since changing them would break subclasses.
@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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant