You are here

Home » API reference » Rules 7.2 » rules.state.inc

abstract class RulesIdentifiableDataWrapper in Rules 7.2

A wrapper class similar to the EntityDrupalWrapper, but for non-entities.

This class is intended to serve as base for a custom wrapper classes of identifiable data types, which are non-entities. By extending this class only the extractIdentifier() and load() methods have to be defined. In order to make the data type savable implement the RulesDataWrapperSavableInterface.

That way it is possible for non-entity data types to be work with Rules, i.e. one can implement a 'ui class' with a direct input form returning the identifier of the data. However, instead of that it is suggested to implement an entity type, such that the same is achieved via general API functions like entity_load().

Hierarchy

Expanded class hierarchy of RulesIdentifiableDataWrapper

File

includes/rules.state.inc, line 671
Contains the state and data related stuff.

View source 
abstract class RulesIdentifiableDataWrapper extends EntityStructureWrapper {

  /**
   * Contains the id.
   */
  protected $id = FALSE;

  /**
   * Construct a new wrapper object.
   *
   * @param $type
   *   The type of the passed data.
   * @param $data
   *   (optional) The data to wrap or its identifier.
   * @param array $info
   *   (optional) Used internally to pass info about properties down the tree.
   */
  public function __construct($type, $data = NULL, $info = array()) {
    parent::__construct($type, $data, $info);
    $this
      ->setData($data);
  }

  /**
   * Sets the data internally accepting both the data id and object.
   */
  protected function setData($data) {
    if (isset($data) && $data !== FALSE && !is_object($data)) {
      $this->id = $data;
      $this->data = FALSE;
    }
    elseif (is_object($data)) {

      // We got the data object passed.
      $this->data = $data;
      $id = $this
        ->extractIdentifier($data);
      $this->id = isset($id) ? $id : FALSE;
    }
  }

  /**
   * Returns the identifier of the wrapped data.
   */
  public function getIdentifier() {
    return $this
      ->dataAvailable() && $this
      ->value() ? $this->id : NULL;
  }

  /**
   * Overridden.
   */
  public function value(array $options = array()) {
    $this
      ->setData(parent::value());
    if (!$this->data && !empty($this->id)) {

      // Lazy load the data if necessary.
      $this->data = $this
        ->load($this->id);
      if (!$this->data) {
        throw new EntityMetadataWrapperException('Unable to load the ' . check_plain($this->type) . ' with the id ' . check_plain($this->id) . '.');
      }
    }
    return $this->data;
  }

  /**
   * Overridden to support setting the data by either the object or the id.
   */
  public function set($value) {
    if (!$this
      ->validate($value)) {
      throw new EntityMetadataWrapperException('Invalid data value given. Be sure it matches the required data type and format.');
    }

    // As custom wrapper classes can only appear for Rules variables, but not
    // as properties we don't have to care about updating the parent.
    $this
      ->clear();
    $this
      ->setData($value);
    return $this;
  }

  /**
   * Overridden.
   */
  public function clear() {
    $this->id = NULL;
    parent::clear();
  }

  /**
   * Prepare for serialization.
   */
  public function __sleep() {
    $vars = parent::__sleep();

    // Don't serialize the loaded data, except for the case the data is not
    // saved yet.
    if (!empty($this->id)) {
      unset($vars['data']);
    }
    return $vars;
  }

  /**
   * Prepare for unserialization.
   */
  public function __wakeup() {
    if ($this->id !== FALSE) {

      // Make sure data is set, so the data will be loaded when needed.
      $this->data = FALSE;
    }
  }

  /**
   * Extract the identifier of the given data object.
   *
   * @return
   *   The extracted identifier.
   */
  protected abstract function extractIdentifier($data);

  /**
   * Load a data object given an identifier.
   *
   * @return
   *   The loaded data object, or FALSE if loading failed.
   */
  protected abstract function load($id);

}

Members

Namesort descending Modifiers Type Description Overrides
EntityMetadataWrapper::$cache protected property
EntityMetadataWrapper::$data protected property
EntityMetadataWrapper::$info protected property
EntityMetadataWrapper::$type protected property 1
EntityMetadataWrapper::access public function Determines whether the given user has access to view or edit this property. Apart from relying on access metadata of properties, this takes into account information about entity level access, if available: 1
EntityMetadataWrapper::dataAvailable protected function Returns whether data is available to work with.
EntityMetadataWrapper::debugIdentifierLocation public function Returns a string to use to identify this wrapper in error messages. 1
EntityMetadataWrapper::info public function Gets info about the wrapped data.
EntityMetadataWrapper::label public function Returns the label for the currently set property value if there is one available, i.e. if an options list has been specified. 2
EntityMetadataWrapper::optionsList public function Returns the options list specifying possible values for the property, if defined.
EntityMetadataWrapper::raw public function Returns the raw, unprocessed data. Most times this is the same as returned by value(), however for already processed and sanitized textual data, this will return the unprocessed data in contrast to value().
EntityMetadataWrapper::type public function Gets the (entity)type of the wrapped data. 1
EntityMetadataWrapper::updateParent protected function Updates the parent data structure of a data property with the latest data value.
EntityMetadataWrapper::validate public function Returns whether $value is a valid value to set. 1
EntityMetadataWrapper::__toString public function
EntityStructureWrapper::$langcode protected property
EntityStructureWrapper::$propertyInfo protected property
EntityStructureWrapper::$propertyInfoDefaults protected property
EntityStructureWrapper::get public function Get the wrapper for a property.
EntityStructureWrapper::getIterator public function
EntityStructureWrapper::getPropertyInfo public function Gets the info about the given property.
EntityStructureWrapper::getPropertyLanguage public function Gets the language used for retrieving properties.
EntityStructureWrapper::getPropertyRaw protected function Gets the raw value of a property.
EntityStructureWrapper::getPropertyValue protected function Gets the value of a property.
EntityStructureWrapper::language public function Sets a new language to use for retrieving properties.
EntityStructureWrapper::propertyAccess protected function
EntityStructureWrapper::refPropertyInfo public function Returns a reference on the property info.
EntityStructureWrapper::setProperty protected function Sets a property.
EntityStructureWrapper::spotInfo protected function May be used to lazy-load additional info about the data, depending on the concrete passed data. 1
EntityStructureWrapper::__get public function Magic method: Get a wrapper for a property.
EntityStructureWrapper::__isset public function Magic method: Can be used to check if a property is known.
EntityStructureWrapper::__set public function Magic method: Set a property.
RulesIdentifiableDataWrapper::$id protected property Contains the id.
RulesIdentifiableDataWrapper::clear public function Overridden. Overrides EntityStructureWrapper::clear
RulesIdentifiableDataWrapper::extractIdentifier abstract protected function Extract the identifier of the given data object. 1
RulesIdentifiableDataWrapper::getIdentifier public function Returns the identifier of the wrapped data. Overrides EntityStructureWrapper::getIdentifier
RulesIdentifiableDataWrapper::load abstract protected function Load a data object given an identifier. 1
RulesIdentifiableDataWrapper::set public function Overridden to support setting the data by either the object or the id. Overrides EntityMetadataWrapper::set
RulesIdentifiableDataWrapper::setData protected function Sets the data internally accepting both the data id and object.
RulesIdentifiableDataWrapper::value public function Overridden. Overrides EntityMetadataWrapper::value
RulesIdentifiableDataWrapper::__construct public function Construct a new wrapper object. Overrides EntityStructureWrapper::__construct
RulesIdentifiableDataWrapper::__sleep public function Prepare for serialization. Overrides EntityStructureWrapper::__sleep
RulesIdentifiableDataWrapper::__wakeup public function Prepare for unserialization.