From 0f660c2783812a9e1251cc0b76b42c83f0f736f5 Mon Sep 17 00:00:00 2001 From: Dmytro Farafontov Date: Thu, 19 Nov 2026 11:24:52 +0200 Subject: [PATCH] Define DBAL 4's parameter type aliases in the Connection stub, and accept LockMode for the lock mode The DBAL 4 Connection stub used WrapperParameterTypeArray without declaring it. The stub replaces the class docblock where DBAL declares it, so Psalm read it as a class that doesn't exist and reported every $types argument. The stub now declares WrapperParameterType and WrapperParameterTypeArray as DBAL does. EntityRepository::find(), EntityManager::find() and refresh(), and EntityManagerInterface::find() and refresh() typed the lock mode as ?int. ORM 3 takes the DBAL 4 LockMode enum, so they now take LockMode|int|null. With DBAL before 4, LockMode is a class of int constants, and the int still matches. Fixes #170 Co-Authored-By: Claude Opus 5.5 --- stubs/DBAL/since-4/Connection.phpstub | 6 ++ stubs/EntityManager.phpstub | 8 +- stubs/EntityManagerInterface.phpstub | 5 +- stubs/EntityRepository.phpstub | 3 +- tests/acceptance/Connection.feature | 100 ++++++++++++++++++ tests/acceptance/EntityManager.feature | 25 +++++ .../acceptance/EntityManagerInterface.feature | 27 +++++ tests/acceptance/EntityRepository.feature | 13 +++ 8 files changed, 181 insertions(+), 6 deletions(-) create mode 100644 tests/acceptance/Connection.feature diff --git a/stubs/DBAL/since-4/Connection.phpstub b/stubs/DBAL/since-4/Connection.phpstub index 8091cec..9e6d4b4 100644 --- a/stubs/DBAL/since-4/Connection.phpstub +++ b/stubs/DBAL/since-4/Connection.phpstub @@ -8,6 +8,12 @@ use Traversable; /** * The queries of doctrine/dbal 4 are SQL sinks. + * + * The stub replaces the docblock of the class, so it declares the type aliases of DBAL's own docblock that the + * methods use. + * + * @phpstan-type WrapperParameterType = string|Type|ParameterType|ArrayParameterType + * @phpstan-type WrapperParameterTypeArray = array, WrapperParameterType>|array */ class Connection { diff --git a/stubs/EntityManager.phpstub b/stubs/EntityManager.phpstub index 12638d8..32151ea 100644 --- a/stubs/EntityManager.phpstub +++ b/stubs/EntityManager.phpstub @@ -2,6 +2,8 @@ namespace Doctrine\ORM; +use Doctrine\DBAL\LockMode; + class EntityManager implements EntityManagerInterface { /** @@ -18,7 +20,7 @@ class EntityManager implements EntityManagerInterface * @template T * @param class-string $entityName * @param mixed $id - * @param null|int $lockMode + * @param LockMode|int|null $lockMode * @param null|int $lockVersion * * @return null|T @@ -39,8 +41,8 @@ class EntityManager implements EntityManagerInterface } /** - * @param object $entity - * @param null|int $lockMode + * @param object $entity + * @param LockMode|int|null $lockMode * * @return void */ diff --git a/stubs/EntityManagerInterface.phpstub b/stubs/EntityManagerInterface.phpstub index cc5bf2c..11e4c04 100644 --- a/stubs/EntityManagerInterface.phpstub +++ b/stubs/EntityManagerInterface.phpstub @@ -2,6 +2,7 @@ namespace Doctrine\ORM; +use Doctrine\DBAL\LockMode; use Doctrine\Persistence\ObjectManager; interface EntityManagerInterface extends ObjectManager @@ -23,7 +24,7 @@ interface EntityManagerInterface extends ObjectManager * * @template T */ - public function find(string $entityName, $id, ?int $lockMode = null, ?int $lockVersion = null); + public function find(string $entityName, $id, LockMode|int|null $lockMode = null, ?int $lockVersion = null); /** * @param class-string $entityName @@ -40,5 +41,5 @@ interface EntityManagerInterface extends ObjectManager * * @return void */ - public function refresh($entity, ?int $lockMode = null); + public function refresh($entity, LockMode|int|null $lockMode = null); } diff --git a/stubs/EntityRepository.phpstub b/stubs/EntityRepository.phpstub index 82701de..36e7edd 100644 --- a/stubs/EntityRepository.phpstub +++ b/stubs/EntityRepository.phpstub @@ -5,6 +5,7 @@ namespace Doctrine\ORM; use Doctrine\Common\Collections\Selectable; use Doctrine\Common\Collections\Collection; use Doctrine\Common\Collections\Criteria; +use Doctrine\DBAL\LockMode; use Doctrine\Persistence\ObjectRepository; /** @@ -38,7 +39,7 @@ class EntityRepository implements ObjectRepository, Selectable } /** - * @param ?int $lockMode + * @param LockMode|int|null $lockMode * @param ?int $lockVersion * * @return ?T diff --git a/tests/acceptance/Connection.feature b/tests/acceptance/Connection.feature new file mode 100644 index 0000000..70844c7 --- /dev/null +++ b/tests/acceptance/Connection.feature @@ -0,0 +1,100 @@ +Feature: Connection + In order to use Doctrine DBAL Connection safely + As a Psalm user + I need Psalm to typecheck the parameter types of Connection's query methods + + Background: + Given I have Doctrine plugin enabled + And I have the following code preamble + """ + = 4.0" + And I have the following code + """ + connection()->( + 'SELECT a FROM t WHERE a = :a AND b IN (:b) AND c = :c AND d = :d', + ['a' => 1, 'b' => [1, 2], 'c' => 'x', 'd' => 'y'], + ['a' => ParameterType::INTEGER, 'b' => ArrayParameterType::INTEGER, 'c' => 'string', 'd' => type()], + ); + """ + When I run Psalm + Then I see no errors + Examples: + | method | + | executeQuery | + | executeStatement | + | fetchAssociative | + | fetchNumeric | + | fetchOne | + | fetchAllNumeric | + | fetchAllAssociative | + | fetchAllKeyValue | + | fetchAllAssociativeIndexed | + | fetchFirstColumn | + | iterateNumeric | + | iterateAssociative | + | iterateKeyValue | + | iterateAssociativeIndexed | + | iterateColumn | + + @Connection::fetchOne + Scenario: Passing positional parameter types to Connection's query methods + Given I have the "doctrine/dbal" package satisfying the ">= 4.0" + And I have the following code + """ + connection()->fetchOne('SELECT a FROM t WHERE a = ? AND b = ?', [1, 'x'], [ParameterType::INTEGER, 'string']); + """ + When I run Psalm + Then I see no errors + + @Connection::fetchOne + Scenario: Passing an invalid parameter type to Connection's query methods + Given I have the "doctrine/dbal" package satisfying the ">= 4.0" + And I have the following code + """ + connection()->fetchOne('SELECT a FROM t WHERE a = :a', ['a' => 1], ['a' => 1.5]); + """ + When I run Psalm + Then I see these errors + | Type | Message | + | InvalidArgument | /Argument 3 of .*Connection::fetchOne expects .*, but array{a: float\(1\.5\)} provided/ | + And I see no other errors diff --git a/tests/acceptance/EntityManager.feature b/tests/acceptance/EntityManager.feature index 72ef7d5..974fe86 100644 --- a/tests/acceptance/EntityManager.feature +++ b/tests/acceptance/EntityManager.feature @@ -105,3 +105,28 @@ Feature: EntityManager """ When I run Psalm Then I see no errors + + @EntityManager::find + Scenario: Finding an entity with a lock mode + Given I have the "doctrine/orm" package satisfying the ">= 3.0" + And I have the following code + """ + atan(em()->find(I::class, 1, \Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE, 1)); + """ + When I run Psalm + Then I see these errors + | Type | Message | + | InvalidArgument | Argument 1 of atan expects float, but I\|null provided | + And I see no other errors + + @EntityManager::refresh + Scenario: Refreshing an entity with a lock mode + Given I have the "doctrine/orm" package satisfying the ">= 3.0" + And I have the following code + """ + function f(I $entity): void { + em()->refresh($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE); + } + """ + When I run Psalm + Then I see no errors diff --git a/tests/acceptance/EntityManagerInterface.feature b/tests/acceptance/EntityManagerInterface.feature index eaca7b7..54e90a3 100644 --- a/tests/acceptance/EntityManagerInterface.feature +++ b/tests/acceptance/EntityManagerInterface.feature @@ -101,3 +101,30 @@ Feature: EntityManagerInterface | Type | Message | | InvalidScalarArgument | Argument 1 of Doctrine\ORM\EntityManagerInterface::getReference expects class-string, but 123 provided | And I see no other errors + + @EntityManagerInterface::find + Scenario: Finding an entity with a lock mode + Given I have the "doctrine/orm" package satisfying the ">= 3.0" + And I have the following code + """ + function f(EntityManagerInterface $em): void { + atan($em->find(I::class, 1, \Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE, 1)); + } + """ + When I run Psalm + Then I see these errors + | Type | Message | + | InvalidArgument | Argument 1 of atan expects float, but I\|null provided | + And I see no other errors + + @EntityManagerInterface::refresh + Scenario: Refreshing an entity with a lock mode + Given I have the "doctrine/orm" package satisfying the ">= 3.0" + And I have the following code + """ + function f(EntityManagerInterface $em, I $entity): void { + $em->refresh($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE); + } + """ + When I run Psalm + Then I see no errors diff --git a/tests/acceptance/EntityRepository.feature b/tests/acceptance/EntityRepository.feature index 6ee6fe7..3a1a761 100644 --- a/tests/acceptance/EntityRepository.feature +++ b/tests/acceptance/EntityRepository.feature @@ -87,3 +87,16 @@ Feature: EntityRepository """ When I run Psalm Then I see no errors + + @EntityRepository::find + Scenario: Finding an entity with a lock mode + Given I have the "doctrine/orm" package satisfying the ">= 3.0" + And I have the following code + """ + atan(repo(I::class)->find(1, \Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE, 1)); + """ + When I run Psalm + Then I see these errors + | Type | Message | + | InvalidArgument | Argument 1 of atan expects float, but I\|null provided | + And I see no other errors