Merge pull request #46476 from nextcloud/enh/noid/migration-attributes

Migration Attributes

14 files changed, 693 insertions, 0 deletions

diff --git a/lib/public/Migration/Attributes/AddColumn.php b/lib/public/Migration/Attributes/AddColumn.php
new file mode 100644
index 00000000000..8d16b9b6e8d
--- /dev/null
+++ b/lib/public/Migration/Attributes/AddColumn.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use Attribute;
+
+/**
+ * attribute on new column creation
+ *
+ * @since 30.0.0
+ */
+#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_CLASS)]
+class AddColumn extends ColumnMigrationAttribute {
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function definition(): string {
+		$type = is_null($this->getType()) ? '' : ' (' . $this->getType()->value . ')';
+		return empty($this->getName()) ?
+			'Addition of a new column' . $type . ' to table \'' . $this->getTable() . '\''
+			: 'Addition of column \'' . $this->getName() . '\'' . $type . ' to table \'' . $this->getTable() . '\'';
+	}
+}
diff --git a/lib/public/Migration/Attributes/AddIndex.php b/lib/public/Migration/Attributes/AddIndex.php
new file mode 100644
index 00000000000..ee22fe7f128
--- /dev/null
+++ b/lib/public/Migration/Attributes/AddIndex.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use Attribute;
+
+/**
+ * attribute on index creation
+ *
+ * @since 30.0.0
+ */
+#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_CLASS)]
+class AddIndex extends IndexMigrationAttribute {
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function definition(): string {
+		$type = is_null($this->getType()) ? '' : ' (' . $this->getType()->value . ')';
+		return 'Addition of a new index' . $type . ' to table \'' . $this->getTable() . '\'';
+	}
+}
diff --git a/lib/public/Migration/Attributes/ColumnMigrationAttribute.php b/lib/public/Migration/Attributes/ColumnMigrationAttribute.php
new file mode 100644
index 00000000000..30b6fe008e6
--- /dev/null
+++ b/lib/public/Migration/Attributes/ColumnMigrationAttribute.php
@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use JsonSerializable;
+
+/**
+ * generic class related to migration attribute about column changes
+ *
+ * @since 30.0.0
+ */
+class ColumnMigrationAttribute extends MigrationAttribute implements JsonSerializable {
+	/**
+	 * @param string $table name of the database table
+	 * @param string $name name of the column
+	 * @param ColumnType|null $type type of the column
+	 * @param string $description description of the migration
+	 * @param array $notes notes about the migration/column
+	 * @since 30.0.0
+	 */
+	public function __construct(
+		string $table,
+		private string $name = '',
+		private ?ColumnType $type = null,
+		string $description = '',
+		array $notes = [],
+	) {
+		parent::__construct($table, $description, $notes);
+	}
+
+	/**
+	 * @param string $name
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function setName(string $name): self {
+		$this->name = $name;
+		return $this;
+	}
+
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function getName(): string {
+		return $this->name;
+	}
+
+	/**
+	 * @param ColumnType|null $type
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function setType(?ColumnType $type): self {
+		$this->type = $type;
+		return $this;
+	}
+
+	/**
+	 * @return ColumnType|null
+	 * @since 30.0.0
+	 */
+	public function getType(): ?ColumnType {
+		return $this->type;
+	}
+
+	/**
+	 * @param array $data
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function import(array $data): self {
+		parent::import($data);
+		$this->setName($data['name'] ?? '');
+		$this->setType(ColumnType::tryFrom($data['type'] ?? ''));
+		return $this;
+	}
+
+	/**
+	 * @return array
+	 * @since 30.0.0
+	 */
+	public function jsonSerialize(): array {
+		return array_merge(
+			parent::jsonSerialize(),
+			[
+				'name' => $this->getName(),
+				'type' => $this->getType() ?? '',
+			]
+		);
+	}
+}
diff --git a/lib/public/Migration/Attributes/ColumnType.php b/lib/public/Migration/Attributes/ColumnType.php
new file mode 100644
index 00000000000..23445e822b6
--- /dev/null
+++ b/lib/public/Migration/Attributes/ColumnType.php
@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+/**
+ * enum ColumnType based on OCP\DB\Types
+ *
+ * @see \OCP\DB\Types
+ * @since 30.0.0
+ */
+enum ColumnType : string {
+	/** @since 30.0.0 */
+	case BIGINT = 'bigint';
+	/** @since 30.0.0 */
+	case BINARY = 'binary';
+	/** @since 30.0.0 */
+	case BLOB = 'blob';
+	/** @since 30.0.0 */
+	case BOOLEAN = 'boolean';
+	/** @since 30.0.0 */
+	case DATE = 'date';
+	/** @since 30.0.0 */
+	case DATETIME = 'datetime';
+	/** @since 30.0.0 */
+	case DECIMAL = 'decimal';
+	/** @since 30.0.0 */
+	case FLOAT = 'float';
+	/** @since 30.0.0 */
+	case INTEGER = 'integer';
+	/** @since 30.0.0 */
+	case SMALLINT = 'smallint';
+	/** @since 30.0.0 */
+	case STRING = 'string';
+	/** @since 30.0.0 */
+	case TEXT = 'text';
+	/** @since 30.0.0 */
+	case TIME = 'time';
+	/** @since 30.0.0 */
+	case JSON = 'json';
+}
diff --git a/lib/public/Migration/Attributes/CreateTable.php b/lib/public/Migration/Attributes/CreateTable.php
new file mode 100644
index 00000000000..df0418fa4bc
--- /dev/null
+++ b/lib/public/Migration/Attributes/CreateTable.php
@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use Attribute;
+
+/**
+ * attribute on table creation
+ *
+ * @since 30.0.0
+ */
+#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_CLASS)]
+class CreateTable extends TableMigrationAttribute {
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function definition(): string {
+		$definition = 'Creation of new table \'' . $this->getTable() . '\'';
+		$definition .= empty($this->getColumns()) ? '' : ' with columns ' . implode(', ', $this->getColumns());
+		return $definition;
+	}
+}
diff --git a/lib/public/Migration/Attributes/DropColumn.php b/lib/public/Migration/Attributes/DropColumn.php
new file mode 100644
index 00000000000..1de0ba58489
--- /dev/null
+++ b/lib/public/Migration/Attributes/DropColumn.php
@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use Attribute;
+
+/**
+ * attribute on column drop
+ *
+ * @since 30.0.0
+ */
+#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_CLASS)]
+class DropColumn extends ColumnMigrationAttribute {
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function definition(): string {
+		return empty($this->getName()) ?
+			'Deletion of a column from table \'' . $this->getTable() . '\''
+			: 'Deletion of column \'' . $this->getName() . '\' from table \'' . $this->getTable() . '\'';
+	}
+}
diff --git a/lib/public/Migration/Attributes/DropIndex.php b/lib/public/Migration/Attributes/DropIndex.php
new file mode 100644
index 00000000000..2702cbed9a7
--- /dev/null
+++ b/lib/public/Migration/Attributes/DropIndex.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use Attribute;
+
+/**
+ * attribute on index drop
+ *
+ * @since 30.0.0
+ */
+#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_CLASS)]
+class DropIndex extends IndexMigrationAttribute {
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function definition(): string {
+		return 'Deletion of an index from table \'' . $this->getTable() . '\'';
+	}
+}
diff --git a/lib/public/Migration/Attributes/DropTable.php b/lib/public/Migration/Attributes/DropTable.php
new file mode 100644
index 00000000000..e90e4804a3c
--- /dev/null
+++ b/lib/public/Migration/Attributes/DropTable.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use Attribute;
+
+/**
+ * attribute on table drop
+ *
+ * @since 30.0.0
+ */
+#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_CLASS)]
+class DropTable extends TableMigrationAttribute {
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function definition(): string {
+		return 'Deletion of table \'' . $this->getTable() . '\'';
+	}
+}
diff --git a/lib/public/Migration/Attributes/GenericMigrationAttribute.php b/lib/public/Migration/Attributes/GenericMigrationAttribute.php
new file mode 100644
index 00000000000..6f187635ff7
--- /dev/null
+++ b/lib/public/Migration/Attributes/GenericMigrationAttribute.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use JsonSerializable;
+
+/**
+ * generic entry, used to replace migration attribute not yet known in current version
+ * but used in a future release
+ *
+ * @since 30.0.0
+ */
+class GenericMigrationAttribute extends MigrationAttribute implements JsonSerializable {
+	/**
+	 * @param array $details
+	 * @since 30.0.0
+	 */
+	public function __construct(
+		private readonly array $details = []
+	) {
+		parent::__construct(
+			$details['table'] ?? '',
+			$details['description'] ?? '',
+			$details['notes'] ?? []
+		);
+	}
+
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function definition(): string {
+		return json_encode($this->jsonSerialize(), JSON_UNESCAPED_SLASHES);
+	}
+
+	/**
+	 * @return array
+	 * @since 30.0.0
+	 */
+	public function jsonSerialize(): array {
+		return $this->details;
+	}
+}
diff --git a/lib/public/Migration/Attributes/IndexMigrationAttribute.php b/lib/public/Migration/Attributes/IndexMigrationAttribute.php
new file mode 100644
index 00000000000..88b60a564b3
--- /dev/null
+++ b/lib/public/Migration/Attributes/IndexMigrationAttribute.php
@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use JsonSerializable;
+
+/**
+ * generic class related to migration attribute about index changes
+ *
+ * @since 30.0.0
+ */
+class IndexMigrationAttribute extends MigrationAttribute implements JsonSerializable {
+	/**
+	 * @param string $table name of the database table
+	 * @param IndexType|null $type type of the index
+	 * @param string $description description of the migration
+	 * @param array $notes notes abour the migration/index
+	 * @since 30.0.0
+	 */
+	public function __construct(
+		string $table,
+		private ?IndexType $type = null,
+		string $description = '',
+		array $notes = [],
+	) {
+		parent::__construct($table, $description, $notes);
+	}
+
+	/**
+	 * @param IndexType|null $type
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function setType(?IndexType $type): self {
+		$this->type = $type;
+		return $this;
+	}
+
+	/**
+	 * @return IndexType|null
+	 * @since 30.0.0
+	 */
+	public function getType(): ?IndexType {
+		return $this->type;
+	}
+
+	/**
+	 * @param array $data
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function import(array $data): self {
+		parent::import($data);
+		$this->setType(IndexType::tryFrom($data['type'] ?? ''));
+		return $this;
+	}
+
+	/**
+	 * @return array
+	 * @since 30.0.0
+	 */
+	public function jsonSerialize(): array {
+		return array_merge(
+			parent::jsonSerialize(),
+			[
+				'type' => $this->getType() ?? '',
+			]
+		);
+	}
+}
diff --git a/lib/public/Migration/Attributes/IndexType.php b/lib/public/Migration/Attributes/IndexType.php
new file mode 100644
index 00000000000..45c88d81041
--- /dev/null
+++ b/lib/public/Migration/Attributes/IndexType.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+/**
+ * type of index
+ *
+ * @since 30.0.0
+ */
+enum IndexType : string {
+	/** @since 30.0.0 */
+	case PRIMARY = 'primary';
+	/** @since 30.0.0 */
+	case INDEX = 'index';
+	/** @since 30.0.0 */
+	case UNIQUE = 'unique';
+}
diff --git a/lib/public/Migration/Attributes/MigrationAttribute.php b/lib/public/Migration/Attributes/MigrationAttribute.php
new file mode 100644
index 00000000000..5b4550c4db5
--- /dev/null
+++ b/lib/public/Migration/Attributes/MigrationAttribute.php
@@ -0,0 +1,118 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use JsonSerializable;
+
+/**
+ * @since 30.0.0
+ */
+class MigrationAttribute implements JsonSerializable {
+	/**
+	 * @param string $table name of the database table
+	 * @param string $description description of the migration
+	 * @param array $notes notes about the migration
+	 * @since 30.0.0
+	 */
+	public function __construct(
+		private string $table,
+		private string $description = '',
+		private array $notes = [],
+	) {
+	}
+
+	/**
+	 * @param string $table
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function setTable(string $table): self {
+		$this->table = $table;
+		return $this;
+	}
+
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function getTable(): string {
+		return $this->table;
+	}
+
+	/**
+	 * @param string $description
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function setDescription(string $description): self {
+		$this->description = $description;
+		return $this;
+	}
+
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function getDescription(): string {
+		return $this->description;
+	}
+
+	/**
+	 * @param array $notes
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function setNotes(array $notes): self {
+		$this->notes = $notes;
+		return $this;
+	}
+
+	/**
+	 * @return array
+	 * @since 30.0.0
+	 */
+	public function getNotes(): array {
+		return $this->notes;
+	}
+
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function definition(): string {
+		return json_encode($this->jsonSerialize(), JSON_UNESCAPED_SLASHES);
+	}
+
+	/**
+	 * @param array $data
+	 *
+	 * @return self
+	 * @since 30.0.0
+	 */
+	public function import(array $data): self {
+		return $this->setDescription($data['description'] ?? '')
+					->setNotes($data['notes'] ?? []);
+	}
+
+	/**
+	 * @return array
+	 * @since 30.0.0
+	 */
+	public function jsonSerialize(): array {
+		return [
+			'class' => get_class($this),
+			'table' => $this->getTable(),
+			'description' => $this->getDescription(),
+			'notes' => $this->getNotes()
+		];
+	}
+}
diff --git a/lib/public/Migration/Attributes/ModifyColumn.php b/lib/public/Migration/Attributes/ModifyColumn.php
new file mode 100644
index 00000000000..ef7250ffb34
--- /dev/null
+++ b/lib/public/Migration/Attributes/ModifyColumn.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use Attribute;
+
+/**
+ * attribute on column modification
+ *
+ * @since 30.0.0
+ */
+#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_CLASS)]
+class ModifyColumn extends ColumnMigrationAttribute {
+	/**
+	 * @return string
+	 * @since 30.0.0
+	 */
+	public function definition(): string {
+		$type = is_null($this->getType()) ? '' : ' to ' . $this->getType()->value;
+		return empty($this->getName()) ?
+			'Modification of a column from table \'' . $this->getTable() . '\'' . $type
+			: 'Modification of column \'' . $this->getName() . '\' from table \'' . $this->getTable() . '\'' . $type;
+	}
+}
diff --git a/lib/public/Migration/Attributes/TableMigrationAttribute.php b/lib/public/Migration/Attributes/TableMigrationAttribute.php
new file mode 100644
index 00000000000..0776e50387e
--- /dev/null
+++ b/lib/public/Migration/Attributes/TableMigrationAttribute.php
@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Migration\Attributes;
+
+use JsonSerializable;
+
+/**
+ * generic class related to migration attribute about table changes
+ *
+ * @since 30.0.0
+ */
+class TableMigrationAttribute extends MigrationAttribute implements JsonSerializable {
+	/**
+	 * @param string $table name of the database table
+	 * @param array $columns list of columns
+	 * @param string $description description of the migration
+	 * @param array $notes notes about the migration/table
+	 * @since 30.0.0
+	 */
+	public function __construct(
+		string $table,
+		private array $columns = [],
+		string $description = '',
+		array $notes = [],
+	) {
+		parent::__construct($table, $description, $notes);
+	}
+
+	/**
+	 * @param array $columns
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function setColumns(array $columns): self {
+		$this->columns = $columns;
+		return $this;
+	}
+
+	/**
+	 * @return array
+	 * @since 30.0.0
+	 */
+	public function getColumns(): array {
+		return $this->columns;
+	}
+
+	/**
+	 * @param array $data
+	 *
+	 * @return $this
+	 * @since 30.0.0
+	 */
+	public function import(array $data): self {
+		parent::import($data);
+		$this->setColumns($data['columns'] ?? []);
+		return $this;
+	}
+
+	/**
+	 * @return array
+	 * @since 30.0.0
+	 */
+	public function jsonSerialize(): array {
+		return array_merge(
+			parent::jsonSerialize(),
+			[
+				'columns' => $this->getColumns(),
+			]
+		);
+	}
+}