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]

Please document why no DI (loop I suppose?)

[CarlSchwan]

Mostly because EntityManager is a private API (for now at least) and so it makes it possible to create a Repository without depending on it

[come-nc]

Ah yeah, because child classes call the parent constructor so it needs public API only in its parameters.
If we put the entity class into a const that child classes override or something like that we may avoid the need for a constructor in most child classes, but I guess that won’t always work, some may want a constructor anyway. Not sure what the pretty solution is.

[CarlSchwan]

I now use a const and made the constructor internal

[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 👏

[ChristophWurst]

It is a rare case, but do we want to allow composite primary keys? Example would be an n:m mapping table. It could just use the two foreign keys as primary key. If we enforce a single primary key column then it needs a third column.

[CarlSchwan]

good point, doctrine does support this: https://www.doctrine-project.org/projects/doctrine-orm/en/3.6/tutorials/composite-primary-keys.html#primitive-types-only

So let's see if I can drop the requirement of only one Id attribute