diff --git a/analyzer-baseline.toml b/analyzer-baseline.toml index 6525bc725..962d7cb63 100644 --- a/analyzer-baseline.toml +++ b/analyzer-baseline.toml @@ -648,24 +648,6 @@ code = "missing-api-or-internal" message = 'Interface `PhpDb\RowGateway\RowGatewayInterface` is missing an `@api` or `@internal` annotation.' count = 1 -[[issues]] -file = "src/Sql/AbstractSql.php" -code = "mixed-assignment" -message = "Assigning `mixed` type to a variable may lead to unexpected behavior." -count = 1 - -[[issues]] -file = "src/Sql/AbstractSql.php" -code = "string-member-selector" -message = "This member selector uses a non-literal string type (`non-empty-string`); its specific value cannot be statically determined." -count = 1 - -[[issues]] -file = "src/Sql/AbstractSql.php" -code = "string-member-selector" -message = "This member selector uses a non-literal string type (`string`); its specific value cannot be statically determined." -count = 1 - [[issues]] file = "src/Sql/Insert.php" code = "missing-return-type" @@ -678,102 +660,12 @@ code = "missing-return-type" message = "Function `__unset` is missing a return type hint." count = 1 -[[issues]] -file = "src/Sql/Platform/AbstractPlatform.php" -code = "imprecise-type" -message = "Type `array` in property `$decorators` is imprecise, equivalent to `array`." -count = 1 - -[[issues]] -file = "src/Sql/Platform/AbstractPlatform.php" -code = "invalid-property-assignment-value" -message = 'Invalid type for property `$subject`: expected `PhpDb\Sql\PreparableSqlInterface|PhpDb\Sql\SqlInterface`, but got `PhpDb\Sql\PreparableSqlInterface|PhpDb\Sql\SqlInterface|null`.' -count = 1 - -[[issues]] -file = "src/Sql/Platform/AbstractPlatform.php" -code = "missing-constructor" -message = 'Class `PhpDb\Sql\Platform\AbstractPlatform` has typed properties without default values but no constructor to initialize them.' -count = 1 - -[[issues]] -file = "src/Sql/Platform/AbstractPlatform.php" -code = "non-existent-method" -message = 'Method `getSqlString` does not exist on type `PhpDb\Sql\Platform\PlatformDecoratorInterface`.' -count = 1 - -[[issues]] -file = "src/Sql/Platform/AbstractPlatform.php" -code = "non-existent-method" -message = 'Method `getSqlString` does not exist on type `PhpDb\Sql\PreparableSqlInterface`.' -count = 1 - -[[issues]] -file = "src/Sql/Platform/AbstractPlatform.php" -code = "non-existent-method" -message = 'Method `prepareStatement` does not exist on type `PhpDb\Sql\Platform\PlatformDecoratorInterface`.' -count = 1 - -[[issues]] -file = "src/Sql/Platform/AbstractPlatform.php" -code = "non-existent-method" -message = 'Method `prepareStatement` does not exist on type `PhpDb\Sql\SqlInterface`.' -count = 1 - [[issues]] file = "src/Sql/Platform/Platform.php" code = "class-must-be-final" message = 'Class `PhpDb\Sql\Platform\Platform` should be declared `final`.' count = 1 -[[issues]] -file = "src/Sql/Platform/Platform.php" -code = "mixed-array-assignment" -message = "Unsafe array assignment on type `mixed`." -count = 1 - -[[issues]] -file = "src/Sql/Platform/Platform.php" -code = "mixed-return-statement" -message = 'Could not infer a precise return type for function `PhpDb\Sql\Platform\Platform::getDecorators`. Saw type `mixed`.' -count = 1 - -[[issues]] -file = "src/Sql/Platform/Platform.php" -code = "non-existent-method" -message = 'Method `getSqlString` does not exist on type `PhpDb\Sql\Platform\PlatformDecoratorInterface`.' -count = 1 - -[[issues]] -file = "src/Sql/Platform/Platform.php" -code = "non-existent-method" -message = 'Method `getSqlString` does not exist on type `PhpDb\Sql\PreparableSqlInterface`.' -count = 1 - -[[issues]] -file = "src/Sql/Platform/Platform.php" -code = "non-existent-method" -message = 'Method `prepareStatement` does not exist on type `PhpDb\Sql\Platform\PlatformDecoratorInterface`.' -count = 1 - -[[issues]] -file = "src/Sql/Platform/Platform.php" -code = "non-existent-method" -message = 'Method `prepareStatement` does not exist on type `PhpDb\Sql\SqlInterface`.' -count = 1 - -[[issues]] -file = "src/Sql/Platform/Platform.php" -code = "possibly-undefined-string-array-index" -message = "Possibly undefined array key `string` accessed on `array`." -count = 1 - -[[issues]] -file = "src/Sql/Platform/PlatformDecoratorInterface.php" -code = "missing-api-or-internal" -message = 'Interface `PhpDb\Sql\Platform\PlatformDecoratorInterface` is missing an `@api` or `@internal` annotation.' -count = 1 - [[issues]] file = "src/Sql/Select.php" code = "missing-return-type" diff --git a/lint-baseline.toml b/lint-baseline.toml index 19faa6c46..33901c7e3 100644 --- a/lint-baseline.toml +++ b/lint-baseline.toml @@ -120,24 +120,6 @@ code = "no-negated-ternary" message = "Negated ternary condition." count = 1 -[[issues]] -file = "src/Sql/AbstractSql.php" -code = "cyclomatic-complexity" -message = "Class has high complexity." -count = 1 - -[[issues]] -file = "src/Sql/AbstractSql.php" -code = "excessive-parameter-list" -message = "Parameter list is too long." -count = 1 - -[[issues]] -file = "src/Sql/AbstractSql.php" -code = "kan-defect" -message = "Class has a high kan defect score." -count = 1 - [[issues]] file = "src/Sql/Combine.php" code = "cyclomatic-complexity" diff --git a/src/Sql/AbstractSql.php b/src/Sql/AbstractSql.php index c6e196f64..a392f00ff 100644 --- a/src/Sql/AbstractSql.php +++ b/src/Sql/AbstractSql.php @@ -50,6 +50,9 @@ * isIdentifier?: bool, * } * @psalm-import-type JoinSpecification from Join + * + * @mago-expect lint:kan-defect + * @mago-expect lint:cyclomatic-complexity */ abstract class AbstractSql implements SqlInterface { @@ -88,7 +91,11 @@ public function getSqlString(?PlatformInterface $adapterPlatform = null): string } /** + * Dispatches each specification to its process{Name}() hook, so the method name is built at runtime + * * @throws Exception\RuntimeException + * + * @mago-expect analysis:string-member-selector */ protected function buildSqlString( PlatformInterface $platform, @@ -200,6 +207,12 @@ protected function formatSpecification(string $name, string ...$values): string return str_replace($placeholders, $values, $specification); } + /** + * Copies the decorated subject's state onto this decorator, so property names are only known at runtime + * + * @mago-expect analysis:string-member-selector + * @mago-expect analysis:mixed-assignment + */ protected function localizeVariables(): void { if (! $this instanceof PlatformDecoratorInterface || null === $this->subject) { @@ -292,6 +305,8 @@ protected function processExpressionList(array $expressions, PlatformInterface $ /** * @throws Exception\RuntimeException + * + * @mago-expect lint:excessive-parameter-list */ protected function processExpressionOrSelect( ArgumentInterface $argument, diff --git a/src/Sql/Exception/RuntimeException.php b/src/Sql/Exception/RuntimeException.php index 846c73472..a9323c698 100644 --- a/src/Sql/Exception/RuntimeException.php +++ b/src/Sql/Exception/RuntimeException.php @@ -10,6 +10,10 @@ class RuntimeException extends Exception\RuntimeException { + final public const string DECORATOR_NOT_IMPLEMENTING = + 'The decorator %s does not implement %s,' + . ' thus %s cannot be delegated to it'; + final public const string REPLACEMENT_MISMATCH = 'The number of replacements in the expression' . ' does not match the number of parameters'; @@ -38,6 +42,11 @@ class RuntimeException extends Exception\RuntimeException '%s renders its expression string and does not accept' . ' a specification override; use setExpression() instead'; + public static function forDecoratorNotImplementing(string $decorator, string $interface, string $method): self + { + return new self(sprintf(self::DECORATOR_NOT_IMPLEMENTING, $decorator, $interface, $method)); + } + public static function forReplacementMismatch(): self { return new self(self::REPLACEMENT_MISMATCH); diff --git a/src/Sql/Platform/AbstractPlatform.php b/src/Sql/Platform/AbstractPlatform.php index ac1c69baf..af6e1d7e2 100644 --- a/src/Sql/Platform/AbstractPlatform.php +++ b/src/Sql/Platform/AbstractPlatform.php @@ -14,15 +14,21 @@ class AbstractPlatform implements PlatformDecoratorInterface, PreparableSqlInterface, SqlInterface { - protected SqlInterface|PreparableSqlInterface $subject; + protected SqlInterface|PreparableSqlInterface|null $subject = null; + /** + * Decorators keyed by the subject type they decorate; Platform nests them under a platform name first + * + * @var array> + */ protected array $decorators = []; /** - * @return array|PlatformDecoratorInterface[] + * @return array */ public function getDecorators(): array { + /** @var array */ return $this->decorators; } @@ -38,14 +44,19 @@ public function getSqlString(?PlatformInterface $adapterPlatform = null): string throw Exception\RuntimeException::forSubjectNotImplementing(SqlInterface::class, 'getSqlString()'); } - return $this->getTypeDecorator($this->subject)->getSqlString($adapterPlatform); + return $this->requireDecoratorImplementing( + $this->getTypeDecorator($this->subject), + SqlInterface::class, + 'getSqlString()', + )->getSqlString($adapterPlatform); } public function getTypeDecorator( PreparableSqlInterface|SqlInterface $subject, ): PlatformDecoratorInterface|PreparableSqlInterface|SqlInterface { - /** @var PlatformDecoratorInterface $decorator */ - foreach ($this->decorators as $type => $decorator) { + /** @var array $decorators */ + $decorators = $this->decorators; + foreach ($decorators as $type => $decorator) { /** @phpstan-ignore-next-line instanceof with string class name is valid */ if (! $subject instanceof $type) { continue; @@ -73,7 +84,11 @@ public function prepareStatement( ); } - $this->getTypeDecorator($this->subject)->prepareStatement($adapter, $statementContainer); + $this->requireDecoratorImplementing( + $this->getTypeDecorator($this->subject), + PreparableSqlInterface::class, + 'prepareStatement()', + )->prepareStatement($adapter, $statementContainer); return $statementContainer; } @@ -93,4 +108,24 @@ public function setTypeDecorator(string $type, PlatformDecoratorInterface $decor { $this->decorators[$type] = $decorator; } + + /** + * Narrows the resolved decorator to the interface whose method is about to be delegated to it + * + * @template T of PreparableSqlInterface|SqlInterface + * @param class-string $interface + * @return T + * @throws Exception\RuntimeException + */ + final protected function requireDecoratorImplementing( + PlatformDecoratorInterface|PreparableSqlInterface|SqlInterface $decorator, + string $interface, + string $method, + ): PreparableSqlInterface|SqlInterface { + if (! $decorator instanceof $interface) { + throw Exception\RuntimeException::forDecoratorNotImplementing($decorator::class, $interface, $method); + } + + return $decorator; + } } diff --git a/src/Sql/Platform/Platform.php b/src/Sql/Platform/Platform.php index b36ce0037..245a566e3 100644 --- a/src/Sql/Platform/Platform.php +++ b/src/Sql/Platform/Platform.php @@ -45,12 +45,13 @@ public function __construct(PlatformInterface $platform) $this->defaultPlatform = $platform; } + /** + * @return array + */ #[Override] public function getDecorators(): array { - $platformName = $this->resolvePlatformName($this->getDefaultPlatform()); - - return $this->decorators[$platformName]; + return $this->decoratorsFor($this->resolvePlatformName($this->getDefaultPlatform())); } /** @@ -61,13 +62,18 @@ public function getDecorators(): array #[Override] public function getSqlString(?PlatformInterface $adapterPlatform = null): string { - if (! $this->subject instanceof SqlInterface) { + $subject = $this->subject; + if (! $subject instanceof SqlInterface) { throw Exception\RuntimeException::forSubjectNotImplementing(SqlInterface::class, 'getSqlString()'); } $adapterPlatform = $this->resolvePlatform($adapterPlatform); - return $this->getTypeDecorator($this->subject, $adapterPlatform)->getSqlString($adapterPlatform); + return $this->requireDecoratorImplementing( + $this->getTypeDecorator($subject, $adapterPlatform), + SqlInterface::class, + 'getSqlString()', + )->getSqlString($adapterPlatform); } #[Override] @@ -75,13 +81,8 @@ public function getTypeDecorator( PreparableSqlInterface|SqlInterface $subject, AdapterInterface|PlatformInterface|null $adapterOrPlatform = null, ): PlatformDecoratorInterface|PreparableSqlInterface|SqlInterface { - $platformName = $this->resolvePlatformName($adapterOrPlatform); - - /** @var array|null $decorators */ - $decorators = $this->decorators[$platformName] ?? null; - if (null === $decorators) { - return $subject; - } + /** @var array $decorators */ + $decorators = $this->decoratorsFor($this->resolvePlatformName($adapterOrPlatform)); $decorator = $decorators[$subject::class] ?? null; if (null !== $decorator) { @@ -118,7 +119,11 @@ public function prepareStatement( ); } - $this->getTypeDecorator($this->subject, $adapter)->prepareStatement($adapter, $statementContainer); + $this->requireDecoratorImplementing( + $this->getTypeDecorator($this->subject, $adapter), + PreparableSqlInterface::class, + 'prepareStatement()', + )->prepareStatement($adapter, $statementContainer); return $statementContainer; } @@ -129,8 +134,11 @@ public function setTypeDecorator( PlatformDecoratorInterface $decorator, AdapterInterface|PlatformInterface|null $adapterOrPlatform = null, ): void { - $platformName = $this->resolvePlatformName($adapterOrPlatform); - $this->decorators[$platformName][$type] = $decorator; + $platformName = $this->resolvePlatformName($adapterOrPlatform); + + $decorators = $this->decoratorsFor($platformName); + $decorators[$type] = $decorator; + $this->decorators[$platformName] = $decorators; } protected function getDefaultPlatform(): PlatformInterface @@ -169,4 +177,15 @@ protected function resolvePlatformName(PlatformInterface|AdapterInterface|null $ return $normalized; } + + /** + * The decorators registered for a platform, keyed by the subject type they decorate + * + * @return array + */ + private function decoratorsFor(string $platformName): array + { + /** @var array */ + return $this->decorators[$platformName] ?? []; + } } diff --git a/src/Sql/Platform/PlatformDecoratorInterface.php b/src/Sql/Platform/PlatformDecoratorInterface.php index 3aa2bd673..55bdb5218 100644 --- a/src/Sql/Platform/PlatformDecoratorInterface.php +++ b/src/Sql/Platform/PlatformDecoratorInterface.php @@ -7,6 +7,9 @@ use PhpDb\Sql\PreparableSqlInterface; use PhpDb\Sql\SqlInterface; +/** + * @api + */ interface PlatformDecoratorInterface { public function setSubject( diff --git a/test/unit/Sql/Exception/RuntimeExceptionTest.php b/test/unit/Sql/Exception/RuntimeExceptionTest.php index 88729babc..8ceddc577 100644 --- a/test/unit/Sql/Exception/RuntimeExceptionTest.php +++ b/test/unit/Sql/Exception/RuntimeExceptionTest.php @@ -7,6 +7,7 @@ use PhpDb\Exception\ExceptionInterface; use PhpDb\Sql\Exception\RuntimeException; use PhpDb\Sql\Expression; +use PhpDb\Sql\Select; use PhpDb\Sql\SqlInterface; use PHPUnit\Framework\Attributes\CoversMethod; use PHPUnit\Framework\Attributes\DataProvider; @@ -17,6 +18,7 @@ use function sprintf; #[Group('unit')] +#[CoversMethod(RuntimeException::class, 'forDecoratorNotImplementing')] #[CoversMethod(RuntimeException::class, 'forReplacementMismatch')] #[CoversMethod(RuntimeException::class, 'forStringSpecificationRequired')] #[CoversMethod(RuntimeException::class, 'forSubjectNotImplementing')] @@ -31,6 +33,11 @@ final class RuntimeExceptionTest extends TestCase public static function namedConstructorProvider(): array { return [ + 'decorator not implementing' => [ + 'forDecoratorNotImplementing', + [Select::class, SqlInterface::class, 'getSqlString()'], + RuntimeException::DECORATOR_NOT_IMPLEMENTING, + ], 'replacement mismatch' => [ 'forReplacementMismatch', [], diff --git a/test/unit/Sql/Platform/AbstractPlatformTest.php b/test/unit/Sql/Platform/AbstractPlatformTest.php index e58e08904..bd8de8e73 100644 --- a/test/unit/Sql/Platform/AbstractPlatformTest.php +++ b/test/unit/Sql/Platform/AbstractPlatformTest.php @@ -28,6 +28,7 @@ #[CoversMethod(AbstractPlatform::class, 'getDecorators')] #[CoversMethod(AbstractPlatform::class, 'prepareStatement')] #[CoversMethod(AbstractPlatform::class, 'getSqlString')] +#[CoversMethod(AbstractPlatform::class, 'requireDecoratorImplementing')] final class AbstractPlatformTest extends TestCase { private AbstractPlatform $platform; @@ -44,6 +45,23 @@ public function getSqlStringDelegatesToDecoratorSubject(): void static::assertStringContainsString('"foo"', $sql); } + #[Test] + public function getSqlStringThrowsWhenDecoratorIsNotSqlInterface(): void + { + $decorator = $this->createStub(PlatformDecoratorInterface::class); + $this->platform->setTypeDecorator(Select::class, $decorator); + $this->platform->setSubject(new Select('foo')); + + self::expectException(RuntimeException::class); + self::expectExceptionMessage(sprintf( + RuntimeException::DECORATOR_NOT_IMPLEMENTING, + $decorator::class, + SqlInterface::class, + 'getSqlString()', + )); + $this->platform->getSqlString(); + } + #[Test] public function getSqlStringThrowsWhenSubjectNotSqlInterface(): void { @@ -59,6 +77,21 @@ public function getSqlStringThrowsWhenSubjectNotSqlInterface(): void $this->platform->getSqlString(); } + #[Test] + public function getSqlStringThrowsWhenSubjectWasCleared(): void + { + $this->platform->setSubject(new Select('foo')); + $this->platform->setSubject(null); + + self::expectException(RuntimeException::class); + self::expectExceptionMessage(sprintf( + RuntimeException::SUBJECT_NOT_IMPLEMENTING, + SqlInterface::class, + 'getSqlString()', + )); + $this->platform->getSqlString(); + } + #[Test] public function getTypeDecoratorLoopMatchesByInstanceof(): void { @@ -110,6 +143,23 @@ public function prepareStatementDelegatesToDecoratorSubject(): void static::assertStringContainsString('SELECT', $statement->getSql()); } + #[Test] + public function prepareStatementThrowsWhenDecoratorIsNotPreparable(): void + { + $decorator = $this->createStub(PlatformDecoratorInterface::class); + $this->platform->setTypeDecorator(Select::class, $decorator); + $this->platform->setSubject(new Select('foo')); + + self::expectException(RuntimeException::class); + self::expectExceptionMessage(sprintf( + RuntimeException::DECORATOR_NOT_IMPLEMENTING, + $decorator::class, + PreparableSqlInterface::class, + 'prepareStatement()', + )); + $this->platform->prepareStatement($this->createStub(AdapterInterface::class), new StatementContainer()); + } + #[Test] public function prepareStatementThrowsWhenSubjectNotPreparable(): void { diff --git a/test/unit/Sql/Platform/PlatformTest.php b/test/unit/Sql/Platform/PlatformTest.php index fdae8706d..0f35e5d75 100644 --- a/test/unit/Sql/Platform/PlatformTest.php +++ b/test/unit/Sql/Platform/PlatformTest.php @@ -20,6 +20,7 @@ use PhpDb\Sql\SqlInterface; use PhpDbTest\TestAsset; use PHPUnit\Framework\Attributes\CoversMethod; +use PHPUnit\Framework\Attributes\Group; use PHPUnit\Framework\Attributes\IgnoreDeprecations; use PHPUnit\Framework\Attributes\RequiresPhp; use PHPUnit\Framework\Attributes\Test; @@ -28,6 +29,9 @@ use ReflectionException; use ReflectionMethod; +use function sprintf; + +#[Group('unit')] #[IgnoreDeprecations] #[RequiresPhp('<= 8.6')] #[CoversMethod(Platform::class, '__construct')] @@ -39,8 +43,23 @@ #[CoversMethod(Platform::class, 'resolvePlatformName')] #[CoversMethod(Platform::class, 'resolvePlatform')] #[CoversMethod(Platform::class, 'getDefaultPlatform')] +#[CoversMethod(Platform::class, 'decoratorsFor')] +#[CoversMethod(AbstractPlatform::class, 'requireDecoratorImplementing')] class PlatformTest extends TestCase { + #[Test] + public function getDecoratorsReturnsEmptyListWhenNoneRegisteredForDefaultPlatform(): void + { + $platform = new Platform(new TestAsset\TrustingSql92Platform()); + $platform->setTypeDecorator( + Select::class, + $this->createStub(PlatformDecoratorInterface::class), + new TestAsset\TrustingMysqlPlatform(), + ); + + static::assertSame([], $platform->getDecorators()); + } + #[Test] public function getDefaultPlatformReturnsInstance(): void { @@ -68,6 +87,26 @@ public function getSqlStringDelegatesToTypeDecorator(): void static::assertStringContainsString('"foo"', $sql); } + #[Test] + public function getSqlStringThrowsWhenDecoratorIsNotSqlInterface(): void + { + $adapterPlatform = new TestAsset\TrustingSql92Platform(); + $platform = new Platform($adapterPlatform); + + $decorator = $this->createStub(PlatformDecoratorInterface::class); + $platform->setTypeDecorator(Select::class, $decorator); + $platform->setSubject(new Select('foo')); + + self::expectException(RuntimeException::class); + self::expectExceptionMessage(sprintf( + RuntimeException::DECORATOR_NOT_IMPLEMENTING, + $decorator::class, + SqlInterface::class, + 'getSqlString()', + )); + $platform->getSqlString($adapterPlatform); + } + #[Test] public function getSqlStringThrowsWhenSubjectNotSqlInterface(): void { @@ -139,6 +178,25 @@ public function getTypeDecoratorReturnsSubjectWhenNoDecoratorRegistered(): void static::assertSame($select, $result); } + #[Test] + public function prepareStatementThrowsWhenDecoratorIsNotPreparable(): void + { + $platform = new Platform(new TestAsset\TrustingSql92Platform()); + + $decorator = $this->createStub(PlatformDecoratorInterface::class); + $platform->setTypeDecorator(Select::class, $decorator); + $platform->setSubject(new Select('foo')); + + self::expectException(RuntimeException::class); + self::expectExceptionMessage(sprintf( + RuntimeException::DECORATOR_NOT_IMPLEMENTING, + $decorator::class, + PreparableSqlInterface::class, + 'prepareStatement()', + )); + $platform->prepareStatement($this->resolveAdapter('sql92'), new StatementContainer()); + } + #[Test] public function prepareStatementThrowsWhenSubjectNotPreparable(): void { @@ -238,6 +296,22 @@ public function resolvePlatformWithPlatformInterface(): void static::assertSame($mockPlatform, $result); } + #[Test] + public function setTypeDecoratorKeepsDecoratorsAlreadyRegisteredForThePlatform(): void + { + $platform = new Platform(new TestAsset\TrustingSql92Platform()); + + $selectDecorator = $this->createStub(PlatformDecoratorInterface::class); + $insertDecorator = $this->createStub(PlatformDecoratorInterface::class); + $platform->setTypeDecorator(Select::class, $selectDecorator); + $platform->setTypeDecorator(Insert::class, $insertDecorator); + + static::assertSame( + [Select::class => $selectDecorator, Insert::class => $insertDecorator], + $platform->getDecorators(), + ); + } + #[Test] public function setTypeDecoratorRegistersDecorator(): void {