feat(entity): Provide a new API for entities

[CarlSchwan]

Entity are now simple data object with attributes for the database mapping. They are manipulated via a Repository which reads the attributes to insert, update, delete and queries the PDO from the database.

Using attributes makes it easier to extends in the future with relations (ManyToMany, OneToMany, OneToOne, ...).

The design of the Repository is based on a mix between the Doctrine ORM repository while keeping some methods from the QBMapper for easier porting.

Example of a entity

#[Entity(name: 'twofactor_backupcodes')]
final class BackupCode {
	#[Id(generatorClass: IGenerator::class)]
	#[Column(name: 'id', type: Types::STRING, length: 64, nullable: false)]
	public ?string $id = null;

	#[Column(name: 'user_id', type: Types::STRING, length: 64, nullable: false)]
	public string $userId;

	#[Column(name: 'code', type: Types::STRING, length: 128, nullable: false)]
	public string $code;

	#[Column(name: 'used', type: Types::SMALLINT, nullable: false, default: 0)]
	public int $used = 0;
}

Supported

• OneToOne relationship
• ManyToOne relationship
• Autoincremented ID
• Snowflake ID
• Basic queries
• Same feature coverage as the old Entities so it's a drop-in replacement

Missing but for later

• Support for OneToMany relationship
• Lazy evaluated relationship
• Support for UnitOfWork https://www.doctrine-project.org/projects/doctrine-orm/en/3.6/reference/unitofwork.html#doctrine-internals-explained
• Support for generating migrations (for the unit tests there is some code to create and remove table already)
• Enums

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)
• Labels added where applicable (ex: bug/enhancement, 3. to review, feature component)
• Milestone added for target branch/version (ex: 32.x for stable32)

[blizzz]

Would have preferred the new API and the reference implementation in backup codes and Tagging to be two different commits. But cool.

What do you think of a CacheEnabled repository next to it (that wraps the Repository and just has a runtime cache)? Have a mapper with such functionality in tables, and saw it on at least another app as well, might be worth to have something like this implemented once properly?

[CarlSchwan]

Would have preferred the new API and the reference implementation in backup codes and Tagging to be two different commits. But cool.

Currently it's more of a prototype, I'll split that in multiple commits.

What do you think of a CacheEnabled repository next to it (that wraps the Repository and just has a runtime cache)? Have a mapper with such functionality in tables, and saw it on at least another app as well, might be worth to have something like this implemented once properly?

Yes that could make sense. That I also saw in multiple apps is the relation stuff: https://github.com/nextcloud/deck/blob/main/lib/Db/RelationalEntity.php which could be quite handy

[come-nc]

Looks promising.

[come-nc]

How is the modified columns detection replaced?
I think the old API was keeping track of which values were modified and I did not see how it is done here, as properties are public and set directly.

[CarlSchwan]

How is the modified columns detection replaced? I think the old API was keeping track of which values were modified and I did not see how it is done here, as properties are public and set directly.

There is no detection, all properties are updated all the time. IHMO this is negligible in term of performance/network compared to the effort required to track changes via something similar to Doctrine Unit of Work as there isn't super frequent updates and for high performance code, it's best to anyway write queries manually requesting only what is needed and writing only what changed.

See https://www.doctrine-project.org/projects/doctrine-orm/en/3.6/reference/unitofwork.html At the moment, since the public API is minimal, we could add support for that later on.

[ChristophWurst]

Quick review

Good stuff 👏

[Copilot]

Pull request overview

Introduces an attribute-driven ORM API and migrates tagging and two-factor backup-code persistence to it.

Changes:

• Adds entity metadata, repositories, relations, and schema helpers.
• Migrates tags and backup codes from QBMapper.
• Adds ORM tests, static-analysis configuration, and autoload entries.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
tests/lib/TagsTest.php	Resolves the new mapper through DI.
tests/lib/AppFramework/ORM/RepositoryTest.php	Tests repository and relation behavior.
psalm-strict.xml	Enables strict ORM analysis.
lib/public/ITags.php	Tightens tag API types.
lib/public/AppFramework/ORM/Repository.php	Adds the public repository API.
lib/public/AppFramework/ORM/Attribute/OneToOne.php	Defines one-to-one metadata.
lib/public/AppFramework/ORM/Attribute/ManyToOne.php	Defines many-to-one metadata.
lib/public/AppFramework/ORM/Attribute/JoinColumn.php	Defines relation columns.
lib/public/AppFramework/ORM/Attribute/Id.php	Defines primary-key metadata.
lib/public/AppFramework/ORM/Attribute/Entity.php	Defines entity metadata.
lib/public/AppFramework/ORM/Attribute/Column.php	Defines column metadata.
lib/public/AppFramework/Db/QBMapper.php	Corrects documentation grammar.
lib/private/Tags.php	Adapts tags to data objects.
lib/private/TagManager.php	Clarifies documentation.
lib/private/Tagging/TagMapper.php	Migrates tags to Repository.
lib/private/Tagging/Tag.php	Converts tags to attributed entities.
lib/private/AppFramework/ORM/PropertyAttributes.php	Aggregates property metadata.
lib/private/AppFramework/ORM/EntityManager.php	Implements ORM persistence and schemas.
lib/private/AppFramework/ORM/EntityInfo.php	Reflects and validates entities.
lib/composer/composer/autoload_static.php	Registers ORM classes.
lib/composer/composer/autoload_classmap.php	Registers ORM classes.
build/rector-strict.php	Enables strict Rector checks.
build/psalm-baseline.xml	Removes resolved tag suppressions.
apps/twofactor_backupcodes/tests/Unit/Service/BackupCodeStorageTest.php	Updates storage unit tests.
apps/twofactor_backupcodes/tests/Db/BackupCodeMapperTest.php	Updates mapper integration tests.
apps/twofactor_backupcodes/lib/Service/BackupCodeStorage.php	Uses repository operations.
apps/twofactor_backupcodes/lib/Listener/UserDeleted.php	Uses the renamed deletion method.
apps/twofactor_backupcodes/lib/Db/BackupCodeMapper.php	Migrates backup codes to Repository.
apps/twofactor_backupcodes/lib/Db/BackupCode.php	Converts backup codes to attributed entities.

Suppressed comments (1)

lib/public/ITags.php:57

• The updated PHP example still uses assignment syntax inside the array (=), so the documented snippet is invalid PHP. Use => for every key/value pair.

	 * 	['id' => 1, 'name' = 'Second tag', 'owner' = 'User B', 'type' => 'tagtype'],

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.