abstract class FeedsConfigurable in Feeds 7.2

Base class for configurable classes.

Captures configuration handling, form handling and distinguishes between in-memory configuration and persistent configuration.

Due to the magic method __get(), protected properties from this class and from classes that extend this class will be publicly readable (but not writeable).

Hierarchy

• class \FeedsConfigurable

File

includes/FeedsConfigurable.inc, line 24

FeedsConfigurable and helper functions.

abstract class FeedsConfigurable {

  /**
   * Holds the actual configuration information.
   *
   * @var array
   */
  protected $config;

  /**
   * An unique identifier for the configuration.
   *
   * @var string
   */
  protected $id;

  /**
   * CTools export type of this object.
   *
   * Export type can be one of:
   * - FEEDS_EXPORT_NONE - the configurable only exists in memory.
   * - EXPORT_IN_DATABASE - the configurable is defined in the database.
   * - EXPORT_IN_CODE - the configurable is defined in code.
   * - EXPORT_IN_CODE | EXPORT_IN_DATABASE - the configurable is defined in
   *   code, but overridden in the database.
   *
   * @var int
   *
   * @todo Should live in FeedsImporter. Not all child classes
   * of FeedsConfigurable are exportable. Same goes for $disabled.
   */
  protected $export_type;

  /**
   * CTools export enabled status of this object.
   *
   * @var bool
   */
  protected $disabled;

  /**
   * Provides a statically cached instance of a FeedsConfigurable subclass.
   *
   * Don't use directly, use feeds_importer() or feeds_plugin() instead.
   *
   * @param string $class
   *   The name of a subclass of FeedsConfigurable.
   * @param string $id
   *   The ID of this configuration object.
   *
   * @return FeedsConfigurable
   *   An instance of this class.
   *
   * @throws InvalidArgumentException
   *   When an empty configuration identifier is passed.
   *
   * @see feeds_importer()
   * @see feeds_plugin()
   */
  public static function instance($class, $id) {

    // @todo Verify that $class is an existing subclass of FeedsConfigurable.
    if (!strlen($id)) {
      throw new InvalidArgumentException(t('Empty configuration identifier.'));
    }
    $instances =& drupal_static(__METHOD__, array());
    if (!isset($instances[$class][$id])) {
      $instances[$class][$id] = new $class($id);
    }
    return $instances[$class][$id];
  }

  /**
   * Constructor, set id and load default configuration.
   *
   * @param string $id
   *   The ID of this configuration object.
   */
  protected function __construct($id) {

    // Set this object's id.
    $this->id = $id;

    // Per default we assume that a Feeds object is not saved to
    // database nor is it exported to code.
    $this->export_type = FEEDS_EXPORT_NONE;

    // Make sure configuration is populated.
    $this->config = $this
      ->configDefaults();
    $this->disabled = FALSE;
  }

  /**
   * Override magic method __isset(). This is needed due to overriding __get().
   */
  public function __isset($name) {
    return isset($this->{$name}) ? TRUE : FALSE;
  }

  /**
   * Determine whether this object is persistent.
   *
   * @return bool
   *   True if the object is persistent.
   *   False otherwise.
   */
  public function doesExist() {
    return $this->export_type == FEEDS_EXPORT_NONE ? FALSE : TRUE;
  }

  /**
   * Determine whether this object is enabled.
   *
   * @return bool
   *   True if the object is enabled.
   *   False otherwise.
   */
  public function isEnabled() {
    return $this->disabled ? FALSE : TRUE;
  }

  /**
   * Determines whether this object is persistent and enabled.
   *
   * This means that it exists either in code or in the database and it is
   * enabled.
   *
   * @return $this
   *
   * @throws FeedsNotExistingException
   *   When the object is not persistent or is not enabled.
   */
  public function existing() {
    if (!$this
      ->doesExist()) {
      throw new FeedsNotExistingException(t('Object is not persistent.'));
    }
    if (!$this
      ->isEnabled()) {
      throw new FeedsNotExistingException(t('Object is disabled.'));
    }
    return $this;
  }

  /**
   * Saves a configuration.
   *
   * Concrete extending classes must implement a save operation.
   */
  public abstract function save();

  /**
   * Copy a configuration.
   *
   * @param FeedsConfigurable $configurable
   *   The FeedsConfigurable instance to take the configuration from.
   */
  public function copy(FeedsConfigurable $configurable) {
    $this
      ->setConfig($configurable->config);
  }

  /**
   * Set configuration.
   *
   * @param array $config
   *   Array containing configuration information. Config array will be filtered
   *   by the keys returned by configDefaults() and populated with default
   *   values that are not included in $config.
   */
  public function setConfig($config) {
    $defaults = $this
      ->configDefaults();
    $this->config = array_intersect_key($config, $defaults) + $defaults;
  }

  /**
   * Similar to setConfig but adds to existing configuration.
   *
   * @param array $config
   *   Array containing configuration information. Will be filtered by the keys
   *   returned by configDefaults().
   */
  public function addConfig($config) {
    $this->config = is_array($this->config) ? array_merge($this->config, $config) : $config;
    $default_keys = $this
      ->configDefaults();
    $this->config = array_intersect_key($this->config, $default_keys);
  }

  /**
   * Overrides magic method __get().
   *
   * - Makes sure that external reads of FeedsConfigurable::config go through
   *   ::getConfig();
   * - Makes private and protected properties from this class and protected
   *   properties from child classes publicly readable.
   * - Prevents warnings when accessing non-existent properties.
   */
  public function __get($name) {
    if ($name == 'config') {
      return $this
        ->getConfig();
    }
    return isset($this->{$name}) ? $this->{$name} : NULL;
  }

  /**
   * Implements getConfig().
   *
   * Returns configuration array, ensure that all default values are present.
   *
   * @return array
   *   The configuration for this object.
   */
  public function getConfig() {
    $defaults = $this
      ->configDefaults();
    return $this->config + $defaults;
  }

  /**
   * Return default configuration.
   *
   * @todo rename to getConfigDefaults().
   *
   * @return array
   *   Array where keys are the variable names of the configuration elements and
   *   values are their default values.
   */
  public function configDefaults() {
    return array() + module_invoke_all('feeds_config_defaults', $this);
  }

  /**
   * Validates the configuration.
   *
   * @return array
   *   A list of errors.
   */
  public function validateConfig() {
    return array();
  }

  /**
   * Returns whether or not the configurable has a config form.
   *
   * @return bool
   *   True if the configurable has a config form, and false if not.
   */
  public function hasConfigForm() {
    $form_state = array();
    return (bool) $this
      ->configForm($form_state);
  }

  /**
   * Returns configuration form for this object.
   *
   * The keys of the configuration form must match the keys of the array
   * returned by configDefaults().
   *
   * @param array $form_state
   *   The current state of the form.
   *
   * @return array
   *   FormAPI style form definition.
   */
  public function configForm(&$form_state) {
    return array();
  }

  /**
   * Validation handler for configForm().
   *
   * Set errors with form_set_error().
   *
   * @param array $values
   *   An array that contains the values entered by the user through configForm.
   */
  public function configFormValidate(&$values) {
  }

  /**
   * Submission handler for configForm().
   *
   * @param array $values
   *   An array that contains the values entered by the user through configForm.
   */
  public function configFormSubmit(&$values) {
    $this
      ->addConfig($values);
    $this
      ->save();
    drupal_set_message(t('Your changes have been saved.'));
    feeds_cache_clear(FALSE);
  }

  /**
   * Returns an array of required modules.
   *
   * @return array
   *   The modules that this configurable requires.
   */
  public function dependencies() {
    return array();
  }

}

Members

Name	Modifiers	Type	Description	Overrides
FeedsConfigurable::$config	protected	property	Holds the actual configuration information.
FeedsConfigurable::$disabled	protected	property	CTools export enabled status of this object.
FeedsConfigurable::$export_type	protected	property	CTools export type of this object.
FeedsConfigurable::$id	protected	property	An unique identifier for the configuration.
FeedsConfigurable::addConfig	public	function	Similar to setConfig but adds to existing configuration.
FeedsConfigurable::configDefaults	public	function	Return default configuration.	3
FeedsConfigurable::configForm	public	function	Returns configuration form for this object.	6
FeedsConfigurable::configFormSubmit	public	function	Submission handler for configForm().	2
FeedsConfigurable::configFormValidate	public	function	Validation handler for configForm().	3
FeedsConfigurable::copy	public	function	Copy a configuration.	1
FeedsConfigurable::dependencies	public	function	Returns an array of required modules.	3
FeedsConfigurable::doesExist	public	function	Determine whether this object is persistent.	1
FeedsConfigurable::existing	public	function	Determines whether this object is persistent and enabled.	1
FeedsConfigurable::getConfig	public	function	Implements getConfig().	1
FeedsConfigurable::hasConfigForm	public	function	Returns whether or not the configurable has a config form.
FeedsConfigurable::instance	public static	function	Provides a statically cached instance of a FeedsConfigurable subclass.	2
FeedsConfigurable::isEnabled	public	function	Determine whether this object is enabled.
FeedsConfigurable::save	abstract public	function	Saves a configuration.	3
FeedsConfigurable::setConfig	public	function	Set configuration.
FeedsConfigurable::validateConfig	public	function	Validates the configuration.	2
FeedsConfigurable::__construct	protected	function	Constructor, set id and load default configuration.	3
FeedsConfigurable::__get	public	function	Overrides magic method __get().
FeedsConfigurable::__isset	public	function	Override magic method __isset(). This is needed due to overriding __get().