Problem/Motivation
Agree on a property naming pattern, so we can start standardizing on it.
Proposed resolution
(From #34, #55 ):
- Defined properties of a classed object should generally use $lowerCamel (This is already in coding standards.), unless something else would be most natural (That is, if they map directly to a DB field, then use the name of the DB field.).
- Non-property variables use $underscore_names. (This is already in coding standards.)
- Dynamic property names should be avoided whenever possible in favour of defined properties as those are far easier to debug. (This is already in coding standards, in practice if not in letter.) Dynamic property names on objects should use whatever is most natural. (That is, if they map directly to a DB field, then use the name of the DB field.)
- Classed objects that have a numeric unique identifier should provide access to that identifier via an id() method. The internal property name used for it is irrelevant for API purposes.
- Defined properties of a classed object that refer to the numeric unique identifier of that entity should be called id, i.e. $entity->id.
- Bare variables that refer to the numeric unique identifier of an entity should be in the form $entity_id. That is, $node_id, $user_id, etc.
- Defined properties that refer to the string unique identifier (machine name) of an object should be called name, i.e. $view->name, $filter->name.
- Bare variables that refer to the string unique identifier (machine name) of an object should be in the form $type_name. That is, $view_name, $filter_name, etc.
- Defined properties that refer to an entity other than the the object to which that property belongs should use a $entity_id (i.e. user_id, node_id reference name if the relation to the referenced entity is clear. That is, the user to which the entity belongs should be always referenced using the property user_id. (This improves DX as one does not need to remember slightly different relation names (user vs. author vs. owner vs. ..).
- Defined properties that refer to an entity other than the the object to which that property belongs should use a describing name $relation_id (i.e. parent_id, issue_id) if the relation to the referenced entity would not be clear else.
- The use of old-style abbreviated variables is discouraged. Eg, nid, uid, vid, etc. While shorter to type, they are less self-documenting and at Drupal's current scale frequently run into namespace collisions.
And taken from #42 about how the pattern should be applied:
- Entities handled by Drupal modules should use Drupal's convention for property names (see above)..
- Entities originating from remote systems should not mess-up with the data to match the convention, but integrate the data as is. So developers used to that data structures get the data as they know it.
Note: See
#1301106: Rely on methods to access entity properties [policy, no patch] →
for the related discussion whether properties should be public accessible or not.
Remaining tasks
Write documentation.
User interface changes
None.
API changes
For now none. The first step is to agree on a pattern we can use when building new stuff. Changing existing stuff to match the pattern is the second step and should be done in other issues.
Original report by fago
In
#1216094: We call too many things 'language', clean that up →
the question of how we name referencing properties came up. While we have nid, uid, cid, tid and others, field API has started doing entity_id, field_id, ... (while I remember we had etid earlier).
from #96:
And yes, field API uses field_id and entitiy_id. Is that where Drupal is heading? Then why not $language_id? We are trying to have consistency here, right? Drupal used to be consistent in Xid's. That is clearly not 100% applied to some systems, but is our most common pattern for universally used identifiers. We want language to be a universal thing like that. It will be eeeeeverywhere. If our new pattern is in the field API, then are we going to ever have user_id and node_id in core? Is that the new consistency we are striving for or is entity/field API an exception, not a rule?
I think its time to stop doing "*id" pattern. That pattern ease writing db-queries (easy joins!) for the cost of a non-intuitive drupalism one has to get to know first + they quickly run into collisions. We even have already collisions in core (sid -> session id, search item id).
Who is hand-writing lots of sql-queries today? The minority. Given the entity/field api, efq and views this is not really an issue, and with nosql finally obsolete. Instead we should focus on today developers needs and make sure they can easily understand what the property is about by just reading its name!
So let's agree upon a good pattern and start adopting it! I know changing everything now is out of question, but still agreeing upon a patter for anything new now helps.
Patterns that come to my mind are:
The old uid, cid, nid, pid, tid, sid, .. pattern.
The mentioned Field-API pattern: "field_id", "user_id", "node_id", "language_id"..
"user_id" is used to refer to a user entity, while the user would be still $user->uid or $user->id
The names are describing, but rather verbose. Also by default, we would end up with lots of _id properties in objects, e.g. assuming "comment" would use the pattern:
$comment->node_id
$comment->parent_id
$comment->user_id (or $comment->author_id?)
Use the general property name without an '_id' suffix, i.e. "field", "user", "node".
So "user" is used to refer to a user entity, while the user would be still $user->uid or $user->id.
The names are describing, but not as verbose as 2). The names do not tell us the properties contain only ids though. However, I don't think that's an issue as long it's consistent. Developer's would know every referencing property contains the id, not the object. And in the DB level it's pretty much obvious "node" would have to hold an id either.
So applied to the comment example we'd have
// Properties are holding ids.
$comment->node
$comment->parent
$comment->user (or $comment->author ?)
Personally, I like option 3). It would be also consistent with manually created fields, e.g. $node->tags doesn't hold objects either. Thoughts?