This email serves to outline planned changed to the Entity class hierarchy
so they can be held into account for development. This has no immediate
impact on user facing functionality.
Right now we have an Entity class that holds an EntityId, a Fingerprint and
a list of Claim. Item derives from Entity and adds a list of SiteLink, as
well as changing the list of Claim to a list of Statement. Property also
derives from Entity and adds only a property type field. In the future we
will have more types of entities, such as a QueryEntity which holds a query
description and entities for Wikimedia Commons.
The problem is that these different types of entities are made up of
different things, and the intersection between all of them is only that
they have an id. Hence the code sharing by inheritance approach we
currently have is definitely a mistake. The thing we are aiming for is to
use more specific interfaces and the things that make up entities.
Example: You have a list of items and properties, and you want to store
their terms into a database table for lookup purposes. Rather than having
the "term store" take an Entity and so increase the assumption that all
entities have terms, only require what is strictly needed. In this case an
EntityId and a Fingerprint (which contains the terms).
$termStore->insertTermsForEntity( Entity $entity )
$termStore->insertTermsForEntity( EntityId $id, Fingerprint $fingerprint )
Any type hint against Entity suggests an assumption we already know will
not hold. Hence avoid parameters and fields of type Entity. Mirroring the
Entity class hierarchy, such as EntityDiff and ItemDiff, is another thing
to avoid. New occurrences of any of these should not be added, so please -1
any commits that do so.
To avoid confusion: it is perfectly fine to have a parameter or field of a
concrete entity type, such as Item or Property.
Jeroen De Dauw - http://www.bn2vs.com
Software craftsmanship advocate
Evil software architect at Wikimedia Germany