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