Spin off from
#2267753: ContentEntityDatabaseStorage::mapToStorageRecord hard-codes $entity->$name->value →
:
The exact semantics of "the main property for a field type" has alawys been a bit vague. IIRC it's been initially introduced to support AllowedValuesConstraint, and has been since then used for a couple other things.
FieldItemInterface::mainPropertyName() basically only says : "Some field types consist "mainly" (whatever that means) of one main property, some others don't and then it's NULL". This doesn't help field type developpers understand what to put in their implementation of mainPropertyName() - "what's my "main property", do I even have one ?".
The exact semantics currently only lie in actual code uses :
- AllowedValuesConstraintValidator only supports field types that have a "main property" (raises an exception if NULL).
--> consequence for Field Type authors : your field type can use AllowedValuesConstraint only if it has a "main property"
- ContentEntityBase::getEntityKey() assumes all entity keys use a field type that has a "main property", and will fatal if not.
--> consequence for Entity Type authors : your "entity keys" can only use field types that have a "main property".
- EntityQuery's Tables.php uses the "main property" of fields used in a condition - not clear what happens if the field type doesn't have one.
--> consequence : ??
-
#2267753: ContentEntityDatabaseStorage::mapToStorageRecord hard-codes $entity->$name->value →
adds : the "main property" is the one that gets stored for base fields in base tables when the table schema is designed such that there's a single column for the field, named after the field.
I guess that this use will be mostly moot when base table schemas are auto-generated ?
--> meanwhile, consequence for Entity Type authors : beware of field types when designing your base table schemas ?
We should try to convey more of that in the doc for FieldItemInterface::mainPropertyName().