Extend entityreference field with another

Updated issue summary.

First, create a behavior:

/**
 * Implements hook_ctools_plugin_directory().
 */
function mymodule_ctools_plugin_directory($module, $plugin) {
  if ($module === 'entityreference') {
    return 'plugins/' . $plugin;
  }
}

And create a directory behavior within another named plugins. Add a file name for exemple your_field.inc in it:

$plugin = array(
  'title' => t('Add a textfield to the reference'),
  'class' => 'YourFieldBehavior',
  'behavior type' => 'field',
);

And add a file in the same behavior directory named after the plugin, YourFieldBehavior.class.php:

/**
 * Class YourFieldBehavior
 */
class YourFieldBehavior extends EntityReference_BehaviorHandler_Abstract {

  /**
   * Alter the schema to add our field
   *
   * @param $schema
   * @param $field
   */
  public function schema_alter(&$schema, $field) {
    $schema['columns']['yourfield'] = array(
      'description' => 'A label for the reference.',
      'type'        => 'varchar',
      'length'      => 255,
      'default'     => 0,
      'not null'    => TRUE,
    );
  }
}

The schema part is now done, flush the caches and the behavior should appear in the entityreference field settings.

Now we need to alter the widget, return to mymodule.module:

/**
 * Implements hook_field_widget_form_alter().
 */
function mymodule_field_widget_form_alter(&$element, &$form_state, $context) {
  // Act on our behavior.
  if (!empty($context['field']['settings']['handler_settings']['behaviors']['your_field']['status'])) {
    $element['yourfield'] = array(
      '#type'     => 'textfield',
      '#title'    => 'My label',
      '#weight'   => -1,
      '#required' => TRUE,
    );
    $element['target_id']['#title'] = 'My reference';
  }
}

Yup that's it, the textfield will be saved along with the reference!

You may want to add it to the display:

/**
 * Implements hook_field_attach_view_alter().
 */
function mymodule_field_attach_view_alter(&$output, $context) {
  // Prefix the reference with the label.
  foreach (element_children($output) as $field_name) {
    $element = &$output[$field_name];
    if ($element['#field_type'] == 'entityreference') {
      $field = field_info_field($field_name);
      if (!empty($field['settings']['handler_settings']['behaviors']['your_field']['status'])) {
        foreach ($element['#items'] as $delta => $item) {
          $element[$delta]['#prefix'] = "<strong>{$item['yourfield']} :</strong> ";
        }
      }
    }
  }
}

Now maybe this should be added to the documentation?