Issue #1104286: Support generating database schema for date properties.
[project/entity.git] / entity.api.php
1 <?php
2
3 /**
4 * @file
5 * Hooks provided by the entity API.
6 */
7
8 /**
9 * @addtogroup hooks
10 * @{
11 */
12
13 /**
14 * Provide an entity type via the entity CRUD API.
15 *
16 * This is a placeholder for describing further keys for hook_entity_info(),
17 * which are introduced the entity API for providing a new entity type with the
18 * entity CRUD API. For that the entity API provides two controllers:
19 * - EntityAPIController: A regular CRUD controller.
20 * - EntityAPIControllerExportable: Extends the regular controller to
21 * additionally support exportable entities and/or entities making use of a
22 * name key.
23 * See entity_metadata_hook_entity_info() for the documentation of additional
24 * keys for hook_entity_info() as introduced by the entity API and supported for
25 * any entity type.
26 *
27 * The entity CRUD API supports the following keys:
28 * - entity class: (optional) A class the controller will use for instantiating
29 * entities. It is suggested to make use of the provided "Entity" class or to
30 * extend it.
31 * - bundle of: (optional) Entity types can be used as bundles for
32 * other entity types. To enable this functionality, use the 'bundle of' key
33 * to indicate which entity type this entity serves as a bundle for. But note
34 * that the other entity type will still need to declare entities of this
35 * type as bundles, as described by the documentation of hook_entity_info().
36 * If the other entity type is fieldable, the entity API controller takes
37 * care of invoking the field API bundle attachers. Note that
38 * field_attach_delete_bundle() has to be invoked manually upon module
39 * uninstallation. See entity_test_entity_info() and entity_test_uninstall()
40 * for examples.
41 * - module: (optional) The module providing the entity type. This is optional,
42 * but strongly suggested.
43 * - exportable: (optional) Whether the entity is exportable. Defaults to FALSE.
44 * If enabled, a name key should be specified and db columns for the module
45 * and status key as defined by entity_exportable_schema_fields() have to
46 * exist in the entity's base table. Also see 'entity keys' below.
47 * This option requires the EntityAPIControllerExportable to work.
48 * - entity keys: An array of keys as defined by Drupal core. The following
49 * additional keys are used by the entity CRUD API:
50 * - name: (optional) The key of the entity property containing the unique,
51 * machine readable name of the entity. If specified, this is used as
52 * identifier of the entity, while the usual 'id' key is still required and
53 * may be used when modules deal with entities generically, or to refer to
54 * the entity internally, i.e. in the database.
55 * If a name key is given, the name is used as entity identifier by the
56 * entity API module, metadata wrappers and entity-type specific hooks.
57 * However note that for consistency all generic entity hooks like
58 * hook_entity_load() are invoked with the entities keyed by numeric id,
59 * while entity-type specific hooks like hook_{entity_type}_load() are
60 * invoked with the entities keyed by name.
61 * Also, just as entity_load_single() entity_load() may be called
62 * with names passed as the $ids parameter, while the results of
63 * entity_load() are always keyed by numeric id. Thus, it is suggested to
64 * make use of entity_load_multiple_by_name() to implement entity-type
65 * specific loading functions like {entity_type}_load_multiple(), as this
66 * function returns the entities keyed by name. See entity_test_get_types()
67 * for an example.
68 * For exportable entities, it is strongly recommended to make use of a
69 * machine name as names are portable across systems.
70 * This option requires the EntityAPIControllerExportable to work.
71 * - module: (optional) A key for the module property used by the entity CRUD
72 * API to save the source module name for exportable entities that have been
73 * provided in code. Defaults to 'module'.
74 * - status: (optional) The name of the entity property used by the entity
75 * CRUD API to save the exportable entity status using defined bit flags.
76 * Defaults to 'status'. See entity_has_status().
77 * - default revision: (optional) The name of the entity property used by
78 * the entity CRUD API to determine if a newly-created revision should be
79 * set as the default revision. Defaults to 'default_revision'.
80 * Note that on entity insert the created revision will be always default
81 * regardless of the value of this entity property.
82 * - export: (optional) An array of information used for exporting. For ctools
83 * exportables compatibility any export-keys supported by ctools may be added
84 * to this array too.
85 * - default hook: What hook to invoke to find exportable entities that are
86 * currently defined. This hook is automatically called by the CRUD
87 * controller during entity_load(). Defaults to 'default_' . $entity_type.
88 * - admin ui: (optional) An array of optional information used for providing an
89 * administrative user interface. To enable the UI at least the path must be
90 * given. Apart from that, the 'access callback' (see below) is required for
91 * the entity, as well as the 'ENTITY_TYPE_form' for editing, adding and
92 * cloning. The form gets the entity and the operation ('edit', 'add' or
93 * 'clone') passed. See entity_ui_get_form() for more details.
94 * Known keys are:
95 * - path: A path where the UI should show up as expected by hook_menu().
96 * - controller class: (optional) A controller class name for providing the
97 * UI. Defaults to EntityDefaultUIController, which implements an admin UI
98 * suiting for managing configuration entities. Other provided controllers
99 * suiting for content entities are EntityContentUIController or
100 * EntityBundleableUIController (which work fine despite the poorly named
101 * 'admin ui' key).
102 * For customizing the UI inherit from the default class and override
103 * methods as suiting and specify your class as controller class.
104 * - file: (optional) The name of the file in which the entity form resides
105 * as it is required by hook_menu().
106 * - file path: (optional) The path to the file as required by hook_menu. If
107 * not set, it defaults to entity type's module's path, thus the entity
108 * types 'module' key is required.
109 * - menu wildcard: The wildcard to use in paths of the hook_menu() items.
110 * Defaults to %entity_object which is the loader provided by Entity API.
111 * - rules controller class: (optional) A controller class for providing Rules
112 * integration, or FALSE to disable this feature. The given class has to
113 * inherit from the class EntityDefaultRulesController, which serves as
114 * default in case the entity type is not marked as configuration. For
115 * configuration entities it defaults to FALSE.
116 * - metadata controller class: (optional) A controller class for providing
117 * entity property info. By default some info is generated out of the
118 * information provided in your hook_schema() implementation, while only read
119 * access is granted to that properties by default. Based upon that the
120 * Entity tokens module also generates token replacements for your entity
121 * type, once activated.
122 * Override the controller class to adapt the defaults and to improve and
123 * complete the generated metadata. Set it to FALSE to disable this feature.
124 * Defaults to the EntityDefaultMetadataController class.
125 * - extra fields controller class: (optional) A controller class for providing
126 * field API extra fields. Defaults to none.
127 * The class must implement the EntityExtraFieldsControllerInterface. Display
128 * extra fields that are exposed that way are rendered by default by the
129 * EntityAPIController. The EntityDefaultExtraFieldsController class may be
130 * used to generate extra fields based upon property metadata, which in turn
131 * get rendered by default by the EntityAPIController.
132 * - features controller class: (optional) A controller class for providing
133 * Features module integration for exportable entities. The given class has to
134 * inherit from the default class being EntityDefaultFeaturesController. Set
135 * it to FALSE to disable this feature.
136 * - i18n controller class: (optional) A controller class for providing
137 * i18n module integration for (exportable) entities. The given class has to
138 * inherit from the class EntityDefaultI18nStringController. Defaults to
139 * FALSE (disabled). See EntityDefaultI18nStringController for more
140 * information.
141 * - views controller class: (optional) A controller class for providing views
142 * integration. The given class has to inherit from the class
143 * EntityDefaultViewsController, which is set as default in case the providing
144 * module has been specified (see 'module') and the module does not provide
145 * any views integration. Else it defaults to FALSE, which disables this
146 * feature. See EntityDefaultViewsController.
147 * - access callback: (optional) Specify a callback that returns access
148 * permissions for the operations 'create', 'update', 'delete' and 'view'.
149 * The callback gets optionally the entity and the user account to check for
150 * passed. See entity_access() for more details on the arguments and
151 * entity_metadata_no_hook_node_access() for an example.
152 * This is optional, but suggested for the Rules integration, and required for
153 * the admin ui (see above).
154 * - form callback: (optional) Specfiy a callback that returns a fully built
155 * edit form for your entity type. See entity_form().
156 * In case the 'admin ui' is used, no callback needs to be specified.
157 * - entity cache: (optional) Whether entities should be cached using the cache
158 * system. Requires the entitycache module to be installed and enabled and the
159 * module key to be specified. As cached entities are only retrieved by id key,
160 * the cache would not apply to exportable entities retrieved by name key.
161 * If enabled and the entitycache module is active, 'field cache' is obsolete
162 * and is automatically disabled. Defaults to FALSE.
163 *
164 * @see hook_entity_info()
165 * @see entity_metadata_hook_entity_info()
166 */
167 function entity_crud_hook_entity_info() {
168 $return = array(
169 'entity_test' => array(
170 'label' => t('Test Entity'),
171 'entity class' => 'Entity',
172 'controller class' => 'EntityAPIController',
173 'base table' => 'entity_test',
174 'module' => 'entity_test',
175 'fieldable' => TRUE,
176 'entity keys' => array(
177 'id' => 'pid',
178 'name' => 'name',
179 'bundle' => 'type',
180 ),
181 'bundles' => array(),
182 ),
183 );
184 foreach (entity_test_get_types() as $name => $info) {
185 $return['entity_test']['bundles'][$name] = array(
186 'label' => $info['label'],
187 );
188 }
189 return $return;
190 }
191
192 /**
193 * Provide additional metadata for entities.
194 *
195 * This is a placeholder for describing further keys for hook_entity_info(),
196 * which are introduced the entity API in order to support any entity type; e.g.
197 * to make entity_save(), entity_create(), entity_view() and others work.
198 * See entity_crud_hook_entity_info() for the documentation of additional keys
199 * for hook_entity_info() as introduced by the entity API for providing new
200 * entity types with the entity CRUD API.
201 *
202 * Additional keys are:
203 * - plural label: (optional) The human-readable, plural name of the entity
204 * type. As 'label' it should start capitalized.
205 * - description: (optional) A human-readable description of the entity type.
206 * - access callback: (optional) Specify a callback that returns access
207 * permissions for the operations 'create', 'update', 'delete' and 'view'.
208 * The callback gets optionally the entity and the user account to check for
209 * passed. See entity_access() for more details on the arguments and
210 * entity_metadata_no_hook_node_access() for an example.
211 * - creation callback: (optional) A callback that creates a new instance of
212 * this entity type. See entity_metadata_create_node() for an example.
213 * - save callback: (optional) A callback that permanently saves an entity of
214 * this type.
215 * - deletion callback: (optional) A callback that permanently deletes an
216 * entity of this type.
217 * - revision deletion callback: (optional) A callback that deletes a revision
218 * of the entity.
219 * - view callback: (optional) A callback to render a list of entities.
220 * See entity_metadata_view_node() as example.
221 * - form callback: (optional) A callback that returns a fully built edit form
222 * for the entity type.
223 * - token type: (optional) A type name to use for token replacements. Set it
224 * to FALSE if there aren't any token replacements for this entity type.
225 * - configuration: (optional) A boolean value that specifies whether the entity
226 * type should be considered as configuration. Modules working with entities
227 * may use this value to decide whether they should deal with a certain entity
228 * type. Defaults to TRUE to for entity types that are exportable, else to
229 * FALSE.
230 *
231 * @see hook_entity_info()
232 * @see entity_crud_hook_entity_info()
233 * @see entity_access()
234 * @see entity_create()
235 * @see entity_save()
236 * @see entity_delete()
237 * @see entity_view()
238 * @see entity_form()
239 */
240 function entity_metadata_hook_entity_info() {
241 return array(
242 'node' => array(
243 'label' => t('Node'),
244 'access callback' => 'entity_metadata_no_hook_node_access',
245 // ...
246 ),
247 );
248 }
249
250 /**
251 * Allow modules to define metadata about entity properties.
252 *
253 * Modules providing properties for any entities defined in hook_entity_info()
254 * can implement this hook to provide metadata about this properties.
255 * For making use of the metadata have a look at the provided wrappers returned
256 * by entity_metadata_wrapper().
257 * For providing property information for fields see entity_hook_field_info().
258 *
259 * @return
260 * An array whose keys are entity type names and whose values are arrays
261 * containing the keys:
262 * - properties: The array describing all properties for this entity. Entries
263 * are keyed by the property name and contain an array of metadata for each
264 * property. The name may only contain alphanumeric lowercase characters
265 * and underscores. Known keys are:
266 * - label: A human readable, translated label for the property.
267 * - description: (optional) A human readable, translated description for
268 * the property.
269 * - type: The data type of the property. To make the property actually
270 * useful it is important to map your properties to one of the known data
271 * types, which currently are:
272 * - text: Any text.
273 * - token: A string containing only lowercase letters, numbers, and
274 * underscores starting with a letter; e.g. this type is useful for
275 * machine readable names.
276 * - integer: A usual PHP integer value.
277 * - decimal: A PHP float or integer.
278 * - date: A full date and time, as timestamp.
279 * - duration: A duration as number of seconds.
280 * - boolean: A usual PHP boolean value.
281 * - uri: An absolute URI or URL.
282 * - entities - You may use the type of each entity known by
283 * hook_entity_info(), e.g. 'node' or 'user'. Internally entities are
284 * represented by their identifieres. In case of single-valued
285 * properties getter callbacks may return full entity objects as well,
286 * while a value of FALSE is interpreted like a NULL value as "property
287 * is not set".
288 * - entity: A special type to be used generically for entities where the
289 * entity type is not known beforehand. The entity has to be
290 * represented using an EntityMetadataWrapper.
291 * - struct: This as well as any else not known type may be used for
292 * supporting arbitrary data structures. For that additional metadata
293 * has to be specified with the 'property info' key. New type names
294 * have to be properly prefixed with the module name.
295 * - list: A list of values, represented as numerically indexed array.
296 * The list<TYPE> notation may be used to specify the type of the
297 * contained items, where TYPE may be any valid type expression.
298 * - bundle: (optional) If the property is an entity, you may specify the
299 * bundle of the referenced entity.
300 * - options list: (optional) A callback that returns a list of possible
301 * values for the property. The callback has to return an array as
302 * used by hook_options_list().
303 * Note that it is possible to return a different set of options depending
304 * whether they are used in read or in write context. See
305 * EntityMetadataWrapper::optionsList() for more details on that.
306 * - getter callback: (optional) A callback used to retrieve the value of
307 * the property. Defaults to entity_property_verbatim_get().
308 * It is important that your data is represented, as documented for your
309 * data type, e.g. a date has to be a timestamp. Thus if necessary, the
310 * getter callback has to do the necessary conversion. In case of an empty
311 * or not set value, the callback has to return NULL.
312 * - setter callback: (optional) A callback used to set the value of the
313 * property. In many cases entity_property_verbatim_set() can be used.
314 * - validation callback: (optional) A callback that returns whether the
315 * passed data value is valid for the property. May be used to implement
316 * additional validation checks, such as to ensure the value is a valid
317 * mail address.
318 * - access callback: (optional) An access callback to allow for checking
319 * 'view' and 'edit' access for the described property. If no callback
320 * is specified, a 'setter permission' may be specified instead.
321 * - setter permission: (optional) A permission that describes whether
322 * a user has permission to set ('edit') this property. This permission
323 * is only be taken into account, if no 'access callback' is given.
324 * - schema field: (optional) In case the property is directly based upon
325 * a field specified in the entity's hook_schema(), the name of the field.
326 * - queryable: (optional) Whether a property is queryable with
327 * EntityFieldQuery. Defaults to TRUE if a 'schema field' is specified, or
328 * if the deprecated 'query callback' is set to
329 * 'entity_metadata_field_query'. Otherwise it defaults to FALSE.
330 * - query callback: (deprecated) A callback for querying for entities
331 * having the given property value. See entity_property_query().
332 * Generally, properties should be queryable via EntityFieldQuery. If
333 * that is the case, just set 'queryable' to TRUE.
334 * - required: (optional) Whether this property is required for the creation
335 * of a new instance of its entity. See
336 * entity_property_values_create_entity().
337 * - field: (optional) A boolean indicating whether a property is stemming
338 * from a field.
339 * - computed: (optional) A boolean indicating whether a property is
340 * computed, i.e. the property value is not stored or loaded by the
341 * entity's controller but determined on the fly by the getter callback.
342 * Defaults to FALSE.
343 * - entity views field: (optional) If enabled, the property is
344 * automatically exposed as views field available to all views query
345 * backends listing this entity-type. As the property value will always be
346 * generated from a loaded entity object, this is particularly useful for
347 * 'computed' properties. Defaults to FALSE.
348 * - sanitized: (optional) For textual properties only, whether the text is
349 * already sanitized. In this case you might want to also specify a raw
350 * getter callback. Defaults to FALSE.
351 * - sanitize: (optional) For textual properties, that are not sanitized
352 * yet, specify a function for sanitizing the value. Defaults to
353 * check_plain().
354 * - raw getter callback: (optional) For sanitized textual properties, a
355 * separate callback which can be used to retrieve the raw, unprocessed
356 * value.
357 * - clear: (optional) An array of property names, of which the cache should
358 * be cleared too once this property is updated. As a rule of thumb any
359 * duplicated properties should be avoided though.
360 * - property info: (optional) An array of info for an arbitrary data
361 * structure together with any else not defined type, see data type
362 * 'struct'. Specify metadata in the same way as defined for this hook.
363 * - property info alter: (optional) A callback for altering the property
364 * info before it is used by the metadata wrappers.
365 * - property defaults: (optional) An array of property info defaults for
366 * each property derived of the wrapped data item (e.g. an entity).
367 * Applied by the metadata wrappers.
368 * - auto creation: (optional) Properties of type 'struct' may specify
369 * this callback which is used to automatically create the data structure
370 * (e.g. an array) if necessary. This is necessary in order to support
371 * setting a property of a not yet initialized data structure.
372 * See entity_metadata_field_file_callback() for an example.
373 * - translatable: (optional) Whether the property is translatable, defaults
374 * to FALSE.
375 * - entity token: (optional) If Entity tokens module is enabled, the
376 * module provides a token for the property if one does not exist yet.
377 * Specify FALSE to disable this functionality for the property.
378 * - bundles: An array keyed by bundle name containing further metadata
379 * related to the bundles only. This array may contain the key 'properties'
380 * with an array of info about the bundle specific properties, structured in
381 * the same way as the entity properties array.
382 *
383 * @see hook_entity_property_info_alter()
384 * @see entity_get_property_info()
385 * @see entity_metadata_wrapper()
386 */
387 function hook_entity_property_info() {
388 $info = array();
389 $properties = &$info['node']['properties'];
390
391 $properties['nid'] = array(
392 'label' => t("Content ID"),
393 'type' => 'integer',
394 'description' => t("The unique content ID."),
395 );
396 return $info;
397 }
398
399 /**
400 * Allow modules to alter metadata about entity properties.
401 *
402 * @see hook_entity_property_info()
403 */
404 function hook_entity_property_info_alter(&$info) {
405 $properties = &$info['node']['bundles']['poll']['properties'];
406
407 $properties['poll-votes'] = array(
408 'label' => t("Poll votes"),
409 'description' => t("The number of votes that have been cast on a poll node."),
410 'type' => 'integer',
411 'getter callback' => 'entity_property_poll_node_get_properties',
412 );
413 }
414
415 /**
416 * Provide entity property information for fields.
417 *
418 * This is a placeholder for describing further keys for hook_field_info(),
419 * which are introduced by the entity API.
420 *
421 * For providing entity property info for fields each field type may specify a
422 * property type to map to using the key 'property_type'. With that info in
423 * place useful defaults are generated, which suffice for a lot of field
424 * types.
425 * However it is possible to specify further callbacks that may alter the
426 * generated property info. To do so use the key 'property_callbacks' and set
427 * it to an array of function names. Apart from that any property info provided
428 * for a field instance using the key 'property info' is added in too.
429 *
430 * @see entity_field_info_alter()
431 * @see entity_metadata_field_text_property_callback()
432 */
433 function entity_hook_field_info() {
434 return array(
435 'text' => array(
436 'label' => t('Text'),
437 'property_type' => 'text',
438 // ...
439 ),
440 );
441 }
442
443 /**
444 * Alter the handlers used by the data selection tables provided by this module.
445 *
446 * @param array $field_handlers
447 * An array of the field handler classes to use for specific types. The keys
448 * are the types, mapped to their respective classes. Contained types are:
449 * - All primitive types known by the entity API (see
450 * hook_entity_property_info()).
451 * - options: Special type for fields having an options list.
452 * - field: Special type for Field API fields.
453 * - entity: Special type for entity-valued fields.
454 * - relationship: Views relationship handler to use for relationships.
455 * Values for all specific entity types can be additionally added.
456 *
457 * @see entity_views_field_definition()
458 * @see entity_views_get_field_handlers()
459 */
460 function hook_entity_views_field_handlers_alter(array &$field_handlers) {
461 $field_handlers['duration'] = 'example_duration_handler';
462 $field_handlers['node'] = 'example_node_handler';
463 }
464
465 /**
466 * @} End of "addtogroup hooks".
467 */