Use the term 'entity' instead of 'object'

I have no problem with defining "entity" as "one of the data items handled by the Drupal API". Although I want a stricter definition (I need to be able to answer the question "is $foo an entity or not" unambiguously) and I want that definition documented somewhere.

But here's my question for this issue: Are all fieldable objects entities? If they are, then it seems to me that the word "entity" is such an empty term that it has no reason to exist. And if they aren't, the word 'entity' needs to be replaced in many places, because the use of that word is misleading: Fields aren't restricted to entities.

It's clear that, by definition, nodes, users, taxonomy, and files are all entities. But suppose I want to attach some fields to an arbitrary Flickr photo. Let's assume that Flickr photos have a unique numerical ID that's embedded in the URL, so whenever a user hands me a Flickr photo URL I can just create an object and pass it to field_attach_load():

  $photo = new StdClass();
  $photo->flickr_id = 3159030384;
  $photo->bundle = 'flickr_photo';
  field_attach_load('flickr_photo', $photo);

This will work fine provided that $photo is a fieldable object. But, so long as my custom module defines a hook_fieldable_info() that returns something like this:

return array(
  'flickr_photo' => array(
     'name' => t('Flickr photo'),
     'id key' => 'flickr_id',
     'revision key' => NULL,
     'bundle key' => 'bundle',
     'cacheable' => TRUE,
     'bundles' => array('flickr'),
  ),
);

$photo is a fieldable object, yes?

But is $photo an entity? Surely not, right? There is no Drupal API that handles such objects. They don't have an API or even a class. I made them up myself in fourteen lines of PHP, some of which I believe are redundant. ;) If we declare that objects like $photo are entities, then I declare that the word "entity" is useless, certainly not worth the hassle of teaching it to all new Drupal programmers. Let's just call these things by the name they already have: "objects".

Okay, I obviously need to read through #460320 in more detail. I missed the key phrase, where hook_entity_info() replaced hook_fieldable_info() and it suddenly became a requirement that every fieldable item also be an entity.

At first glance, I'm very dubious of that. I thought the ability to add fields to a simple StdClass(), without having to deal with or even know about the semantics of "entities", was a nice feature, and I hope there's a big payoff to getting rid of that feature. But, again, I haven't read the other patch.

Sounds like the right thing to do might be to postpone this issue until #460320 is hashed out.

Okay, I have gone back and forth several times on this, but I think I might be ready to concede that "entity" is a useful term. Perhaps useful enough that it's worth creating yet another Drupal jargon word.

Here's the one-line take-home version of my proposed definition:

• An "entity" is an object which is identified by a unique ID that is stored inside it.

Here's some fleshing out of the definition:

• Each entity has a type. Entity types must be declared to Drupal using hook_entity_info().
• Entities have a single "id" field, and may also have a "revision" field. The (id, revision) combination uniquely identifies the entity. The field names do not actually need to be "id" and "revision"; they are defined for each entity type by hook_entity_info(). For example, a node entity has its ID in $node->nid and its revision in $node->revision, while user entities have $user->uid as their ID field.
• Entities are the only objects that can be fieldable, though not all entity types are necessarily fieldable.
• Entities may be loadable using Drupal's loading API, but not all entity types are necessarily loadable.
• (...insert future optional properties of entities here...)

I was not convinced that the word "entity" was useful until I realized that the one common factor between the four subtypes of entity which we have mentioned so far (fieldable vs non-fieldable, loadable vs non-loadable) is that they all require PHP objects with a unique ID. And I'll accept that that concept deserves its own word. Indeed, now that I think about it, I've been looking for that word for a while.

So I'm altering the suggested agenda of this issue: If we want to go with the term "entity", we need to use it everywhere, we need to put it in the glossary, we need to define it in the Doxygen docs. And we need to do these things as soon as we can, perhaps even without waiting for #460320 to land. Right now all the word is doing is confusing people like me who try to read the Field code.