summaryrefslogtreecommitdiffstats
path: root/entity.api.php
blob: 3f7775265828a6bf3eda02d77ede0eccda336a58 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
<?php

/**
 * @file
 * Hooks provided by the entity API.
 */

/**
 * @addtogroup hooks
 * @{
 */

/**
 * Provide an entity type via the entity CRUD API.
 *
 * This is a placeholder for describing further keys for hook_entity_info(),
 * which are introduced the entity API for providing a new entity type with the
 * entity CRUD API. For that the entity API provides two controllers:
 *  - EntityAPIController: A regular CRUD controller.
 *  - EntityAPIControllerExportable: Extends the regular controller to
 *    additionally support exportable entities and/or entities making use of a
 *    name key.
 * See entity_metadata_hook_entity_info() for the documentation of additional
 * keys for hook_entity_info() as introduced by the entity API and supported for
 * any entity type.
 *
 * The entity CRUD API supports the following keys:
 * - entity class: (optional) A class the controller will use for instantiating
 *   entities. It is suggested to make use of the provided "Entity" class or to
 *   extend it.
 * - bundle of: (optional) Entity types can be used as bundles for
 *   other entity types. To enable this functionality, use the 'bundle of' key
 *   to indicate which entity type this entity serves as a bundle for. But note
 *   that the other entity type will still need to declare entities of this
 *   type as bundles, as described by the documentation of hook_entity_info().
 *   If the other entity type is fieldable, the entity API controller takes
 *   care of invoking the field API bundle attachers. Note that
 *   field_attach_delete_bundle() has to be invoked manually upon module
 *   uninstallation. See entity_test_entity_info() and entity_test_uninstall()
 *   for examples.
 * - module: (optional) The module providing the entity type. This is optional,
 *   but strongly suggested.
 * - exportable: (optional) Whether the entity is exportable. Defaults to FALSE.
 *   If enabled, a name key should be specified and db columns for the module
 *   and status key as defined by entity_exportable_schema_fields() have to
 *   exist in the entity's base table. Also see 'entity keys' below.
 *   This option requires the EntityAPIControllerExportable to work.
 * - entity keys: An array of keys as defined by Drupal core. The following
 *   additional keys are used by the entity CRUD API:
 *   - name: (optional) The key of the entity property containing the unique,
 *     machine readable name of the entity. If specified, this is used as
 *     identifier of the entity, while the usual 'id' key is still required and
 *     may be used when modules deal with entities generically, or to refer to
 *     the entity internally, i.e. in the database.
 *     If a name key is given, the name is used as entity identifier by the
 *     entity API module, metadata wrappers and entity-type specific hooks.
 *     However note that for consistency all generic entity hooks like
 *     hook_entity_load() are invoked with the entities keyed by numeric id,
 *     while entity-type specific hooks like hook_{entity_type}_load() are
 *     invoked with the entities keyed by name.
 *     Also, just as entity_load_single() entity_load() may be called
 *     with names passed as the $ids parameter, while the results of
 *     entity_load() are always keyed by numeric id. Thus, it is suggested to
 *     make use of entity_load_multiple_by_name() to implement entity-type
 *     specific loading functions like {entity_type}_load_multiple(), as this
 *     function returns the entities keyed by name. See entity_test_get_types()
 *     for an example.
 *     For exportable entities, it is strongly recommended to make use of a
 *     machine name as names are portable across systems.
 *     This option requires the EntityAPIControllerExportable to work.
 *   - module: (optional) A key for the module property used by the entity CRUD
 *     API to save the source module name for exportable entities that have been
 *     provided in code. Defaults to 'module'.
 *   - status: (optional) The name of the entity property used by the entity
 *     CRUD API to save the exportable entity status using defined bit flags.
 *     Defaults to 'status'. See entity_has_status().
 *   - default revision: (optional) The name of the entity property used by
 *     the entity CRUD API to determine if a newly-created revision should be
 *     set as the default revision. Defaults to 'default_revision'.
 *     Note that on entity insert the created revision will be always default
 *     regardless of the value of this entity property.
 * - export: (optional) An array of information used for exporting. For ctools
 *   exportables compatibility any export-keys supported by ctools may be added
 *   to this array too.
 *   - default hook: What hook to invoke to find exportable entities that are
 *     currently defined. This hook is automatically called by the CRUD
 *     controller during entity_load(). Defaults to 'default_' . $entity_type.
 * - admin ui: (optional) An array of optional information used for providing an
 *   administrative user interface. To enable the UI at least the path must be
 *   given. Apart from that, the 'access callback' (see below) is required for
 *   the entity, as well as the 'ENTITY_TYPE_form' for editing, adding and
 *   cloning. The form gets the entity and the operation ('edit', 'add' or
 *   'clone') passed. See entity_ui_get_form() for more details.
 *   Known keys are:
 *   - path: A path where the UI should show up as expected by hook_menu().
 *   - controller class: (optional) A controller class name for providing the
 *     UI. Defaults to EntityDefaultUIController, which implements an admin UI
 *     suiting for managing configuration entities. Other provided controllers
 *     suiting for content entities are EntityContentUIController or
 *     EntityBundleableUIController (which work fine despite the poorly named
 *     'admin ui' key).
 *     For customizing the UI inherit from the default class and override
 *     methods as suiting and specify your class as controller class.
 *   - file: (optional) The name of the file in which the entity form resides
 *     as it is required by hook_menu().
 *   - file path: (optional) The path to the file as required by hook_menu. If
 *     not set, it defaults to entity type's module's path, thus the entity
 *     types 'module' key is required.
 *   - menu wildcard: The wildcard to use in paths of the hook_menu() items.
 *     Defaults to %entity_object which is the loader provided by Entity API.
 * - rules controller class: (optional) A controller class for providing Rules
 *   integration, or FALSE to disable this feature. The given class has to
 *   inherit from the class EntityDefaultRulesController, which serves as
 *   default in case the entity type is not marked as configuration. For
 *   configuration entities it defaults to FALSE.
 * - metadata controller class: (optional) A controller class for providing
 *   entity property info. By default some info is generated out of the
 *   information provided in your hook_schema() implementation, while only read
 *   access is granted to that properties by default. Based upon that the
 *   Entity tokens module also generates token replacements for your entity
 *   type, once activated.
 *   Override the controller class to adapt the defaults and to improve and
 *   complete the generated metadata. Set it to FALSE to disable this feature.
 *   Defaults to the EntityDefaultMetadataController class.
 * - extra fields controller class: (optional) A controller class for providing
 *   field API extra fields. Defaults to none.
 *   The class must implement the EntityExtraFieldsControllerInterface. Display
 *   extra fields that are exposed that way are rendered by default by the
 *   EntityAPIController. The EntityDefaultExtraFieldsController class may be
 *   used to generate extra fields based upon property metadata, which in turn
 *   get rendered by default by the EntityAPIController.
 * - features controller class: (optional) A controller class for providing
 *   Features module integration for exportable entities. The given class has to
 *   inherit from the default class being EntityDefaultFeaturesController. Set
 *   it to FALSE to disable this feature.
 * - i18n controller class: (optional) A controller class for providing
 *   i18n module integration for (exportable) entities. The given class has to
 *   inherit from the class EntityDefaultI18nStringController. Defaults to
 *   FALSE (disabled). See EntityDefaultI18nStringController for more
 *   information.
 * - views controller class: (optional) A controller class for providing views
 *   integration. The given class has to inherit from the class
 *   EntityDefaultViewsController, which is set as default in case the providing
 *   module has been specified (see 'module') and the module does not provide
 *   any views integration. Else it defaults to FALSE, which disables this
 *   feature. See EntityDefaultViewsController.
 * - access callback: (optional) Specify a callback that returns access
 *   permissions for the operations 'create', 'update', 'delete' and 'view'.
 *   The callback gets optionally the entity and the user account to check for
 *   passed. See entity_access() for more details on the arguments and
 *   entity_metadata_no_hook_node_access() for an example.
 *   This is optional, but suggested for the Rules integration, and required for
 *   the admin ui (see above).
 * - form callback: (optional) Specfiy a callback that returns a fully built
 *   edit form for your entity type. See entity_form().
 *   In case the 'admin ui' is used, no callback needs to be specified.
 * - entity cache: (optional) Whether entities should be cached using the cache
 *   system. Requires the entitycache module to be installed and enabled and the
 *   module key to be specified. As cached entities are only retrieved by id key,
 *   the cache would not apply to exportable entities retrieved by name key.
 *   If enabled and the entitycache module is active, 'field cache' is obsolete
 *   and is automatically disabled. Defaults to FALSE.
 *
 * @see hook_entity_info()
 * @see entity_metadata_hook_entity_info()
 */
function entity_crud_hook_entity_info() {
  $return = array(
    'entity_test' => array(
      'label' => t('Test Entity'),
      'entity class' => 'Entity',
      'controller class' => 'EntityAPIController',
      'base table' => 'entity_test',
      'module' => 'entity_test',
      'fieldable' => TRUE,
      'entity keys' => array(
        'id' => 'pid',
        'name' => 'name',
        'bundle' => 'type',
      ),
      'bundles' => array(),
    ),
  );
  foreach (entity_test_get_types() as $name => $info) {
    $return['entity_test']['bundles'][$name] = array(
      'label' => $info['label'],
    );
  }
  return $return;
}

/**
 * Provide additional metadata for entities.
 *
 * This is a placeholder for describing further keys for hook_entity_info(),
 * which are introduced the entity API in order to support any entity type; e.g.
 * to make entity_save(), entity_create(), entity_view() and others work.
 * See entity_crud_hook_entity_info() for the documentation of additional keys
 * for hook_entity_info() as introduced by the entity API for providing new
 * entity types with the entity CRUD API.
 *
 * Additional keys are:
 * - plural label: (optional) The human-readable, plural name of the entity
 *   type. As 'label' it should start capitalized.
 * - description: (optional) A human-readable description of the entity type.
 * - access callback: (optional) Specify a callback that returns access
 *   permissions for the operations 'create', 'update', 'delete' and 'view'.
 *   The callback gets optionally the entity and the user account to check for
 *   passed. See entity_access() for more details on the arguments and
 *   entity_metadata_no_hook_node_access() for an example.
 * - creation callback: (optional) A callback that creates a new instance of
 *   this entity type. See entity_metadata_create_node() for an example.
 * - save callback: (optional) A callback that permanently saves an entity of
 *   this type.
 * - deletion callback: (optional) A callback that permanently deletes an
 *   entity of this type.
 * - revision deletion callback: (optional) A callback that deletes a revision
 *   of the entity.
 * - view callback: (optional) A callback to render a list of entities.
 *   See entity_metadata_view_node() as example.
 * - form callback: (optional) A callback that returns a fully built edit form
 *   for the entity type.
 * - token type: (optional) A type name to use for token replacements. Set it
 *   to FALSE if there aren't any token replacements for this entity type.
 * - configuration: (optional) A boolean value that specifies whether the entity
 *   type should be considered as configuration. Modules working with entities
 *   may use this value to decide whether they should deal with a certain entity
 *   type. Defaults to TRUE to for entity types that are exportable, else to
 *   FALSE.
 *
 * @see hook_entity_info()
 * @see entity_crud_hook_entity_info()
 * @see entity_access()
 * @see entity_create()
 * @see entity_save()
 * @see entity_delete()
 * @see entity_view()
 * @see entity_form()
 */
function entity_metadata_hook_entity_info() {
  return array(
    'node' => array(
      'label' => t('Node'),
      'access callback' => 'entity_metadata_no_hook_node_access',
      // ...
    ),
  );
}

/**
 * Allow modules to define metadata about entity properties.
 *
 * Modules providing properties for any entities defined in hook_entity_info()
 * can implement this hook to provide metadata about this properties.
 * For making use of the metadata have a look at the provided wrappers returned
 * by entity_metadata_wrapper().
 * For providing property information for fields see entity_hook_field_info().
 *
 * @return
 *   An array whose keys are entity type names and whose values are arrays
 *   containing the keys:
 *   - properties: The array describing all properties for this entity. Entries
 *     are keyed by the property name and contain an array of metadata for each
 *     property. The name may only contain alphanumeric lowercase characters
 *     and underscores. Known keys are:
 *     - label: A human readable, translated label for the property.
 *     - description: (optional) A human readable, translated description for
 *       the property.
 *     - type: The data type of the property. To make the property actually
 *       useful it is important to map your properties to one of the known data
 *       types, which currently are:
 *        - text: Any text.
 *        - token: A string containing only lowercase letters, numbers, and
 *          underscores starting with a letter; e.g. this type is useful for
 *          machine readable names.
 *        - integer: A usual PHP integer value.
 *        - decimal: A PHP float or integer.
 *        - date: A full date and time, as timestamp.
 *        - duration: A duration as number of seconds.
 *        - boolean: A usual PHP boolean value.
 *        - uri: An absolute URI or URL.
 *        - entities - You may use the type of each entity known by
 *          hook_entity_info(), e.g. 'node' or 'user'. Internally entities are
 *          represented by their identifieres. In case of single-valued
 *          properties getter callbacks may return full entity objects as well,
 *          while a value of FALSE is interpreted like a NULL value as "property
 *          is not set".
 *        - entity: A special type to be used generically for entities where the
 *          entity type is not known beforehand. The entity has to be
 *          represented using an EntityMetadataWrapper.
 *        - struct: This as well as any else not known type may be used for
 *          supporting arbitrary data structures. For that additional metadata
 *          has to be specified with the 'property info' key. New type names
 *          have to be properly prefixed with the module name.
 *        - list: A list of values, represented as numerically indexed array.
 *          The list<TYPE> notation may be used to specify the type of the
 *          contained items, where TYPE may be any valid type expression.
 *     - bundle: (optional) If the property is an entity, you may specify the
 *       bundle of the referenced entity.
 *     - options list: (optional) A callback that returns a list of possible
 *       values for the property. The callback has to return an array as
 *       used by hook_options_list().
 *       Note that it is possible to return a different set of options depending
 *       whether they are used in read or in write context. See
 *       EntityMetadataWrapper::optionsList() for more details on that.
 *     - getter callback: (optional) A callback used to retrieve the value of
 *       the property. Defaults to entity_property_verbatim_get().
 *       It is important that your data is represented, as documented for your
 *       data type, e.g. a date has to be a timestamp. Thus if necessary, the
 *       getter callback has to do the necessary conversion. In case of an empty
 *       or not set value, the callback has to return NULL.
 *     - setter callback: (optional) A callback used to set the value of the
 *       property. In many cases entity_property_verbatim_set() can be used.
 *     - validation callback: (optional) A callback that returns whether the
 *       passed data value is valid for the property. May be used to implement
 *       additional validation checks, such as to ensure the value is a valid
 *       mail address.
 *     - access callback: (optional) An access callback to allow for checking
 *       'view' and 'edit' access for the described property. If no callback
 *       is specified, a 'setter permission' may be specified instead.
 *     - setter permission: (optional) A permission that describes whether
 *       a user has permission to set ('edit') this property. This permission
 *       is only be taken into account, if no 'access callback' is given.
 *     - schema field: (optional) In case the property is directly based upon
 *       a field specified in the entity's hook_schema(), the name of the field.
 *     - queryable: (optional) Whether a property is queryable with
 *       EntityFieldQuery. Defaults to TRUE if a 'schema field' is specified, or
 *       if the deprecated 'query callback' is set to
 *       'entity_metadata_field_query'. Otherwise it defaults to FALSE.
 *     - query callback: (deprecated) A callback for querying for entities
 *       having the given property value. See entity_property_query().
 *       Generally, properties should be queryable via EntityFieldQuery. If
 *       that is the case, just set 'queryable' to TRUE.
 *     - required: (optional) Whether this property is required for the creation
 *       of a new instance of its entity. See
 *       entity_property_values_create_entity().
 *     - field: (optional) A boolean indicating whether a property is stemming
 *       from a field.
 *     - computed: (optional) A boolean indicating whether a property is
 *       computed, i.e. the property value is not stored or loaded by the
 *       entity's controller but determined on the fly by the getter callback.
 *       Defaults to FALSE.
 *     - entity views field: (optional) If enabled, the property is
 *       automatically exposed as views field available to all views query
 *       backends listing this entity-type. As the property value will always be
 *       generated from a loaded entity object, this is particularly useful for
 *       'computed' properties. Defaults to FALSE.
 *     - sanitized: (optional) For textual properties only, whether the text is
 *       already sanitized. In this case you might want to also specify a raw
 *       getter callback. Defaults to FALSE.
 *     - sanitize: (optional) For textual properties, that are not sanitized
 *       yet, specify a function for sanitizing the value. Defaults to
 *       check_plain().
 *     - raw getter callback: (optional) For sanitized textual properties, a
 *       separate callback which can be used to retrieve the raw, unprocessed
 *       value.
 *     - clear: (optional) An array of property names, of which the cache should
 *       be cleared too once this property is updated. As a rule of thumb any
 *       duplicated properties should be avoided though.
 *     - property info: (optional) An array of info for an arbitrary data
 *       structure together with any else not defined type, see data type
 *       'struct'. Specify metadata in the same way as defined for this hook.
 *     - property info alter: (optional) A callback for altering the property
 *       info before it is used by the metadata wrappers.
 *     - property defaults: (optional) An array of property info defaults for
 *       each property derived of the wrapped data item (e.g. an entity).
 *       Applied by the metadata wrappers.
 *     - auto creation: (optional) Properties of type 'struct' may specify
 *       this callback which is used to automatically create the data structure
 *       (e.g. an array) if necessary. This is necessary in order to support
 *       setting a property of a not yet initialized data structure.
 *       See entity_metadata_field_file_callback() for an example.
 *     - translatable: (optional) Whether the property is translatable, defaults
 *       to FALSE.
 *     - entity token: (optional) If Entity tokens module is enabled, the
 *       module provides a token for the property if one does not exist yet.
 *       Specify FALSE to disable this functionality for the property.
 *   - bundles: An array keyed by bundle name containing further metadata
 *     related to the bundles only. This array may contain the key 'properties'
 *     with an array of info about the bundle specific properties, structured in
 *     the same way as the entity properties array.
 *
 *  @see hook_entity_property_info_alter()
 *  @see entity_get_property_info()
 *  @see entity_metadata_wrapper()
 */
function hook_entity_property_info() {
  $info = array();
  $properties = &$info['node']['properties'];

  $properties['nid'] = array(
    'label' => t("Content ID"),
    'type' => 'integer',
    'description' => t("The unique content ID."),
  );
  return $info;
}

/**
 * Allow modules to alter metadata about entity properties.
 *
 * @see hook_entity_property_info()
 */
function hook_entity_property_info_alter(&$info) {
  $properties = &$info['node']['bundles']['poll']['properties'];

  $properties['poll-votes'] = array(
    'label' => t("Poll votes"),
    'description' => t("The number of votes that have been cast on a poll node."),
    'type' => 'integer',
    'getter callback' => 'entity_property_poll_node_get_properties',
  );
}

/**
 * Provide entity property information for fields.
 *
 * This is a placeholder for describing further keys for hook_field_info(),
 * which are introduced by the entity API.
 *
 * For providing entity property info for fields each field type may specify a
 * property type to map to using the key 'property_type'. With that info in
 * place useful defaults are generated, which suffice for a lot of field
 * types.
 * However it is possible to specify further callbacks that may alter the
 * generated property info. To do so use the key 'property_callbacks' and set
 * it to an array of function names. Apart from that any property info provided
 * for a field instance using the key 'property info' is added in too.
 *
 * @see entity_field_info_alter()
 * @see entity_metadata_field_text_property_callback()
 */
function entity_hook_field_info() {
  return array(
    'text' => array(
      'label' => t('Text'),
      'property_type' => 'text',
      // ...
    ),
  );
}

/**
 * Alter the handlers used by the data selection tables provided by this module.
 *
 * @param array $field_handlers
 *   An array of the field handler classes to use for specific types. The keys
 *   are the types, mapped to their respective classes. Contained types are:
 *   - All primitive types known by the entity API (see
 *     hook_entity_property_info()).
 *   - options: Special type for fields having an options list.
 *   - field: Special type for Field API fields.
 *   - entity: Special type for entity-valued fields.
 *   - relationship: Views relationship handler to use for relationships.
 *   Values for all specific entity types can be additionally added.
 *
 * @see entity_views_field_definition()
 * @see entity_views_get_field_handlers()
 */
function hook_entity_views_field_handlers_alter(array &$field_handlers) {
  $field_handlers['duration'] = 'example_duration_handler';
  $field_handlers['node'] = 'example_node_handler';
}

/**
 * @} End of "addtogroup hooks".
 */