Where is the API for custom entities documented?

Another end-user here. I have been attempting to use the UUID module's own implementations for core entities along with the uuid.api.php file. Haven't had much luck but I would absolutely contribute docs if I sort it out.

* http://cgit.drupalcode.org/uuid/tree/uuid.inc
* http://cgit.drupalcode.org/uuid/tree/uuid.entity.inc
* http://cgit.drupalcode.org/uuid/tree/uuid.core.inc
* http://cgit.drupalcode.org/uuid/tree/uuid.api.php

I see lots of explanations for the mechanics of various functions, but the comments unfortunately don't tell an unfamiliar user why each function is needed, or the order in which they need to be set up. My blanket approach of just copying all functions that begin with node_entity_uuid_XXX and attempting to customize them didn't get me any results yet.

Additionally, the API file refers to functions that I can't seem to find. The only occurrence is the reference itself:

chris at chris-mbpr in ~/src/uuid on 7.x-1.x
$ grep -rn 'uuid_get_info' *
uuid.api.php:17: * @see uuid_get_info()
chris at chris-mbpr in ~/src/uuid on 7.x-1.x
$ grep -rn 'entity_uuid_sync' *
uuid.api.php:34: * @see entity_uuid_sync()

Ok, after a brutal journey of self-discovery and research, I have come back and learned a few things. Here's a list of functions that I implemented. They come from the files I listed above in comment #1:

• my_module_uuid_info() — defines your UUID generator. Basically takes a label and a callback, so that you can customize UUID generation.
• _my_module_generate_uuid() — the custom callback (if any) for your hook_uuid_info() implementation. You could use the UUID module's uuid_generate() function here. Or you could supply additional logic as necessary using a custom callback.
• my_module_get_uuid_entity_info_alter() — NOT YET EXISTING alterhook to specify the schema which needs to be altered during installation/update. See comment #4 for alter hook details.
• my_module_schema_alter() — I manually copied this function from uuid_schema_alter() and made some minor adjustments to point toward the previous function regarding the schema alterations.
• my_module_uninstall() — make module clean up after itself on uninstall. straight copy from uuid.install but I changed the loop to use my entity_info() implementation.

I'm still not 100% sure if I need these or if the uuid.entity.inc file does some of this for me (there are functions that claim to do this for all UUID-enabled entities), but I'm including them nonetheless as possible requirements for implementation:

• my_module_entity_uuid_load() — copy pasta from uuid.core.inc with minor modifications to match my table's schema.
• my_module_entity_uuid_presave() — another copy pasta from uuid.core.inc with minor modifications to match my table's schema.

Additionally, I created a new alter hook because I could not figure out how else to invoke the schema_alter(). We need direction from maintainers on how to avoid this hack, or perhaps I need to turn this into a legit patch for the module.

/**
 * Function found in uuid.entity.inc which contains my hacked-in alter hook.
 */
function uuid_get_core_entity_info() {
  $info = array();
  // ... module does it's thing for core entities here ...

  // I added this alter
  drupal_alter('get_uuid_entity_info', $info);

  return $info;
}

/**
 * Implements hook_get_uuid_entity_info_alter().
 *
 * This is a FICTIONAL function at the time of comment. I hacked it in to get things working.
 *
 * @see uuid_get_core_entity_info()
 */
function my_module_get_uuid_entity_info_alter(&$info) {
  // Provide a similar definition to the entries in uuid_get_core_entity_info().
  // I got some nasty PDO exceptions when I forgot 'revision table'. The "core" types don't list a revision table so beware.
}

After all that was in place, I removed the following functions (everything UUID-related in the .install file) which are now taken care of by the UUID module's (hacked, for now) functions:

• my_module_schema_alter()
• my_module_uninstall()

Well, the latest dev version should provide: uuid_features/uuid_features.api.php
This is at least a small documentation.

This is a UUID issue, not a UUID Features issue. Thanks for the heads-up on the Features side of things, though! I will probably be in your queue tomorrow with a similar brain-dump ;)

@rupl thanks for documenting :)

This is all I've added to my custom entity to get uuid working. I am using Entity API, but I believe it should also work without it and rely instead on core entity and "UUID implementation of Entity API" built-in to uuid. I also have a dependancy on uuid.

sample.install

module_load_include('install', 'uuid');

/**
 * Implements hook_schema().
 */
function sample_schema() {
  $schema['sample'] = array(
    ...
    'fields' => array(
      ...
      'sample_uuid' => uuid_schema_field_definition(),
      ...
    ),
    ...
  );
  return $schema;
}

sample.module

/**
 * Implements hook_entity_info().
 */
function sample_entity_info() {
  return array(
    'sample' => array(
      ...
      'uuid' => TRUE,
      'entity keys' => array(
        ...
        'uuid' => 'sample_uuid',
      ),
      ...
    ),
  );
}

P.S. "sample_uuid" could just be called "uuid" or anything else you wish.

Thanks very much @MustangGB

Is any result with features_uuid and custom entities types export to feature code?
I would be very appriciate to get any information!

I did now know work was being done on this in the uuid module. I have gotten uuid-entities export working decently in this module: https://github.com/gnucifer/uuid_entity_features

Perhaps functionality can be merged, I will have a look.

This was completed under #2236497: Documentation: How to integrate UUID with third party entities. If you have additional contributions, please add them to the existing documentation. Closing.