diff options
Diffstat (limited to 'lib/public/AppFramework/Db')
| -rw-r--r-- | lib/public/AppFramework/Db/DoesNotExistException.php | 27 | ||||
| -rw-r--r-- | lib/public/AppFramework/Db/Entity.php | 203 | ||||
| -rw-r--r-- | lib/public/AppFramework/Db/IMapperException.php | 26 | ||||
| -rw-r--r-- | lib/public/AppFramework/Db/Mapper.php | 371 | ||||
| -rw-r--r-- | lib/public/AppFramework/Db/MultipleObjectsReturnedException.php | 27 | ||||
| -rw-r--r-- | lib/public/AppFramework/Db/QBMapper.php | 169 | ||||
| -rw-r--r-- | lib/public/AppFramework/Db/TTransactional.php | 88 |
7 files changed, 319 insertions, 592 deletions
diff --git a/lib/public/AppFramework/Db/DoesNotExistException.php b/lib/public/AppFramework/Db/DoesNotExistException.php index 6969e1016c5..416268b27c1 100644 --- a/lib/public/AppFramework/Db/DoesNotExistException.php +++ b/lib/public/AppFramework/Db/DoesNotExistException.php @@ -1,31 +1,11 @@ <?php declare(strict_types=1); - /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Bernhard Posselt <dev@bernhard-posselt.com> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\AppFramework\Db; /** @@ -34,7 +14,6 @@ namespace OCP\AppFramework\Db; * @since 7.0.0 */ class DoesNotExistException extends \Exception implements IMapperException { - /** * Constructor * @param string $msg the error message diff --git a/lib/public/AppFramework/Db/Entity.php b/lib/public/AppFramework/Db/Entity.php index 34719c82aea..3094070af5f 100644 --- a/lib/public/AppFramework/Db/Entity.php +++ b/lib/public/AppFramework/Db/Entity.php @@ -1,53 +1,40 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Bernhard Posselt <dev@bernhard-posselt.com> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Daniel Kesselberg <mail@danielkesselberg.de> - * @author Morris Jobke <hey@morrisjobke.de> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\AppFramework\Db; +use OCP\DB\Types; + use function lcfirst; use function substr; /** - * @method integer getId() - * @method void setId(integer $id) + * @method int getId() + * @method void setId(int $id) * @since 7.0.0 + * @psalm-consistent-constructor */ abstract class Entity { + /** + * @var int + */ public $id; - private $_updatedFields = []; - private $_fieldTypes = ['id' => 'integer']; - + private array $_updatedFields = []; + /** @var array<string, \OCP\DB\Types::*> */ + private array $_fieldTypes = ['id' => 'integer']; /** * Simple alternative constructor for building entities from a request * @param array $params the array which was obtained via $this->params('key') - * in the controller - * @return Entity + * in the controller * @since 7.0.0 */ - public static function fromParams(array $params) { + public static function fromParams(array $params): static { $instance = new static(); foreach ($params as $key => $value) { @@ -64,13 +51,12 @@ abstract class Entity { * @param array $row the row to map onto the entity * @since 7.0.0 */ - public static function fromRow(array $row) { + public static function fromRow(array $row): static { $instance = new static(); foreach ($row as $key => $value) { - $prop = ucfirst($instance->columnToProperty($key)); - $setter = 'set' . $prop; - $instance->$setter($value); + $prop = $instance->columnToProperty($key); + $instance->setter($prop, [$value]); } $instance->resetUpdatedFields(); @@ -80,10 +66,10 @@ abstract class Entity { /** - * @return array with attribute and type + * @return array<string, \OCP\DB\Types::*> with attribute and type * @since 7.0.0 */ - public function getFieldTypes() { + public function getFieldTypes(): array { return $this->_fieldTypes; } @@ -92,49 +78,89 @@ abstract class Entity { * Marks the entity as clean needed for setting the id after the insertion * @since 7.0.0 */ - public function resetUpdatedFields() { + public function resetUpdatedFields(): void { $this->_updatedFields = []; } /** * Generic setter for properties + * + * @throws \InvalidArgumentException * @since 7.0.0 + * */ - protected function setter($name, $args) { + protected function setter(string $name, array $args): void { // setters should only work for existing attributes - if (property_exists($this, $name)) { - if ($this->$name === $args[0]) { - return; - } - $this->markFieldUpdated($name); - - // if type definition exists, cast to correct type - if ($args[0] !== null && array_key_exists($name, $this->_fieldTypes)) { - $type = $this->_fieldTypes[$name]; - if ($type === 'blob') { - // (B)LOB is treated as string when we read from the DB - $type = 'string'; + if (!property_exists($this, $name)) { + throw new \BadFunctionCallException($name . ' is not a valid attribute'); + } + + if ($args[0] === $this->$name) { + return; + } + $this->markFieldUpdated($name); + + // if type definition exists, cast to correct type + if ($args[0] !== null && array_key_exists($name, $this->_fieldTypes)) { + $type = $this->_fieldTypes[$name]; + if ($type === Types::BLOB) { + // (B)LOB is treated as string when we read from the DB + if (is_resource($args[0])) { + $args[0] = stream_get_contents($args[0]); } - settype($args[0], $type); + $type = Types::STRING; + } + + switch ($type) { + case Types::BIGINT: + case Types::SMALLINT: + settype($args[0], Types::INTEGER); + break; + case Types::BINARY: + case Types::DECIMAL: + case Types::TEXT: + settype($args[0], Types::STRING); + break; + case Types::TIME: + case Types::DATE: + case Types::DATETIME: + case Types::DATETIME_TZ: + if (!$args[0] instanceof \DateTime) { + $args[0] = new \DateTime($args[0]); + } + break; + case Types::TIME_IMMUTABLE: + case Types::DATE_IMMUTABLE: + case Types::DATETIME_IMMUTABLE: + case Types::DATETIME_TZ_IMMUTABLE: + if (!$args[0] instanceof \DateTimeImmutable) { + $args[0] = new \DateTimeImmutable($args[0]); + } + break; + case Types::JSON: + if (!is_array($args[0])) { + $args[0] = json_decode($args[0], true); + } + break; + default: + settype($args[0], $type); } - $this->$name = $args[0]; - } else { - throw new \BadFunctionCallException($name . - ' is not a valid attribute'); } + $this->$name = $args[0]; + } /** * Generic getter for properties * @since 7.0.0 */ - protected function getter($name) { + protected function getter(string $name): mixed { // getters should only work for existing attributes if (property_exists($this, $name)) { return $this->$name; } else { - throw new \BadFunctionCallException($name . - ' is not a valid attribute'); + throw new \BadFunctionCallException($name + . ' is not a valid attribute'); } } @@ -146,16 +172,16 @@ abstract class Entity { * getter method * @since 7.0.0 */ - public function __call($methodName, $args) { - if (strpos($methodName, 'set') === 0) { + public function __call(string $methodName, array $args) { + if (str_starts_with($methodName, 'set')) { $this->setter(lcfirst(substr($methodName, 3)), $args); - } elseif (strpos($methodName, 'get') === 0) { + } elseif (str_starts_with($methodName, 'get')) { return $this->getter(lcfirst(substr($methodName, 3))); } elseif ($this->isGetterForBoolProperty($methodName)) { return $this->getter(lcfirst(substr($methodName, 2))); } else { - throw new \BadFunctionCallException($methodName . - ' does not exist'); + throw new \BadFunctionCallException($methodName + . ' does not exist'); } } @@ -165,9 +191,9 @@ abstract class Entity { * @since 18.0.0 */ protected function isGetterForBoolProperty(string $methodName): bool { - if (strpos($methodName, 'is') === 0) { + if (str_starts_with($methodName, 'is')) { $fieldName = lcfirst(substr($methodName, 2)); - return isset($this->_fieldTypes[$fieldName]) && strpos($this->_fieldTypes[$fieldName], 'bool') === 0; + return isset($this->_fieldTypes[$fieldName]) && str_starts_with($this->_fieldTypes[$fieldName], 'bool'); } return false; } @@ -177,23 +203,24 @@ abstract class Entity { * @param string $attribute the name of the attribute * @since 7.0.0 */ - protected function markFieldUpdated($attribute) { + protected function markFieldUpdated(string $attribute): void { $this->_updatedFields[$attribute] = true; } /** * Transform a database columnname to a property + * * @param string $columnName the name of the column * @return string the property name * @since 7.0.0 */ - public function columnToProperty($columnName) { + public function columnToProperty(string $columnName) { $parts = explode('_', $columnName); - $property = null; + $property = ''; foreach ($parts as $part) { - if ($property === null) { + if ($property === '') { $property = $part; } else { $property .= ucfirst($part); @@ -206,16 +233,17 @@ abstract class Entity { /** * Transform a property to a database column name + * * @param string $property the name of the property * @return string the column name * @since 7.0.0 */ - public function propertyToColumn($property) { + public function propertyToColumn(string $property): string { $parts = preg_split('/(?=[A-Z])/', $property); - $column = null; + $column = ''; foreach ($parts as $part) { - if ($column === null) { + if ($column === '') { $column = $part; } else { $column .= '_' . lcfirst($part); @@ -230,19 +258,33 @@ abstract class Entity { * @return array array of updated fields for update query * @since 7.0.0 */ - public function getUpdatedFields() { + public function getUpdatedFields(): array { return $this->_updatedFields; } /** - * Adds type information for a field so that its automatically casted to + * Adds type information for a field so that it's automatically cast to * that value once its being returned from the database + * * @param string $fieldName the name of the attribute - * @param string $type the type which will be used to call settype() + * @param \OCP\DB\Types::* $type the type which will be used to match a cast + * @since 31.0.0 Parameter $type is now restricted to {@see \OCP\DB\Types} constants. The formerly accidentally supported types 'int'|'bool'|'double' are mapped to Types::INTEGER|Types::BOOLEAN|Types::FLOAT accordingly. * @since 7.0.0 */ - protected function addType($fieldName, $type) { + protected function addType(string $fieldName, string $type): void { + /** @psalm-suppress TypeDoesNotContainType */ + if (in_array($type, ['bool', 'double', 'int', 'array', 'object'], true)) { + // Mapping legacy strings to the actual types + $type = match ($type) { + 'int' => Types::INTEGER, + 'bool' => Types::BOOLEAN, + 'double' => Types::FLOAT, + 'array', + 'object' => Types::STRING, + }; + } + $this->_fieldTypes[$fieldName] = $type; } @@ -250,11 +292,13 @@ abstract class Entity { /** * Slugify the value of a given attribute * Warning: This doesn't result in a unique value + * * @param string $attributeName the name of the attribute, which value should be slugified * @return string slugified value * @since 7.0.0 + * @deprecated 24.0.0 */ - public function slugify($attributeName) { + public function slugify(string $attributeName): string { // toSlug should only work for existing attributes if (property_exists($this, $attributeName)) { $value = $this->$attributeName; @@ -263,9 +307,8 @@ abstract class Entity { $value = strtolower($value); // trim '-' return trim($value, '-'); - } else { - throw new \BadFunctionCallException($attributeName . - ' is not a valid attribute'); } + + throw new \BadFunctionCallException($attributeName . ' is not a valid attribute'); } } diff --git a/lib/public/AppFramework/Db/IMapperException.php b/lib/public/AppFramework/Db/IMapperException.php index 591bfda2e66..3e91422a89f 100644 --- a/lib/public/AppFramework/Db/IMapperException.php +++ b/lib/public/AppFramework/Db/IMapperException.php @@ -1,34 +1,14 @@ <?php declare(strict_types=1); - /** - * @copyright Copyright (c) 2018, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\AppFramework\Db; /** * @since 16.0.0 */ -interface IMapperException { +interface IMapperException extends \Throwable { } diff --git a/lib/public/AppFramework/Db/Mapper.php b/lib/public/AppFramework/Db/Mapper.php deleted file mode 100644 index 1ee4fe80ca2..00000000000 --- a/lib/public/AppFramework/Db/Mapper.php +++ /dev/null @@ -1,371 +0,0 @@ -<?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Bernhard Posselt <dev@bernhard-posselt.com> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Joas Schilling <coding@schilljs.com> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ - -namespace OCP\AppFramework\Db; - -use OCP\IDBConnection; - -/** - * Simple parent class for inheriting your data access layer from. This class - * may be subject to change in the future - * @since 7.0.0 - * @deprecated 14.0.0 Move over to QBMapper - */ -abstract class Mapper { - protected $tableName; - protected $entityClass; - protected $db; - - /** - * @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 - * mapped to queries without using sql - * @since 7.0.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - public function __construct(IDBConnection $db, $tableName, $entityClass = null) { - $this->db = $db; - $this->tableName = '*PREFIX*' . $tableName; - - // if not given set the entity name to the class without the mapper part - // cache it here for later use since reflection is slow - if ($entityClass === null) { - $this->entityClass = str_replace('Mapper', '', get_class($this)); - } else { - $this->entityClass = $entityClass; - } - } - - - /** - * @return string the table name - * @since 7.0.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - public function getTableName() { - return $this->tableName; - } - - - /** - * Deletes an entity from the table - * @param Entity $entity the entity that should be deleted - * @return Entity the deleted entity - * @since 7.0.0 - return value added in 8.1.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - public function delete(Entity $entity) { - $sql = 'DELETE FROM `' . $this->tableName . '` WHERE `id` = ?'; - $stmt = $this->execute($sql, [$entity->getId()]); - $stmt->closeCursor(); - return $entity; - } - - - /** - * Creates a new entry in the db from an entity - * @param Entity $entity the entity that should be created - * @return Entity the saved entity with the set id - * @since 7.0.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - public function insert(Entity $entity) { - // get updated fields to save, fields have to be set using a setter to - // be saved - $properties = $entity->getUpdatedFields(); - $values = ''; - $columns = ''; - $params = []; - - // build the fields - $i = 0; - foreach ($properties as $property => $updated) { - $column = $entity->propertyToColumn($property); - $getter = 'get' . ucfirst($property); - - $columns .= '`' . $column . '`'; - $values .= '?'; - - // only append colon if there are more entries - if ($i < count($properties) - 1) { - $columns .= ','; - $values .= ','; - } - - $params[] = $entity->$getter(); - $i++; - } - - $sql = 'INSERT INTO `' . $this->tableName . '`(' . - $columns . ') VALUES(' . $values . ')'; - - $stmt = $this->execute($sql, $params); - - $entity->setId((int) $this->db->lastInsertId($this->tableName)); - - $stmt->closeCursor(); - - return $entity; - } - - - - /** - * 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 - * @return Entity the saved entity with the set id - * @since 7.0.0 - return value was added in 8.0.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - public function update(Entity $entity) { - // if entity wasn't changed it makes no sense to run a db query - $properties = $entity->getUpdatedFields(); - if (count($properties) === 0) { - return $entity; - } - - // entity needs an id - $id = $entity->getId(); - if ($id === null) { - throw new \InvalidArgumentException( - 'Entity which should be updated has no id'); - } - - // get updated fields to save, fields have to be set using a setter to - // be saved - // do not update the id field - unset($properties['id']); - - $columns = ''; - $params = []; - - // build the fields - $i = 0; - foreach ($properties as $property => $updated) { - $column = $entity->propertyToColumn($property); - $getter = 'get' . ucfirst($property); - - $columns .= '`' . $column . '` = ?'; - - // only append colon if there are more entries - if ($i < count($properties) - 1) { - $columns .= ','; - } - - $params[] = $entity->$getter(); - $i++; - } - - $sql = 'UPDATE `' . $this->tableName . '` SET ' . - $columns . ' WHERE `id` = ?'; - $params[] = $id; - - $stmt = $this->execute($sql, $params); - $stmt->closeCursor(); - - return $entity; - } - - /** - * Checks if an array is associative - * @param array $array - * @return bool true if associative - * @since 8.1.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - private function isAssocArray(array $array) { - return array_values($array) !== $array; - } - - /** - * Returns the correct PDO constant based on the value type - * @param $value - * @return int PDO constant - * @since 8.1.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - private function getPDOType($value) { - switch (gettype($value)) { - case 'integer': - return \PDO::PARAM_INT; - case 'boolean': - return \PDO::PARAM_BOOL; - default: - return \PDO::PARAM_STR; - } - } - - - /** - * Runs an sql query - * @param string $sql the prepare string - * @param array $params the params which should replace the ? in the sql query - * @param int $limit the maximum number of rows - * @param int $offset from which row we want to start - * @return \PDOStatement the database query result - * @since 7.0.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - protected function execute($sql, array $params = [], $limit = null, $offset = null) { - $query = $this->db->prepare($sql, $limit, $offset); - - if ($this->isAssocArray($params)) { - foreach ($params as $key => $param) { - $pdoConstant = $this->getPDOType($param); - $query->bindValue($key, $param, $pdoConstant); - } - } else { - $index = 1; // bindParam is 1 indexed - foreach ($params as $param) { - $pdoConstant = $this->getPDOType($param); - $query->bindValue($index, $param, $pdoConstant); - $index++; - } - } - - $query->execute(); - - return $query; - } - - /** - * Returns an db result and throws exceptions when there are more or less - * results - * @see findEntity - * @param string $sql the sql query - * @param array $params the parameters of the sql query - * @param int $limit the maximum number of rows - * @param int $offset from which row we want to start - * @throws DoesNotExistException if the item does not exist - * @throws MultipleObjectsReturnedException if more than one item exist - * @return array the result as row - * @since 7.0.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - protected function findOneQuery($sql, array $params = [], $limit = null, $offset = null) { - $stmt = $this->execute($sql, $params, $limit, $offset); - $row = $stmt->fetch(); - - if ($row === false || $row === null) { - $stmt->closeCursor(); - $msg = $this->buildDebugMessage( - 'Did expect one result but found none when executing', $sql, $params, $limit, $offset - ); - throw new DoesNotExistException($msg); - } - $row2 = $stmt->fetch(); - $stmt->closeCursor(); - //MDB2 returns null, PDO and doctrine false when no row is available - if (! ($row2 === false || $row2 === null)) { - $msg = $this->buildDebugMessage( - 'Did not expect more than one result when executing', $sql, $params, $limit, $offset - ); - throw new MultipleObjectsReturnedException($msg); - } else { - return $row; - } - } - - /** - * Builds an error message by prepending the $msg to an error message which - * has the parameters - * @see findEntity - * @param string $sql the sql query - * @param array $params the parameters of the sql query - * @param int $limit the maximum number of rows - * @param int $offset from which row we want to start - * @return string formatted error message string - * @since 9.1.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - private function buildDebugMessage($msg, $sql, array $params = [], $limit = null, $offset = null) { - return $msg . - ': query "' . $sql . '"; ' . - 'parameters ' . print_r($params, true) . '; ' . - 'limit "' . $limit . '"; '. - 'offset "' . $offset . '"'; - } - - - /** - * Creates an entity from a row. Automatically determines the entity class - * from the current mapper name (MyEntityMapper -> MyEntity) - * @param array $row the row which should be converted to an entity - * @return Entity the entity - * @since 7.0.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - protected function mapRowToEntity($row) { - return call_user_func($this->entityClass .'::fromRow', $row); - } - - - /** - * Runs a sql query and returns an array of entities - * @param string $sql the prepare string - * @param array $params the params which should replace the ? in the sql query - * @param int $limit the maximum number of rows - * @param int $offset from which row we want to start - * @return array all fetched entities - * @since 7.0.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - protected function findEntities($sql, array $params = [], $limit = null, $offset = null) { - $stmt = $this->execute($sql, $params, $limit, $offset); - - $entities = []; - - while ($row = $stmt->fetch()) { - $entities[] = $this->mapRowToEntity($row); - } - - $stmt->closeCursor(); - - return $entities; - } - - - /** - * Returns an db result and throws exceptions when there are more or less - * results - * @param string $sql the sql query - * @param array $params the parameters of the sql query - * @param int $limit the maximum number of rows - * @param int $offset from which row we want to start - * @throws DoesNotExistException if the item does not exist - * @throws MultipleObjectsReturnedException if more than one item exist - * @return Entity the entity - * @since 7.0.0 - * @deprecated 14.0.0 Move over to QBMapper - */ - protected function findEntity($sql, array $params = [], $limit = null, $offset = null) { - return $this->mapRowToEntity($this->findOneQuery($sql, $params, $limit, $offset)); - } -} diff --git a/lib/public/AppFramework/Db/MultipleObjectsReturnedException.php b/lib/public/AppFramework/Db/MultipleObjectsReturnedException.php index e82f7cb8eff..e83bc1647d7 100644 --- a/lib/public/AppFramework/Db/MultipleObjectsReturnedException.php +++ b/lib/public/AppFramework/Db/MultipleObjectsReturnedException.php @@ -1,31 +1,11 @@ <?php declare(strict_types=1); - /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Bernhard Posselt <dev@bernhard-posselt.com> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\AppFramework\Db; /** @@ -34,7 +14,6 @@ namespace OCP\AppFramework\Db; * @since 7.0.0 */ class MultipleObjectsReturnedException extends \Exception implements IMapperException { - /** * Constructor * @param string $msg the error message diff --git a/lib/public/AppFramework/Db/QBMapper.php b/lib/public/AppFramework/Db/QBMapper.php index 72373ba26c3..7fb5b2a9afd 100644 --- a/lib/public/AppFramework/Db/QBMapper.php +++ b/lib/public/AppFramework/Db/QBMapper.php @@ -1,37 +1,16 @@ <?php declare(strict_types=1); - /** - * @copyright 2018, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Daniel Kesselberg <mail@danielkesselberg.de> - * @author Joas Schilling <coding@schilljs.com> - * @author Marius David Wieschollek <git.public@mdns.eu> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\AppFramework\Db; -use Doctrine\DBAL\Exception\UniqueConstraintViolationException; +use Generator; +use OCP\DB\Exception; use OCP\DB\QueryBuilder\IQueryBuilder; +use OCP\DB\Types; use OCP\IDBConnection; /** @@ -43,7 +22,6 @@ use OCP\IDBConnection; * @template T of Entity */ abstract class QBMapper { - /** @var string */ protected $tableName; @@ -56,12 +34,11 @@ 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|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 + * @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 */ - public function __construct(IDBConnection $db, string $tableName, string $entityClass = null) { + public function __construct(IDBConnection $db, string $tableName, ?string $entityClass = null) { $this->db = $db; $this->tableName = $tableName; @@ -86,10 +63,12 @@ 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 + * @throws Exception * @since 14.0.0 */ public function delete(Entity $entity): Entity { @@ -101,17 +80,19 @@ abstract class QBMapper { ->where( $qb->expr()->eq('id', $qb->createNamedParameter($entity->getId(), $idType)) ); - $qb->execute(); + $qb->executeStatement(); return $entity; } /** * 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 + * @throws Exception * @since 14.0.0 */ public function insert(Entity $entity): Entity { @@ -132,11 +113,11 @@ abstract class QBMapper { $qb->setValue($column, $qb->createNamedParameter($value, $type)); } - $qb->execute(); + $qb->executeStatement(); if ($entity->id === null) { // When autoincrement is used id is always an int - $entity->setId((int)$qb->getLastInsertId()); + $entity->setId($qb->getLastInsertId()); } return $entity; @@ -151,24 +132,30 @@ abstract class QBMapper { * @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 Exception * @throws \InvalidArgumentException if entity has no id * @since 15.0.0 */ public function insertOrUpdate(Entity $entity): Entity { try { return $this->insert($entity); - } catch (UniqueConstraintViolationException $ex) { - return $this->update($entity); + } catch (Exception $ex) { + if ($ex->getReason() === Exception::REASON_UNIQUE_CONSTRAINT_VIOLATION) { + return $this->update($entity); + } + throw $ex; } } /** * 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 + * @throws Exception + * @throws \InvalidArgumentException if entity has no id * @since 14.0.0 */ public function update(Entity $entity): Entity { @@ -208,7 +195,7 @@ abstract class QBMapper { $qb->where( $qb->expr()->eq('id', $qb->createNamedParameter($id, $idType)) ); - $qb->execute(); + $qb->executeStatement(); return $entity; } @@ -217,13 +204,13 @@ abstract class QBMapper { * Returns the type parameter for the QueryBuilder for a specific property * of the $entity * - * @param Entity $entity The entity to get the types from + * @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 + * @return int|string * @since 16.0.0 */ - protected function getParameterTypeForProperty(Entity $entity, string $property): int { + protected function getParameterTypeForProperty(Entity $entity, string $property) { $types = $entity->getFieldTypes(); if (!isset($types[ $property ])) { @@ -232,15 +219,34 @@ abstract class QBMapper { switch ($types[ $property ]) { case 'int': - case 'integer': + case Types::INTEGER: + case Types::SMALLINT: return IQueryBuilder::PARAM_INT; - case 'string': + case Types::STRING: return IQueryBuilder::PARAM_STR; case 'bool': - case 'boolean': + case Types::BOOLEAN: return IQueryBuilder::PARAM_BOOL; - case 'blob': + case Types::BLOB: return IQueryBuilder::PARAM_LOB; + case Types::DATE: + return IQueryBuilder::PARAM_DATETIME_MUTABLE; + case Types::DATETIME: + return IQueryBuilder::PARAM_DATETIME_MUTABLE; + case Types::DATETIME_TZ: + return IQueryBuilder::PARAM_DATETIME_TZ_MUTABLE; + case Types::DATE_IMMUTABLE: + return IQueryBuilder::PARAM_DATE_IMMUTABLE; + case Types::DATETIME_IMMUTABLE: + return IQueryBuilder::PARAM_DATETIME_IMMUTABLE; + case Types::DATETIME_TZ_IMMUTABLE: + return IQueryBuilder::PARAM_DATETIME_TZ_IMMUTABLE; + case Types::TIME: + return IQueryBuilder::PARAM_TIME_MUTABLE; + case Types::TIME_IMMUTABLE: + return IQueryBuilder::PARAM_TIME_IMMUTABLE; + case Types::JSON: + return IQueryBuilder::PARAM_JSON; } return IQueryBuilder::PARAM_STR; @@ -250,28 +256,29 @@ abstract class QBMapper { * Returns an db result and throws exceptions when there are more or less * results * - * @see findEntity - * * @param IQueryBuilder $query - * @throws DoesNotExistException if the item does not exist - * @throws MultipleObjectsReturnedException if more than one item exist * @return array the result as row + * @throws Exception + * @throws MultipleObjectsReturnedException if more than one item exist + * @throws DoesNotExistException if the item does not exist + * @see findEntity + * * @since 14.0.0 */ protected function findOneQuery(IQueryBuilder $query): array { - $cursor = $query->execute(); + $result = $query->executeQuery(); - $row = $cursor->fetch(); + $row = $result->fetch(); if ($row === false) { - $cursor->closeCursor(); + $result->closeCursor(); $msg = $this->buildDebugMessage( 'Did expect one result but found none when executing', $query ); throw new DoesNotExistException($msg); } - $row2 = $cursor->fetch(); - $cursor->closeCursor(); + $row2 = $result->fetch(); + $result->closeCursor(); if ($row2 !== false) { $msg = $this->buildDebugMessage( 'Did not expect more than one result when executing', $query @@ -289,8 +296,8 @@ abstract class QBMapper { * @since 14.0.0 */ private function buildDebugMessage(string $msg, IQueryBuilder $sql): string { - return $msg . - ': query "' . $sql->getSQL() . '"; '; + return $msg + . ': query "' . $sql->getSQL() . '"; '; } @@ -304,7 +311,8 @@ abstract class QBMapper { * @since 14.0.0 */ protected function mapRowToEntity(array $row): Entity { - return \call_user_func($this->entityClass .'::fromRow', $row); + unset($row['DOCTRINE_ROWNUM']); // remove doctrine/dbal helper column + return \call_user_func($this->entityClass . '::fromRow', $row); } @@ -312,22 +320,42 @@ abstract class QBMapper { * Runs a sql query and returns an array of entities * * @param IQueryBuilder $query - * @return Entity[] all fetched entities - * @psalm-return T[] all fetched entities + * @return list<Entity> all fetched entities + * @psalm-return list<T> all fetched entities + * @throws Exception * @since 14.0.0 */ protected function findEntities(IQueryBuilder $query): array { - $cursor = $query->execute(); - - $entities = []; - - while ($row = $cursor->fetch()) { - $entities[] = $this->mapRowToEntity($row); + $result = $query->executeQuery(); + try { + $entities = []; + while ($row = $result->fetch()) { + $entities[] = $this->mapRowToEntity($row); + } + return $entities; + } finally { + $result->closeCursor(); } + } - $cursor->closeCursor(); - - return $entities; + /** + * Runs a sql query and yields each resulting entity to obtain database entries in a memory-efficient way + * + * @param IQueryBuilder $query + * @return Generator Generator of fetched entities + * @psalm-return Generator<T> Generator of fetched entities + * @throws Exception + * @since 30.0.0 + */ + protected function yieldEntities(IQueryBuilder $query): Generator { + $result = $query->executeQuery(); + try { + while ($row = $result->fetch()) { + yield $this->mapRowToEntity($row); + } + } finally { + $result->closeCursor(); + } } @@ -336,10 +364,11 @@ abstract class QBMapper { * results * * @param IQueryBuilder $query - * @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 + * @throws Exception + * @throws MultipleObjectsReturnedException if more than one item exist + * @throws DoesNotExistException if the item does not exist * @since 14.0.0 */ protected function findEntity(IQueryBuilder $query): Entity { diff --git a/lib/public/AppFramework/Db/TTransactional.php b/lib/public/AppFramework/Db/TTransactional.php new file mode 100644 index 00000000000..8dd275e5420 --- /dev/null +++ b/lib/public/AppFramework/Db/TTransactional.php @@ -0,0 +1,88 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\AppFramework\Db; + +use OC\DB\Exceptions\DbalException; +use OCP\DB\Exception; +use OCP\IDBConnection; +use Throwable; +use function OCP\Log\logger; + +/** + * Helper trait for transactional operations + * + * @since 24.0.0 + */ +trait TTransactional { + /** + * Run an atomic database operation + * + * - Commit if no exceptions are thrown, return the callable result + * - Revert otherwise and rethrows the exception + * + * @template T + * @param callable $fn + * @psalm-param callable():T $fn + * @param IDBConnection $db + * + * @return mixed the result of the passed callable + * @psalm-return T + * + * @throws Exception for possible errors of commit or rollback or the custom operations within the closure + * @throws Throwable any other error caused by the closure + * + * @since 24.0.0 + * @see https://docs.nextcloud.com/server/latest/developer_manual/basics/storage/database.html#transactions + */ + protected function atomic(callable $fn, IDBConnection $db) { + $db->beginTransaction(); + try { + $result = $fn(); + $db->commit(); + return $result; + } catch (Throwable $e) { + $db->rollBack(); + throw $e; + } + } + + /** + * Wrapper around atomic() to retry after a retryable exception occurred + * + * Certain transactions might need to be retried. This is especially useful + * in highly concurrent requests where a deadlocks is thrown by the database + * without waiting for the lock to be freed (e.g. due to MySQL/MariaDB deadlock + * detection) + * + * @template T + * @param callable $fn + * @psalm-param callable():T $fn + * @param IDBConnection $db + * @param int $maxRetries + * + * @return mixed the result of the passed callable + * @psalm-return T + * + * @throws Exception for possible errors of commit or rollback or the custom operations within the closure + * @throws Throwable any other error caused by the closure + * + * @since 27.0.0 + */ + protected function atomicRetry(callable $fn, IDBConnection $db, int $maxRetries = 3): mixed { + for ($i = 0; $i < $maxRetries; $i++) { + try { + return $this->atomic($fn, $db); + } catch (DbalException $e) { + if (!$e->isRetryable() || $i === ($maxRetries - 1)) { + throw $e; + } + logger('core')->warning('Retrying operation after retryable exception.', [ 'exception' => $e ]); + } + } + } +} |