diff options
Diffstat (limited to 'sites/all/modules/entity/includes/entity.inc')
-rw-r--r-- | sites/all/modules/entity/includes/entity.inc | 423 |
1 files changed, 423 insertions, 0 deletions
diff --git a/sites/all/modules/entity/includes/entity.inc b/sites/all/modules/entity/includes/entity.inc new file mode 100644 index 000000000..2f504f36a --- /dev/null +++ b/sites/all/modules/entity/includes/entity.inc @@ -0,0 +1,423 @@ +<?php + +/** + * @file + * Provides a base class for entities. + */ + +/** + * Interface for class based entities. + */ +interface EntityInterface { + + /** + * Returns the internal, numeric identifier. + * + * Returns the numeric identifier, even if the entity type has specified a + * name key. In the latter case, the numeric identifier is supposed to be used + * when dealing generically with entities or internally to refer to an entity, + * i.e. in a relational database. If unsure, use Entity:identifier(). + */ + public function internalIdentifier(); + + /** + * Returns the entity identifier, i.e. the entities name or numeric id. + * + * @return + * The identifier of the entity. If the entity type makes use of a name key, + * the name is returned, else the numeric id. + * + * @see entity_id() + */ + public function identifier(); + + /** + * Returns the info of the type of the entity. + * + * @see entity_get_info() + */ + public function entityInfo(); + + /** + * Returns the type of the entity. + */ + public function entityType(); + + /** + * Returns the bundle of the entity. + * + * @return + * The bundle of the entity. Defaults to the entity type if the entity type + * does not make use of different bundles. + */ + public function bundle(); + + /** + * Returns the EntityMetadataWrapper of the entity. + * + * @return EntityDrupalWrapper + * An EntityMetadataWrapper containing the entity. + */ + public function wrapper(); + + /** + * Returns the label of the entity. + * + * Modules may alter the label by specifying another 'label callback' using + * hook_entity_info_alter(). + * + * @see entity_label() + */ + public function label(); + + /** + * Returns the uri of the entity just as entity_uri(). + * + * Modules may alter the uri by specifying another 'uri callback' using + * hook_entity_info_alter(). + * + * @see entity_uri() + */ + public function uri(); + + /** + * Checks if the entity has a certain exportable status. + * + * @param $status + * A status constant, i.e. one of ENTITY_CUSTOM, ENTITY_IN_CODE, + * ENTITY_OVERRIDDEN or ENTITY_FIXED. + * + * @return bool + * For exportable entities TRUE if the entity has the status, else FALSE. + * In case the entity is not exportable, NULL is returned. + * + * @see entity_has_status() + */ + public function hasStatus($status); + + /** + * Permanently saves the entity. + * + * @see entity_save() + */ + public function save(); + + /** + * Permanently deletes the entity. + * + * @see entity_delete() + */ + public function delete(); + + /** + * Exports the entity. + * + * @see entity_export() + */ + public function export($prefix = ''); + + /** + * Generate an array for rendering the entity. + * + * @see entity_view() + */ + public function view($view_mode = 'full', $langcode = NULL, $page = NULL); + + /** + * Builds a structured array representing the entity's content. + * + * @see entity_build_content() + */ + public function buildContent($view_mode = 'full', $langcode = NULL); + + /** + * Gets the raw, translated value of a property or field. + * + * Supports retrieving field translations as well as i18n string translations. + * + * Note that this returns raw data values, which might not reflect what + * has been declared for hook_entity_property_info() as no 'getter callbacks' + * are invoked or no referenced entities are loaded. For retrieving values + * reflecting the property info make use of entity metadata wrappers, see + * entity_metadata_wrapper(). + * + * @param $property + * The name of the property to return; e.g., 'title'. + * @param $langcode + * (optional) The language code of the language to which the value should + * be translated. If set to NULL, the default display language is being + * used. + * + * @return + * The raw, translated property value; or the raw, un-translated value if no + * translation is available. + * + * @todo Implement an analogous setTranslation() method for updating. + */ + public function getTranslation($property, $langcode = NULL); + + /** + * Checks whether the entity is the default revision. + * + * @return Boolean + * + * @see entity_revision_is_default() + */ + public function isDefaultRevision(); + +} + +/** + * A common class for entities. + * + * It's suggested, but not required, to extend this class and to override + * __construct() in order to specify a fixed entity type. + * + * For providing an entity label and URI it is suggested to override the + * defaultLabel() and defaultUri() methods, and to specify the + * entity_class_label() and entity_class_uri() as respective callbacks in + * hook_entity_info(). That way modules are able to override your defaults + * by altering the hook_entity_info() callbacks, while $entity->label() and + * $entity->uri() reflect this changes as well. + * + * Defaults for entity properties can be easily defined by adding class + * properties, e.g.: + * @code + * public $name = ''; + * public $count = 0; + * @endcode + */ +class Entity implements EntityInterface { + + protected $entityType; + protected $entityInfo; + protected $idKey, $nameKey, $statusKey; + protected $defaultLabel = FALSE; + protected $wrapper; + + /** + * {@inheritdoc} + */ + public function __construct(array $values = array(), $entityType = NULL) { + if (empty($entityType)) { + throw new Exception('Cannot create an instance of Entity without a specified entity type.'); + } + $this->entityType = $entityType; + $this->setUp(); + // Set initial values. + foreach ($values as $key => $value) { + $this->$key = $value; + } + } + + /** + * Set up the object instance on construction or unserializiation. + */ + protected function setUp() { + $this->entityInfo = entity_get_info($this->entityType); + $this->idKey = $this->entityInfo['entity keys']['id']; + $this->nameKey = isset($this->entityInfo['entity keys']['name']) ? $this->entityInfo['entity keys']['name'] : $this->idKey; + $this->statusKey = empty($this->entityInfo['entity keys']['status']) ? 'status' : $this->entityInfo['entity keys']['status']; + } + + /** + * {@inheritdoc} + */ + public function internalIdentifier() { + return isset($this->{$this->idKey}) ? $this->{$this->idKey} : NULL; + } + + /** + * {@inheritdoc} + */ + public function identifier() { + return isset($this->{$this->nameKey}) ? $this->{$this->nameKey} : NULL; + } + + /** + * {@inheritdoc} + */ + public function entityInfo() { + return $this->entityInfo; + } + + /** + * {@inheritdoc} + */ + public function entityType() { + return $this->entityType; + } + + /** + * {@inheritdoc} + */ + public function bundle() { + return !empty($this->entityInfo['entity keys']['bundle']) ? $this->{$this->entityInfo['entity keys']['bundle']} : $this->entityType; + } + + /** + * {@inheritdoc} + */ + public function wrapper() { + if (empty($this->wrapper)) { + $this->wrapper = entity_metadata_wrapper($this->entityType, $this); + } + elseif ($this->wrapper->value() !== $this) { + // Wrapper has been modified outside, so let's better create a new one. + $this->wrapper = entity_metadata_wrapper($this->entityType, $this); + } + return $this->wrapper; + } + + /** + * {@inheritdoc} + */ + public function label() { + // If the default label flag is enabled, this is being invoked recursively. + // In this case we need to use our default label callback directly. This may + // happen if a module provides a label callback implementation different + // from ours, but then invokes Entity::label() or entity_class_label() from + // there. + if ($this->defaultLabel || (isset($this->entityInfo['label callback']) && $this->entityInfo['label callback'] == 'entity_class_label')) { + return $this->defaultLabel(); + } + $this->defaultLabel = TRUE; + $label = entity_label($this->entityType, $this); + $this->defaultLabel = FALSE; + return $label; + } + + /** + * Defines the entity label if the 'entity_class_label' callback is used. + * + * Specify 'entity_class_label' as 'label callback' in hook_entity_info() to + * let the entity label point to this method. Override this in order to + * implement a custom default label. + */ + protected function defaultLabel() { + // Add in the translated specified label property. + return $this->getTranslation($this->entityInfo['entity keys']['label']); + } + + /** + * {@inheritdoc} + */ + public function uri() { + if (isset($this->entityInfo['uri callback']) && $this->entityInfo['uri callback'] == 'entity_class_uri') { + return $this->defaultUri(); + } + return entity_uri($this->entityType, $this); + } + + /** + * Override this in order to implement a custom default URI and specify + * 'entity_class_uri' as 'uri callback' hook_entity_info(). + */ + protected function defaultUri() { + return array('path' => 'default/' . $this->identifier()); + } + + /** + * {@inheritdoc} + */ + public function hasStatus($status) { + if (!empty($this->entityInfo['exportable'])) { + return isset($this->{$this->statusKey}) && ($this->{$this->statusKey} & $status) == $status; + } + } + + /** + * {@inheritdoc} + */ + public function save() { + return entity_get_controller($this->entityType)->save($this); + } + + /** + * {@inheritdoc} + */ + public function delete() { + $id = $this->identifier(); + if (isset($id)) { + entity_get_controller($this->entityType)->delete(array($id)); + } + } + + /** + * {@inheritdoc} + */ + public function export($prefix = '') { + return entity_get_controller($this->entityType)->export($this, $prefix); + } + + /** + * {@inheritdoc} + */ + public function view($view_mode = 'full', $langcode = NULL, $page = NULL) { + return entity_get_controller($this->entityType)->view(array($this), $view_mode, $langcode, $page); + } + + /** + * {@inheritdoc} + */ + public function buildContent($view_mode = 'full', $langcode = NULL) { + return entity_get_controller($this->entityType)->buildContent($this, $view_mode, $langcode); + } + + /** + * {@inheritdoc} + */ + public function getTranslation($property, $langcode = NULL) { + $all_info = entity_get_all_property_info($this->entityType); + // Assign by reference to avoid triggering notices if metadata is missing. + $property_info = &$all_info[$property]; + + if (!empty($property_info['translatable'])) { + if (!empty($property_info['field'])) { + return field_get_items($this->entityType, $this, $property, $langcode); + } + elseif (!empty($property_info['i18n string'])) { + $name = $this->entityInfo['module'] . ':' . $this->entityType . ':' . $this->identifier() . ':' . $property; + return entity_i18n_string($name, $this->$property, $langcode); + } + } + return $this->$property; + } + + /** + * {@inheritdoc} + */ + public function isDefaultRevision() { + if (!empty($this->entityInfo['entity keys']['revision'])) { + $key = !empty($this->entityInfo['entity keys']['default revision']) ? $this->entityInfo['entity keys']['default revision'] : 'default_revision'; + return !empty($this->$key); + } + return TRUE; + } + + /** + * Magic method to only serialize what's necessary. + */ + public function __sleep() { + $vars = get_object_vars($this); + unset($vars['entityInfo'], $vars['idKey'], $vars['nameKey'], $vars['statusKey']); + // Also key the returned array with the variable names so the method may + // be easily overridden and customized. + return drupal_map_assoc(array_keys($vars)); + } + + /** + * Magic method to invoke setUp() on unserialization. + */ + public function __wakeup() { + $this->setUp(); + } +} + +/** + * These classes are deprecated by "Entity" and are only here for backward + * compatibility reasons. + */ +class EntityDB extends Entity {} +class EntityExtendable extends Entity {} +class EntityDBExtendable extends Entity {} |