class Entity in Entity API 7

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.:


  public $name = '';
  public $count = 0;

Hierarchy

class \Entity implements EntityInterface

Expanded class hierarchy of Entity

5 string references to 'Entity'

entity_crud_hook_entity_info in ./entity.api.php: Provide an entity type via the entity CRUD API.
entity_entity_view_content_type_content_types in ctools/content_types/entity_view.inc: Implements hook_PLUGIN_content_type_content_types().
entity_property.inc in ctools/relationships/entity_property.inc: Plugin to provide an relationship handler for any entity property.
entity_test_entity_info in tests/entity_test.module: Implements hook_entity_info().
entity_views_data in views/entity.views.inc: Implements hook_views_data().

File

includes/entity.inc, line 191: Provides a base class for entities.

View source

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();
  }

}

Members

Name	Modifiers	Type	Description	Overrides
Entity::$defaultLabel	protected	property		1
Entity::$entityInfo	protected	property
Entity::$entityType	protected	property
Entity::$idKey	protected	property
Entity::$wrapper	protected	property
Entity::buildContent	public	function	Builds a structured array representing the entity's content. Overrides EntityInterface::buildContent	1
Entity::bundle	public	function	Returns the bundle of the entity. Overrides EntityInterface::bundle
Entity::defaultLabel	protected	function	Defines the entity label if the 'entity_class_label' callback is used.	1
Entity::defaultUri	protected	function	Override this in order to implement a custom default URI and specify 'entity_class_uri' as 'uri callback' hook_entity_info().
Entity::delete	public	function	Permanently deletes the entity. Overrides EntityInterface::delete
Entity::entityInfo	public	function	Returns the info of the type of the entity. Overrides EntityInterface::entityInfo
Entity::entityType	public	function	Returns the type of the entity. Overrides EntityInterface::entityType
Entity::export	public	function	Exports the entity. Overrides EntityInterface::export
Entity::getTranslation	public	function	Gets the raw, translated value of a property or field. Overrides EntityInterface::getTranslation
Entity::hasStatus	public	function	Checks if the entity has a certain exportable status. Overrides EntityInterface::hasStatus
Entity::identifier	public	function	Returns the entity identifier, i.e. the entities name or numeric id. Overrides EntityInterface::identifier
Entity::internalIdentifier	public	function	Returns the internal, numeric identifier. Overrides EntityInterface::internalIdentifier
Entity::isDefaultRevision	public	function	Checks whether the entity is the default revision. Overrides EntityInterface::isDefaultRevision
Entity::label	public	function	Returns the label of the entity. Overrides EntityInterface::label
Entity::save	public	function	Permanently saves the entity. Overrides EntityInterface::save
Entity::setUp	protected	function	Set up the object instance on construction or unserializiation.
Entity::uri	public	function	Returns the uri of the entity just as entity_uri(). Overrides EntityInterface::uri
Entity::view	public	function	Generate an array for rendering the entity. Overrides EntityInterface::view
Entity::wrapper	public	function	Returns the EntityMetadataWrapper of the entity. Overrides EntityInterface::wrapper
Entity::__construct	public	function		1
Entity::__sleep	public	function	Magic method to only serialize what's necessary.
Entity::__wakeup	public	function	Magic method to invoke setUp() on unserialization.

You are here

class Entity in Entity API 7

Hierarchy

File

Members

API Navigation