migrate therinaldos.com data

wedding-pics/lib/public/AppFramework/Db/DoesNotExistException.php

@@ -0,0 +1,44 @@
+<?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/>
+ *
+ */
+namespace OCP\AppFramework\Db;
+
+/**
+ * This is returned or should be returned when a find request does not find an
+ * entry in the database
+ * @since 7.0.0
+ */
+class DoesNotExistException extends \Exception implements IMapperException {
+	/**
+	 * Constructor
+	 * @param string $msg the error message
+	 * @since 7.0.0
+	 */
+	public function __construct($msg) {
+		parent::__construct($msg);
+	}
+}

wedding-pics/lib/public/AppFramework/Db/Entity.php

@@ -0,0 +1,288 @@
+<?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 Joas Schilling <coding@schilljs.com>
+ * @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/>
+ *
+ */
+namespace OCP\AppFramework\Db;
+
+use function lcfirst;
+use function substr;
+
+/**
+ * @method int getId()
+ * @method void setId(int $id)
+ * @since 7.0.0
+ * @psalm-consistent-constructor
+ */
+abstract class Entity {
+	/**
+	 * @var int
+	 */
+	public $id;
+
+	private array $_updatedFields = [];
+	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
+	 * @since 7.0.0
+	 */
+	public static function fromParams(array $params): static {
+		$instance = new static();
+
+		foreach ($params as $key => $value) {
+			$method = 'set' . ucfirst($key);
+			$instance->$method($value);
+		}
+
+		return $instance;
+	}
+
+
+	/**
+	 * Maps the keys of the row array to the attributes
+	 * @param array $row the row to map onto the entity
+	 * @since 7.0.0
+	 */
+	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);
+		}
+
+		$instance->resetUpdatedFields();
+
+		return $instance;
+	}
+
+
+	/**
+	 * @return array with attribute and type
+	 * @since 7.0.0
+	 */
+	public function getFieldTypes() {
+		return $this->_fieldTypes;
+	}
+
+
+	/**
+	 * Marks the entity as clean needed for setting the id after the insertion
+	 * @since 7.0.0
+	 */
+	public function resetUpdatedFields() {
+		$this->_updatedFields = [];
+	}
+
+	/**
+	 * Generic setter for properties
+	 * @since 7.0.0
+	 */
+	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
+					if (is_resource($args[0])) {
+						$args[0] = stream_get_contents($args[0]);
+					}
+					$type = 'string';
+				}
+
+				if ($type === 'datetime') {
+					if (!$args[0] instanceof \DateTime) {
+						$args[0] = new \DateTime($args[0]);
+					}
+				} elseif ($type === 'json') {
+					if (!is_array($args[0])) {
+						$args[0] = json_decode($args[0], true);
+					}
+				} else {
+					settype($args[0], $type);
+				}
+			}
+			$this->$name = $args[0];
+		} else {
+			throw new \BadFunctionCallException($name .
+				' is not a valid attribute');
+		}
+	}
+
+	/**
+	 * Generic getter for properties
+	 * @since 7.0.0
+	 */
+	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');
+		}
+	}
+
+
+	/**
+	 * Each time a setter is called, push the part after set
+	 * into an array: for instance setId will save Id in the
+	 * updated fields array so it can be easily used to create the
+	 * getter method
+	 * @since 7.0.0
+	 */
+	public function __call(string $methodName, array $args) {
+		if (str_starts_with($methodName, 'set')) {
+			$this->setter(lcfirst(substr($methodName, 3)), $args);
+		} 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');
+		}
+	}
+
+	/**
+	 * @param string $methodName
+	 * @return bool
+	 * @since 18.0.0
+	 */
+	protected function isGetterForBoolProperty(string $methodName): bool {
+		if (str_starts_with($methodName, 'is')) {
+			$fieldName = lcfirst(substr($methodName, 2));
+			return isset($this->_fieldTypes[$fieldName]) && str_starts_with($this->_fieldTypes[$fieldName], 'bool');
+		}
+		return false;
+	}
+
+	/**
+	 * Mark am attribute as updated
+	 * @param string $attribute the name of the attribute
+	 * @since 7.0.0
+	 */
+	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) {
+		$parts = explode('_', $columnName);
+		$property = null;
+
+		foreach ($parts as $part) {
+			if ($property === null) {
+				$property = $part;
+			} else {
+				$property .= ucfirst($part);
+			}
+		}
+
+		return $property;
+	}
+
+
+	/**
+	 * 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) {
+		$parts = preg_split('/(?=[A-Z])/', $property);
+		$column = null;
+
+		foreach ($parts as $part) {
+			if ($column === null) {
+				$column = $part;
+			} else {
+				$column .= '_' . lcfirst($part);
+			}
+		}
+
+		return $column;
+	}
+
+
+	/**
+	 * @return array array of updated fields for update query
+	 * @since 7.0.0
+	 */
+	public function getUpdatedFields() {
+		return $this->_updatedFields;
+	}
+
+
+	/**
+	 * Adds type information for a field so that its automatically casted 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()
+	 * @since 7.0.0
+	 */
+	protected function addType($fieldName, $type) {
+		$this->_fieldTypes[$fieldName] = $type;
+	}
+
+
+	/**
+	 * 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) {
+		// toSlug should only work for existing attributes
+		if (property_exists($this, $attributeName)) {
+			$value = $this->$attributeName;
+			// replace everything except alphanumeric with a single '-'
+			$value = preg_replace('/[^A-Za-z0-9]+/', '-', $value);
+			$value = strtolower($value);
+			// trim '-'
+			return trim($value, '-');
+		} else {
+			throw new \BadFunctionCallException($attributeName .
+				' is not a valid attribute');
+		}
+	}
+}

wedding-pics/lib/public/AppFramework/Db/IMapperException.php

@@ -0,0 +1,33 @@
+<?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/>.
+ *
+ */
+namespace OCP\AppFramework\Db;
+
+/**
+ * @since 16.0.0
+ */
+interface IMapperException extends \Throwable {
+}

wedding-pics/lib/public/AppFramework/Db/MultipleObjectsReturnedException.php

@@ -0,0 +1,44 @@
+<?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/>
+ *
+ */
+namespace OCP\AppFramework\Db;
+
+/**
+ * This is returned or should be returned when a find request finds more than one
+ * row
+ * @since 7.0.0
+ */
+class MultipleObjectsReturnedException extends \Exception implements IMapperException {
+	/**
+	 * Constructor
+	 * @param string $msg the error message
+	 * @since 7.0.0
+	 */
+	public function __construct($msg) {
+		parent::__construct($msg);
+	}
+}

wedding-pics/lib/public/AppFramework/Db/QBMapper.php

@@ -0,0 +1,363 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright 2018, Roeland Jago Douma <roeland@famdouma.nl>
+ *
+ * @author Anna Larch <anna@nextcloud.com>
+ * @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/>.
+ *
+ */
+namespace OCP\AppFramework\Db;
+
+use OCP\DB\Exception;
+use OCP\DB\QueryBuilder\IQueryBuilder;
+use OCP\IDBConnection;
+
+/**
+ * Simple parent class for inheriting your data access layer from. This class
+ * 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|class-string<T> */
+	protected $entityClass;
+
+	/** @var IDBConnection */
+	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 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) {
+		$this->db = $db;
+		$this->tableName = $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 14.0.0
+	 */
+	public function getTableName(): string {
+		return $this->tableName;
+	}
+
+
+	/**
+	 * 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 {
+		$qb = $this->db->getQueryBuilder();
+
+		$idType = $this->getParameterTypeForProperty($entity, 'id');
+
+		$qb->delete($this->tableName)
+			->where(
+				$qb->expr()->eq('id', $qb->createNamedParameter($entity->getId(), $idType))
+			);
+		$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 {
+		// get updated fields to save, fields have to be set using a setter to
+		// be saved
+		$properties = $entity->getUpdatedFields();
+
+		$qb = $this->db->getQueryBuilder();
+		$qb->insert($this->tableName);
+
+		// build the fields
+		foreach ($properties as $property => $updated) {
+			$column = $entity->propertyToColumn($property);
+			$getter = 'get' . ucfirst($property);
+			$value = $entity->$getter();
+
+			$type = $this->getParameterTypeForProperty($entity, $property);
+			$qb->setValue($column, $qb->createNamedParameter($value, $type));
+		}
+
+		$qb->executeStatement();
+
+		if ($entity->id === null) {
+			// When autoincrement is used id is always an int
+			$entity->setId($qb->getLastInsertId());
+		}
+
+		return $entity;
+	}
+
+	/**
+	 * Tries to creates a new entry in the db from an entity and
+	 * updates an existing entry if duplicate keys are detected
+	 * 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 Exception
+	 * @throws \InvalidArgumentException if entity has no id
+	 * @since 15.0.0
+	 */
+	public function insertOrUpdate(Entity $entity): Entity {
+		try {
+			return $this->insert($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
+	 *
+	 * @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 {
+		// 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']);
+
+		$qb = $this->db->getQueryBuilder();
+		$qb->update($this->tableName);
+
+		// build the fields
+		foreach ($properties as $property => $updated) {
+			$column = $entity->propertyToColumn($property);
+			$getter = 'get' . ucfirst($property);
+			$value = $entity->$getter();
+
+			$type = $this->getParameterTypeForProperty($entity, $property);
+			$qb->set($column, $qb->createNamedParameter($value, $type));
+		}
+
+		$idType = $this->getParameterTypeForProperty($entity, 'id');
+
+		$qb->where(
+			$qb->expr()->eq('id', $qb->createNamedParameter($id, $idType))
+		);
+		$qb->executeStatement();
+
+		return $entity;
+	}
+
+	/**
+	 * Returns the type parameter for the QueryBuilder for a specific property
+	 * 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|string
+	 * @since 16.0.0
+	 */
+	protected function getParameterTypeForProperty(Entity $entity, string $property) {
+		$types = $entity->getFieldTypes();
+
+		if (!isset($types[ $property ])) {
+			return IQueryBuilder::PARAM_STR;
+		}
+
+		switch ($types[ $property ]) {
+			case 'int':
+			case 'integer':
+				return IQueryBuilder::PARAM_INT;
+			case 'string':
+				return IQueryBuilder::PARAM_STR;
+			case 'bool':
+			case 'boolean':
+				return IQueryBuilder::PARAM_BOOL;
+			case 'blob':
+				return IQueryBuilder::PARAM_LOB;
+			case 'datetime':
+				return IQueryBuilder::PARAM_DATE;
+			case 'json':
+				return IQueryBuilder::PARAM_JSON;
+		}
+
+		return IQueryBuilder::PARAM_STR;
+	}
+
+	/**
+	 * Returns an db result and throws exceptions when there are more or less
+	 * results
+	 *
+	 * @param IQueryBuilder $query
+	 * @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 {
+		$result = $query->executeQuery();
+
+		$row = $result->fetch();
+		if ($row === false) {
+			$result->closeCursor();
+			$msg = $this->buildDebugMessage(
+				'Did expect one result but found none when executing', $query
+			);
+			throw new DoesNotExistException($msg);
+		}
+
+		$row2 = $result->fetch();
+		$result->closeCursor();
+		if ($row2 !== false) {
+			$msg = $this->buildDebugMessage(
+				'Did not expect more than one result when executing', $query
+			);
+			throw new MultipleObjectsReturnedException($msg);
+		}
+
+		return $row;
+	}
+
+	/**
+	 * @param string $msg
+	 * @param IQueryBuilder $sql
+	 * @return string
+	 * @since 14.0.0
+	 */
+	private function buildDebugMessage(string $msg, IQueryBuilder $sql): string {
+		return $msg .
+			': query "' . $sql->getSQL() . '"; ';
+	}
+
+
+	/**
+	 * 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
+	 * @psalm-return T the entity
+	 * @since 14.0.0
+	 */
+	protected function mapRowToEntity(array $row): Entity {
+		unset($row['DOCTRINE_ROWNUM']); // remove doctrine/dbal helper column
+		return \call_user_func($this->entityClass .'::fromRow', $row);
+	}
+
+
+	/**
+	 * Runs a sql query and returns an array of entities
+	 *
+	 * @param IQueryBuilder $query
+	 * @return Entity[] all fetched entities
+	 * @psalm-return T[] all fetched entities
+	 * @throws Exception
+	 * @since 14.0.0
+	 */
+	protected function findEntities(IQueryBuilder $query): array {
+		$result = $query->executeQuery();
+		try {
+			$entities = [];
+			while ($row = $result->fetch()) {
+				$entities[] = $this->mapRowToEntity($row);
+			}
+			return $entities;
+		} finally {
+			$result->closeCursor();
+		}
+	}
+
+
+	/**
+	 * Returns an db result and throws exceptions when there are more or less
+	 * results
+	 *
+	 * @param IQueryBuilder $query
+	 * @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 {
+		return $this->mapRowToEntity($this->findOneQuery($query));
+	}
+}

wedding-pics/lib/public/AppFramework/Db/TTransactional.php

@@ -0,0 +1,106 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright 2022 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @author 2022 Christoph Wurst <christoph@winzerhof-wurst.at>
+ *
+ * @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/>.
+ */
+
+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 ]);
+			}
+		}
+	}
+}