rules.state.inc

<?php


/**
 * @file
 * Contains the state and data related stuff.
 */

/**
 * The rules evaluation state.
 *
 * A rule element may clone the state, so any added variables are only visible
 * for elements in the current PHP-variable-scope.
 */
class RulesState {
    
    /**
     * Globally keeps the ids of rules blocked due to recursion prevention.
     *
     * @var array
     */
    protected static $blocked = array();
    
    /**
     * The known variables.
     *
     * @var array
     */
    public $variables = array();
    
    /**
     * Holds info about the variables.
     *
     * @var array
     */
    protected $info = array();
    
    /**
     * Keeps wrappers to be saved later on.
     */
    protected $save;
    
    /**
     * Holds the arguments while an element is executed.
     *
     * May be used by the element to easily access the wrapped arguments.
     */
    public $currentArguments;
    
    /**
     * Variable for saving currently blocked configs for serialization.
     */
    protected $currentlyBlocked;
    
    /**
     * Constructs a RulesState object.
     */
    public function __construct() {
        // Use an object in order to ensure any cloned states reference the same
        // save information.
        $this->save = new ArrayObject();
        $this->addVariable('site', FALSE, self::defaultVariables('site'));
    }
    
    /**
     * Adds the given variable to the given execution state.
     */
    public function addVariable($name, $data, $info) {
        $this->info[$name] = $info + array(
            'skip save' => FALSE,
            'type' => 'unknown',
            'handler' => FALSE,
        );
        if (empty($this->info[$name]['handler'])) {
            $this->variables[$name] = rules_wrap_data($data, $this->info[$name]);
        }
    }
    
    /**
     * Runs post-evaluation tasks, such as saving variables.
     */
    public function cleanUp() {
        // Make changes permanent.
        foreach ($this->save
            ->getArrayCopy() as $selector => $wrapper) {
            $this->saveNow($selector);
        }
        unset($this->currentArguments);
    }
    
    /**
     * Block a rules configuration from execution.
     */
    public function block($rules_config) {
        if (empty($rules_config->recursion) && $rules_config->id) {
            self::$blocked[$rules_config->id] = TRUE;
        }
    }
    
    /**
     * Unblock a rules configuration from execution.
     */
    public function unblock($rules_config) {
        if (empty($rules_config->recursion) && $rules_config->id) {
            unset(self::$blocked[$rules_config->id]);
        }
    }
    
    /**
     * Returns whether a rules configuration should be blocked from execution.
     */
    public function isBlocked($rule_config) {
        return !empty($rule_config->id) && isset(self::$blocked[$rule_config->id]);
    }
    
    /**
     * Get the info about the state variables or a single variable.
     */
    public function varInfo($name = NULL) {
        if (isset($name)) {
            return isset($this->info[$name]) ? $this->info[$name] : FALSE;
        }
        return $this->info;
    }
    
    /**
     * Returns whether the given wrapper is saveable.
     */
    public function isSavable($wrapper) {
        return $wrapper instanceof EntityDrupalWrapper && entity_type_supports($wrapper->type(), 'save') || $wrapper instanceof RulesDataWrapperSavableInterface;
    }
    
    /**
     * Returns whether the variable with the given name is an entity.
     */
    public function isEntity($name) {
        $entity_info = entity_get_info();
        return isset($this->info[$name]['type']) && isset($entity_info[$this->info[$name]['type']]);
    }
    
    /**
     * Gets a variable.
     *
     * If necessary, the specified handler is invoked to fetch the variable.
     *
     * @param string $name
     *   The name of the variable to return.
     *
     * @return
     *   The variable or a EntityMetadataWrapper containing the variable.
     *
     * @throws RulesEvaluationException
     *   Throws a RulesEvaluationException in case we have info about the
     *   requested variable, but it is not defined.
     */
    public function &get($name) {
        if (!array_key_exists($name, $this->variables)) {
            // If there is handler to load the variable, do it now.
            if (!empty($this->info[$name]['handler'])) {
                $data = call_user_func($this->info[$name]['handler'], rules_unwrap_data($this->variables), $name, $this->info[$name]);
                $this->variables[$name] = rules_wrap_data($data, $this->info[$name]);
                $this->info[$name]['handler'] = FALSE;
                if (!isset($data)) {
                    throw new RulesEvaluationException('Unable to load variable %name, aborting.', array(
                        '%name' => $name,
                    ), NULL, RulesLog::INFO);
                }
            }
            else {
                throw new RulesEvaluationException('Unable to get variable %name, it is not defined.', array(
                    '%name' => $name,
                ), NULL, RulesLog::ERROR);
            }
        }
        return $this->variables[$name];
    }
    
    /**
     * Apply permanent changes provided the wrapper's data type is saveable.
     *
     * @param $selector
     *   The data selector of the wrapper to save or just a variable name.
     * @param $wrapper
     * @param bool $immediate
     *   Pass FALSE to postpone saving to later on. Else it's immediately saved.
     */
    public function saveChanges($selector, $wrapper, $immediate = FALSE) {
        $info = $wrapper->info();
        if (empty($info['skip save']) && $this->isSavable($wrapper)) {
            $this->save($selector, $wrapper, $immediate);
        }
        elseif (empty($info['skip save']) && isset($info['parent']) && !$wrapper instanceof EntityDrupalWrapper) {
            // Cut of the last part of the selector.
            $selector = implode(':', explode(':', $selector, -1));
            $this->saveChanges($selector, $info['parent'], $immediate);
        }
        return $this;
    }
    
    /**
     * Remembers to save the wrapper on cleanup or does it now.
     */
    protected function save($selector, EntityMetadataWrapper $wrapper, $immediate) {
        // Convert variable names and selectors to both use underscores.
        $selector = strtr($selector, '-', '_');
        if (isset($this->save[$selector])) {
            if ($this->save[$selector][0]
                ->getIdentifier() == $wrapper->getIdentifier()) {
                // The entity is already remembered. So do a combined save.
                $this->save[$selector][1] += self::$blocked;
            }
            else {
                // The wrapper is already in there, but wraps another entity. So first
                // save the old one, then care about the new one.
                $this->saveNow($selector);
            }
        }
        if (!isset($this->save[$selector])) {
            // In case of immediate saving don't clone the wrapper, so saving a new
            // entity immediately makes the identifier available afterwards.
            $this->save[$selector] = array(
                $immediate ? $wrapper : clone $wrapper,
                self::$blocked,
            );
        }
        if ($immediate) {
            $this->saveNow($selector);
        }
    }
    
    /**
     * Saves the wrapper for the given selector.
     */
    protected function saveNow($selector) {
        // Add the set of blocked elements for the recursion prevention.
        $previously_blocked = self::$blocked;
        self::$blocked += $this->save[$selector][1];
        // Actually save!
        $wrapper = $this->save[$selector][0];
        $entity = $wrapper->value();
        // When operating in hook_entity_insert() $entity->is_new might be still
        // set. In that case remove the flag to avoid causing another insert instead
        // of an update.
        if (!empty($entity->is_new) && $wrapper->getIdentifier()) {
            $entity->is_new = FALSE;
        }
        rules_log('Saved %selector of type %type.', array(
            '%selector' => $selector,
            '%type' => $wrapper->type(),
        ));
        $wrapper->save();
        // Restore the state's set of blocked elements.
        self::$blocked = $previously_blocked;
        unset($this->save[$selector]);
    }
    
    /**
     * Merges info from the given state into the existing state.
     *
     * Merges the info about to-be-saved variables from the given state into the
     * existing state. Therefore we can aggregate saves from invoked components.
     * Merged-in saves are removed from the given state, but not-mergeable saves
     * remain there.
     *
     * @param $state
     *   The state for which to merge the to be saved variables in.
     * @param $component
     *   The component which has been invoked, thus needs to be blocked for the
     *   merged in saves.
     * @param $settings
     *   The settings of the element that invoked the component. Contains
     *   information about variable/selector mappings between the states.
     */
    public function mergeSaveVariables(RulesState $state, RulesPlugin $component, $settings) {
        // For any saves that we take over, also block the component.
        $this->block($component);
        foreach ($state->save
            ->getArrayCopy() as $selector => $data) {
            $parts = explode(':', $selector, 2);
            // Adapt the selector to fit for the parent state and move the wrapper.
            if (isset($settings[$parts[0] . ':select'])) {
                $parts[0] = $settings[$parts[0] . ':select'];
                $this->save(implode(':', $parts), $data[0], FALSE);
                unset($state->save[$selector]);
            }
        }
        $this->unblock($component);
    }
    
    /**
     * Returns an entity metadata wrapper as specified in the selector.
     *
     * @param string $selector
     *   The selector string, e.g. "node:author:mail".
     * @param string $langcode
     *   (optional) The language code used to get the argument value if the
     *   argument value should be translated. Defaults to LANGUAGE_NONE.
     *
     * @return EntityMetadataWrapper
     *   The wrapper for the given selector.
     *
     * @throws RulesEvaluationException
     *   Throws a RulesEvaluationException in case the selector cannot be applied.
     */
    public function applyDataSelector($selector, $langcode = LANGUAGE_NONE) {
        $parts = explode(':', str_replace('-', '_', $selector), 2);
        $wrapper = $this->get($parts[0]);
        if (count($parts) == 1) {
            return $wrapper;
        }
        elseif (!$wrapper instanceof EntityMetadataWrapper) {
            throw new RulesEvaluationException('Unable to apply data selector %selector. The specified variable is not wrapped correctly.', array(
                '%selector' => $selector,
            ));
        }
        try {
            foreach (explode(':', $parts[1]) as $name) {
                if ($wrapper instanceof EntityListWrapper || $wrapper instanceof EntityStructureWrapper) {
                    // Make sure we are using the right language. Wrappers might be cached
                    // and have previous langcodes set, so always set the right language.
                    if ($wrapper instanceof EntityStructureWrapper) {
                        $wrapper->language($langcode);
                    }
                    $wrapper = $wrapper->get($name);
                }
                else {
                    throw new RulesEvaluationException('Unable to apply data selector %selector. The specified variable is not a list or a structure: %wrapper.', array(
                        '%selector' => $selector,
                        '%wrapper' => $wrapper,
                    ));
                }
            }
        } catch (EntityMetadataWrapperException $e) {
            // In case of an exception, re-throw it.
            throw new RulesEvaluationException('Unable to apply data selector %selector: %error', array(
                '%selector' => $selector,
                '%error' => $e->getMessage(),
            ));
        }
        return $wrapper;
    }
    
    /**
     * Magic method. Only serialize variables and their info.
     *
     * Additionally we remember currently blocked configs, so we can restore them
     * upon deserialization using restoreBlocks().
     */
    public function __sleep() {
        $this->currentlyBlocked = self::$blocked;
        return array(
            'info',
            'variables',
            'currentlyBlocked',
        );
    }
    
    /**
     * Magic method. Unserialize variables and their info.
     */
    public function __wakeup() {
        $this->save = new ArrayObject();
    }
    
    /**
     * Restores the before-serialization blocked configurations.
     *
     * Warning: This overwrites any possible currently blocked configs. Thus
     * do not invoke this method if there might be evaluations active.
     */
    public function restoreBlocks() {
        self::$blocked = $this->currentlyBlocked;
    }
    
    /**
     * Defines always-available variables.
     *
     * @param $key
     *   (optional)
     */
    public static function defaultVariables($key = NULL) {
        // Add a variable for accessing site-wide data properties.
        $vars['site'] = array(
            'type' => 'site',
            'label' => t('Site information'),
            'description' => t("Site-wide settings and other global information."),
            // Add the property info via a callback making use of the cached info.
'property info alter' => array(
                'RulesData',
                'addSiteMetadata',
            ),
            'property info' => array(),
            'optional' => TRUE,
        );
        return isset($key) ? $vars[$key] : $vars;
    }

}

/**
 * A class holding static methods related to data.
 */
class RulesData {
    
    /**
     * Returns whether the type match. They match if type1 is compatible to type2.
     *
     * @param $var_info
     *   The name of the type to check for whether it is compatible to type2.
     * @param $param_info
     *   The type expression to check for.
     * @param bool $ancestors
     *   (optional) Whether sub-type relationships for checking type compatibility
     *   should be taken into account. Defaults to TRUE.
     *
     * @return bool
     *   Whether the types match.
     */
    public static function typesMatch($var_info, $param_info, $ancestors = TRUE) {
        $var_type = $var_info['type'];
        $param_type = $param_info['type'];
        if ($param_type == '*' || $param_type == 'unknown') {
            return TRUE;
        }
        if ($var_type == $param_type) {
            // Make sure the bundle matches, if specified by the parameter.
            return !isset($param_info['bundles']) || isset($var_info['bundle']) && in_array($var_info['bundle'], $param_info['bundles']);
        }
        // Parameters may specify multiple types using an array.
        $valid_types = is_array($param_type) ? $param_type : array(
            $param_type,
        );
        if (in_array($var_type, $valid_types)) {
            return TRUE;
        }
        // Check for sub-type relationships.
        if ($ancestors && !isset($param_info['bundles'])) {
            $cache =& rules_get_cache();
            self::typeCalcAncestors($cache, $var_type);
            // If one of the types is an ancestor return TRUE.
            return (bool) array_intersect_key($cache['data_info'][$var_type]['ancestors'], array_flip($valid_types));
        }
        return FALSE;
    }
    protected static function typeCalcAncestors(&$cache, $type) {
        if (!isset($cache['data_info'][$type]['ancestors'])) {
            $cache['data_info'][$type]['ancestors'] = array();
            if (isset($cache['data_info'][$type]['parent']) && ($parent = $cache['data_info'][$type]['parent'])) {
                $cache['data_info'][$type]['ancestors'][$parent] = TRUE;
                self::typeCalcAncestors($cache, $parent);
                // Add all parent ancestors to our own ancestors.
                $cache['data_info'][$type]['ancestors'] += $cache['data_info'][$parent]['ancestors'];
            }
            // For special lists like list<node> add in "list" as valid parent.
            if (entity_property_list_extract_type($type)) {
                $cache['data_info'][$type]['ancestors']['list'] = TRUE;
            }
        }
    }
    
    /**
     * Returns data for the given info and the to-be-configured parameter.
     *
     * Returns matching data variables or properties for the given info and the
     * to-be-configured parameter.
     *
     * @param $source
     *   Either an array of info about available variables or a entity metadata
     *   wrapper.
     * @param $param_info
     *   The information array about the to be configured parameter.
     * @param string $prefix
     *   An optional prefix for the data selectors.
     * @param int $recursions
     *   The number of recursions used to go down the tree. Defaults to 2.
     * @param bool $suggestions
     *   Whether possibilities to recurse are suggested as soon as the deepest
     *   level of recursions is reached. Defaults to TRUE.
     *
     * @return array
     *   An array of info about matching variables or properties that match, keyed
     *   with the data selector.
     */
    public static function matchingDataSelector($source, $param_info, $prefix = '', $recursions = 2, $suggestions = TRUE) {
        // If an array of info is given, get entity metadata wrappers first.
        $data = NULL;
        if (is_array($source)) {
            foreach ($source as $name => $info) {
                $source[$name] = rules_wrap_data($data, $info, TRUE);
            }
        }
        $matches = array();
        foreach ($source as $name => $wrapper) {
            $info = $wrapper->info();
            $name = str_replace('_', '-', $name);
            if (self::typesMatch($info, $param_info)) {
                $matches[$prefix . $name] = $info;
                if (!is_array($source) && $source instanceof EntityListWrapper) {
                    // Add some more possible list items.
                    for ($i = 1; $i < 4; $i++) {
                        $matches[$prefix . $i] = $info;
                    }
                }
            }
            // Recurse later on to get an improved ordering of the results.
            if ($wrapper instanceof EntityStructureWrapper || $wrapper instanceof EntityListWrapper) {
                $recurse[$prefix . $name] = $wrapper;
                if ($recursions > 0) {
                    $matches += self::matchingDataSelector($wrapper, $param_info, $prefix . $name . ':', $recursions - 1, $suggestions);
                }
                elseif ($suggestions) {
                    // We may not recurse any more,
                    // but indicate the possibility to recurse.
                    $matches[$prefix . $name . ':'] = $wrapper->info();
                    if (!is_array($source) && $source instanceof EntityListWrapper) {
                        // Add some more possible list items.
                        for ($i = 1; $i < 4; $i++) {
                            $matches[$prefix . $i . ':'] = $wrapper->info();
                        }
                    }
                }
            }
        }
        return $matches;
    }
    
    /**
     * Adds asserted metadata to the variable info.
     *
     * In case there are already assertions for a variable, the assertions are
     * merged such that both apply.
     *
     * @see RulesData::applyMetadataAssertions()
     */
    public static function addMetadataAssertions($var_info, $assertions) {
        foreach ($assertions as $selector => $assertion) {
            // Convert the selector back to underscores, such it matches the varname.
            $selector = str_replace('-', '_', $selector);
            $parts = explode(':', $selector);
            if (isset($var_info[$parts[0]])) {
                // Apply the selector to determine the right target array. We build an
                // array like
                // $var_info['rules assertion']['property1']['property2']['#info'] = ..
                $target =& $var_info[$parts[0]]['rules assertion'];
                foreach (array_slice($parts, 1) as $part) {
                    $target =& $target[$part];
                }
                // In case the assertion is directly for a variable, we have to modify
                // the variable info directly. In case the asserted property is nested
                // the info-has to be altered by RulesData::applyMetadataAssertions()
                // before the child-wrapper is created.
                if (count($parts) == 1) {
                    // Support asserting a type in case of generic entity references only.
                    $var_type =& $var_info[$parts[0]]['type'];
                    if (isset($assertion['type']) && ($var_type == 'entity' || $var_type == 'list<entity>')) {
                        $var_type = $assertion['type'];
                        unset($assertion['type']);
                    }
                    // Add any single bundle directly to the variable info, so the
                    // variable fits as argument for parameters requiring the bundle.
                    if (isset($assertion['bundle']) && count($bundles = (array) $assertion['bundle']) == 1) {
                        $var_info[$parts[0]]['bundle'] = reset($bundles);
                    }
                }
                // Add the assertions, but merge them with any previously added
                // assertions if necessary.
                $target['#info'] = isset($target['#info']) ? rules_update_array($target['#info'], $assertion) : $assertion;
                // Add in a callback that the entity metadata wrapper pick up for
                // altering the property info, such that we can add in the assertions.
                $var_info[$parts[0]] += array(
                    'property info alter' => array(
                        'RulesData',
                        'applyMetadataAssertions',
                    ),
                );
                // In case there is a VARNAME_unchanged variable as it is used in update
                // hooks, assume the assertions are valid for the unchanged variable
                // too.
                if (isset($var_info[$parts[0] . '_unchanged'])) {
                    $name = $parts[0] . '_unchanged';
                    $var_info[$name]['rules assertion'] = $var_info[$parts[0]]['rules assertion'];
                    $var_info[$name]['property info alter'] = array(
                        'RulesData',
                        'applyMetadataAssertions',
                    );
                    if (isset($var_info[$parts[0]]['bundle']) && !isset($var_info[$name]['bundle'])) {
                        $var_info[$name]['bundle'] = $var_info[$parts[0]]['bundle'];
                    }
                }
            }
        }
        return $var_info;
    }
    
    /**
     * Property info alter callback for the entity metadata wrapper.
     *
     * Used for applying the rules metadata assertions.
     *
     * @see RulesData::addMetadataAssertions()
     */
    public static function applyMetadataAssertions(EntityMetadataWrapper $wrapper, $property_info) {
        $info = $wrapper->info();
        if (!empty($info['rules assertion'])) {
            $assertion = $info['rules assertion'];
            // In case there are list-wrappers pass through the assertions of the item
            // but make sure we only apply the assertions for the list items for
            // which the conditions are executed.
            if (isset($info['parent']) && $info['parent'] instanceof EntityListWrapper) {
                $assertion = isset($assertion[$info['name']]) ? $assertion[$info['name']] : array();
            }
            // Support specifying multiple bundles, whereas the added properties are
            // the intersection of the bundle properties.
            if (isset($assertion['#info']['bundle'])) {
                $bundles = (array) $assertion['#info']['bundle'];
                foreach ($bundles as $bundle) {
                    $properties[] = isset($property_info['bundles'][$bundle]['properties']) ? $property_info['bundles'][$bundle]['properties'] : array();
                }
                // Add the intersection.
                $property_info['properties'] += count($properties) > 1 ? call_user_func_array('array_intersect_key', $properties) : reset($properties);
            }
            // Support adding directly asserted property info.
            if (isset($assertion['#info']['property info'])) {
                $property_info['properties'] += $assertion['#info']['property info'];
            }
            // Pass through any rules assertion of properties to their info, so any
            // derived wrappers apply it.
            foreach (element_children($assertion) as $key) {
                $property_info['properties'][$key]['rules assertion'] = $assertion[$key];
                $property_info['properties'][$key]['property info alter'] = array(
                    'RulesData',
                    'applyMetadataAssertions',
                );
                // Apply any 'type' and 'bundle' assertion directly to the property
                // info.
                if (isset($assertion[$key]['#info']['type'])) {
                    $type = $assertion[$key]['#info']['type'];
                    // Support asserting a type in case of generic entity references only.
                    if ($property_info['properties'][$key]['type'] == 'entity' && entity_get_info($type)) {
                        $property_info['properties'][$key]['type'] = $type;
                    }
                }
                if (isset($assertion[$key]['#info']['bundle'])) {
                    $bundle = (array) $assertion[$key]['#info']['bundle'];
                    // Add any single bundle directly to the variable info, so the
                    // property fits as argument for parameters requiring the bundle.
                    if (count($bundle) == 1) {
                        $property_info['properties'][$key]['bundle'] = reset($bundle);
                    }
                }
            }
        }
        return $property_info;
    }
    
    /**
     * Property info alter callback for the entity metadata wrapper.
     *
     * Used to inject metadata for the 'site' variable. In contrast to doing this
     * via hook_rules_data_info() this callback makes use of the already existing
     * property info cache for site information of entity metadata.
     *
     * @see RulesPlugin::availableVariables()
     */
    public static function addSiteMetadata(EntityMetadataWrapper $wrapper, $property_info) {
        $site_info = entity_get_property_info('site');
        $property_info['properties'] += $site_info['properties'];
        // Also invoke the usual callback for altering metadata, in case actions
        // have specified further metadata.
        return RulesData::applyMetadataAssertions($wrapper, $property_info);
    }

}

/**
 * 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 saveable 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().
 */
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);

}

/**
 * Used to declare custom wrapper classes as saveable.
 */
interface RulesDataWrapperSavableInterface {
    
    /**
     * Save the currently wrapped data.
     */
    public function save();

}