refactor(db): Introduce new API for entities

.gitignore

@@ -80,3 +80,5 @@ typings/
 
 # VScode settings
 .vscode/settings.json
+
+tests/.phpunit.cache/test-results

lib/AppFramework/Db/Attribute/Column.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH
+ * SPDX-FileContributor: Carl Schwan
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Maps\AppFramework\Db\Attribute;
+
+use Attribute;
+use OCP\AppFramework\Attribute\Consumable;
+use OCP\DB\Types;
+
+/**
+ * Attribute for mapping a property in an entity to a database column.
+ *
+ * ```php
+ * #[Entity(name: 'my_entity']
+ * final class MyEntity {
+ *     #[Column(name: 'my_column', type: Types::String, default: '')]
+ *     public string $myColumn = '';
+ * }
+ * ```
+ *
+ * @since 35.0.0
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+#[Consumable(since: '35.0.0')]
+final readonly class Column {
+	public function __construct(
+		/** @param non-empty-string $name The name of the column in the database. */
+		public string $name,
+		/** @param Types::* $type The type of the column in the database. */
+		public string $type,
+		/** @param ?int $length The length of the column (relevant for Types::STRING) */
+		public ?int $length = null,
+		/** @param bool $nullable Whether the column is nullable in the database */
+		public bool $nullable = false,
+		/** @param mixed $default The default value for the column in the database. */
+		public mixed $default = null,
+	) {
+	}
+}

lib/AppFramework/Db/Attribute/Entity.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH
+ * SPDX-FileContributor: Carl Schwan
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Maps\AppFramework\Db\Attribute;
+
+use Attribute;
+use OCP\AppFramework\Attribute\Consumable;
+
+/**
+ * Attribute for marking a class as an entity mapped to some database table.
+ *
+ * ```php
+ * #[Entity(name: 'my_entity')]
+ * final class MyEntity {
+ *     #[Column(name: 'my_column', type: Types::String, default: '')]
+ *     public string $myColumn = '';
+ * }
+ * ```
+ *
+ * @since 35.0.0
+ */
+#[Attribute(Attribute::TARGET_CLASS)]
+#[Consumable(since: '35.0.0')]
+final readonly class Entity {
+	public function __construct(
+		/** @param non-empty-string $name */
+		public string $name,
+	) {
+	}
+}

lib/AppFramework/Db/Attribute/Id.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH
+ * SPDX-FileContributor: Carl Schwan
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Maps\AppFramework\Db\Attribute;
+
+use Attribute;
+use OCP\AppFramework\Attribute\Consumable;
+use OCP\Snowflake\ISnowflakeGenerator;
+
+/**
+ * Attribute for marking a column as a primary id.
+ *
+ * ```php
+ * #[Entity(name: 'my_entity']
+ * final class MyEntity {
+ *     #[Id(generatorClass: ISnowflakeGenerator::class)]
+ *     #[Column(name: 'id', type: Types::BIGINT)]
+ *     public string $id = '';
+ * }
+ * ```
+ *
+ * @since 35.0.0
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+#[Consumable(since: '35.0.0')]
+final readonly class Id {
+	public function __construct(
+		/** @param class-string<ISnowflakeGenerator> $generatorClass */
+		public ?string $generatorClass = null,
+	) {
+	}
+}