Merge pull request #23310 from nextcloud/enhancement/psalm-typed-qb-mapper

Add template typing to the QBMapper

apps/contactsinteraction/lib/Db/RecentContactMapper.php

@@ -30,6 +30,9 @@ use OCP\AppFramework\Db\QBMapper;
 use OCP\IDBConnection;
 use OCP\IUser;
 
+/**
+ * @template-extends QBMapper<RecentContact>
+ */
 class RecentContactMapper extends QBMapper {
 	public const TABLE_NAME = 'recent_contact';
 

apps/twofactor_backupcodes/lib/Db/BackupCodeMapper.php

@@ -30,6 +30,9 @@ use OCP\DB\QueryBuilder\IQueryBuilder;
 use OCP\IDBConnection;
 use OCP\IUser;
 
+/**
+ * @template-extends QBMapper<BackupCode>
+ */
 class BackupCodeMapper extends QBMapper {
 	public function __construct(IDBConnection $db) {
 		parent::__construct($db, 'twofactor_backupcodes');

lib/private/Authentication/Token/DefaultTokenMapper.php

@@ -35,6 +35,9 @@ use OCP\AppFramework\Db\QBMapper;
 use OCP\DB\QueryBuilder\IQueryBuilder;
 use OCP\IDBConnection;
 
+/**
+ * @template-extends QBMapper<DefaultToken>
+ */
 class DefaultTokenMapper extends QBMapper {
 	public function __construct(IDBConnection $db) {
 		parent::__construct($db, 'authtoken');

lib/private/Authentication/Token/PublicKeyTokenMapper.php

@@ -32,6 +32,9 @@ use OCP\AppFramework\Db\QBMapper;
 use OCP\DB\QueryBuilder\IQueryBuilder;
 use OCP\IDBConnection;
 
+/**
+ * @template-extends QBMapper<PublicKeyToken>
+ */
 class PublicKeyTokenMapper extends QBMapper {
 	public function __construct(IDBConnection $db) {
 		parent::__construct($db, 'authtoken');

lib/private/Authentication/Token/PublicKeyTokenProvider.php

@@ -219,7 +219,7 @@ class PublicKeyTokenProvider implements IProvider {
 		$activityInterval = $this->config->getSystemValueInt('token_auth_activity_update', 60);
 		$activityInterval = min(max($activityInterval, 0), 300);
 
-		/** @var DefaultToken $token */
+		/** @var PublicKeyToken $token */
 		$now = $this->time->getTime();
 		if ($token->getLastActivity() < ($now - $activityInterval)) {
 			// Update token only once per minute

lib/private/Authentication/WebAuthn/Db/PublicKeyCredentialMapper.php

@@ -30,6 +30,9 @@ use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Db\QBMapper;
 use OCP\IDBConnection;
 
+/**
+ * @template-extends QBMapper<PublicKeyCredentialEntity>
+ */
 class PublicKeyCredentialMapper extends QBMapper {
 	public function __construct(IDBConnection $db) {
 		parent::__construct($db, 'webauthn', PublicKeyCredentialEntity::class);

lib/public/AppFramework/Db/QBMapper.php

@@ -39,13 +39,15 @@ use OCP\IDBConnection;
  * may be subject to change in the future
  *
  * @since 14.0.0
+ *
+ * @template T of Entity
  */
 abstract class QBMapper {
 
 	/** @var string */
 	protected $tableName;
 
-	/** @var string */
+	/** @var string|class-string<T> */
 	protected $entityClass;
 
 	/** @var IDBConnection */
@@ -54,7 +56,8 @@ abstract class QBMapper {
 	/**
 	 * @param IDBConnection $db Instance of the Db abstraction layer
 	 * @param string $tableName the name of the table. set this to allow entity
-	 * @param string $entityClass the name of the entity that the sql should be
+	 * @param string|null $entityClass the name of the entity that the sql should be
+	 * @psalm-param class-string<T>|null $entityClass the name of the entity that the sql should be
 	 * mapped to queries without using sql
 	 * @since 14.0.0
 	 */
@@ -84,7 +87,9 @@ abstract class QBMapper {
 	/**
 	 * Deletes an entity from the table
 	 * @param Entity $entity the entity that should be deleted
+	 * @psalm-param T $entity the entity that should be deleted
 	 * @return Entity the deleted entity
+	 * @psalm-return T the deleted entity
 	 * @since 14.0.0
 	 */
 	public function delete(Entity $entity): Entity {
@@ -104,7 +109,9 @@ abstract class QBMapper {
 	/**
 	 * Creates a new entry in the db from an entity
 	 * @param Entity $entity the entity that should be created
+	 * @psalm-param T $entity the entity that should be created
 	 * @return Entity the saved entity with the set id
+	 * @psalm-return T the saved entity with the set id
 	 * @since 14.0.0
 	 */
 	public function insert(Entity $entity): Entity {
@@ -141,7 +148,9 @@ abstract class QBMapper {
 	 * by the database
 	 *
 	 * @param Entity $entity the entity that should be created/updated
+	 * @psalm-param T $entity the entity that should be created/updated
 	 * @return Entity the saved entity with the (new) id
+	 * @psalm-return T the saved entity with the (new) id
 	 * @throws \InvalidArgumentException if entity has no id
 	 * @since 15.0.0
 	 */
@@ -157,7 +166,9 @@ abstract class QBMapper {
 	 * Updates an entry in the db from an entity
 	 * @throws \InvalidArgumentException if entity has no id
 	 * @param Entity $entity the entity that should be created
+	 * @psalm-param T $entity the entity that should be created
 	 * @return Entity the saved entity with the set id
+	 * @psalm-return T the saved entity with the set id
 	 * @since 14.0.0
 	 */
 	public function update(Entity $entity): Entity {
@@ -207,6 +218,7 @@ abstract class QBMapper {
 	 * of the $entity
 	 *
 	 * @param Entity $entity   The entity to get the types from
+	 * @psalm-param T $entity
 	 * @param string $property The property of $entity to get the type for
 	 * @return int
 	 * @since 16.0.0
@@ -288,6 +300,7 @@ abstract class QBMapper {
 	 *
 	 * @param array $row the row which should be converted to an entity
 	 * @return Entity the entity
+	 * @psalm-return T the entity
 	 * @since 14.0.0
 	 */
 	protected function mapRowToEntity(array $row): Entity {
@@ -300,6 +313,7 @@ abstract class QBMapper {
 	 *
 	 * @param IQueryBuilder $query
 	 * @return Entity[] all fetched entities
+	 * @psalm-return T[] all fetched entities
 	 * @since 14.0.0
 	 */
 	protected function findEntities(IQueryBuilder $query): array {
@@ -325,6 +339,7 @@ abstract class QBMapper {
 	 * @throws DoesNotExistException if the item does not exist
 	 * @throws MultipleObjectsReturnedException if more than one item exist
 	 * @return Entity the entity
+	 * @psalm-return T the entity
 	 * @since 14.0.0
 	 */
 	protected function findEntity(IQueryBuilder $query): Entity {