Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Component\Plugin;
Chris@0: 
Chris@0: /**
Chris@0:  * Defines an object which stores multiple plugin instances to lazy load them.
Chris@0:  *
Chris@0:  * @ingroup plugin_api
Chris@0:  */
Chris@0: abstract class LazyPluginCollection implements \IteratorAggregate, \Countable {
Chris@0: 
Chris@0:   /**
Chris@0:    * Stores all instantiated plugins.
Chris@0:    *
Chris@0:    * @var array
Chris@0:    */
Chris@0:   protected $pluginInstances = [];
Chris@0: 
Chris@0:   /**
Chris@0:    * Stores the IDs of all potential plugin instances.
Chris@0:    *
Chris@0:    * @var array
Chris@0:    */
Chris@0:   protected $instanceIDs = [];
Chris@0: 
Chris@0:   /**
Chris@0:    * Initializes and stores a plugin.
Chris@0:    *
Chris@0:    * @param string $instance_id
Chris@0:    *   The ID of the plugin instance to initialize.
Chris@0:    */
Chris@0:   abstract protected function initializePlugin($instance_id);
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the current configuration of all plugins in this collection.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of up-to-date plugin configuration.
Chris@0:    */
Chris@0:   abstract public function getConfiguration();
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the configuration for all plugins in this collection.
Chris@0:    *
Chris@0:    * @param array $configuration
Chris@0:    *   An array of up-to-date plugin configuration.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   abstract public function setConfiguration($configuration);
Chris@0: 
Chris@0:   /**
Chris@0:    * Clears all instantiated plugins.
Chris@0:    */
Chris@0:   public function clear() {
Chris@0:     $this->pluginInstances = [];
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Determines if a plugin instance exists.
Chris@0:    *
Chris@0:    * @param string $instance_id
Chris@0:    *   The ID of the plugin instance to check.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the plugin instance exists, FALSE otherwise.
Chris@0:    */
Chris@0:   public function has($instance_id) {
Chris@0:     return isset($this->pluginInstances[$instance_id]) || isset($this->instanceIDs[$instance_id]);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets a plugin instance, initializing it if necessary.
Chris@0:    *
Chris@0:    * @param string $instance_id
Chris@0:    *   The ID of the plugin instance being retrieved.
Chris@0:    */
Chris@0:   public function &get($instance_id) {
Chris@0:     if (!isset($this->pluginInstances[$instance_id])) {
Chris@0:       $this->initializePlugin($instance_id);
Chris@0:     }
Chris@0:     return $this->pluginInstances[$instance_id];
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Stores an initialized plugin.
Chris@0:    *
Chris@0:    * @param string $instance_id
Chris@0:    *   The ID of the plugin instance being stored.
Chris@0:    * @param mixed $value
Chris@0:    *   An instantiated plugin.
Chris@0:    */
Chris@0:   public function set($instance_id, $value) {
Chris@0:     $this->pluginInstances[$instance_id] = $value;
Chris@0:     $this->addInstanceId($instance_id);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Removes an initialized plugin.
Chris@0:    *
Chris@0:    * The plugin can still be used; it will be reinitialized.
Chris@0:    *
Chris@0:    * @param string $instance_id
Chris@0:    *   The ID of the plugin instance to remove.
Chris@0:    */
Chris@0:   public function remove($instance_id) {
Chris@0:     unset($this->pluginInstances[$instance_id]);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Adds an instance ID to the available instance IDs.
Chris@0:    *
Chris@0:    * @param string $id
Chris@0:    *   The ID of the plugin instance to add.
Chris@0:    * @param array|null $configuration
Chris@0:    *   (optional) The configuration used by this instance. Defaults to NULL.
Chris@0:    */
Chris@0:   public function addInstanceId($id, $configuration = NULL) {
Chris@0:     if (!isset($this->instanceIDs[$id])) {
Chris@0:       $this->instanceIDs[$id] = $id;
Chris@0:     }
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets all instance IDs.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of all available instance IDs.
Chris@0:    */
Chris@0:   public function getInstanceIds() {
Chris@0:     return $this->instanceIDs;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Removes an instance ID.
Chris@0:    *
Chris@0:    * @param string $instance_id
Chris@0:    *   The ID of the plugin instance to remove.
Chris@0:    */
Chris@0:   public function removeInstanceId($instance_id) {
Chris@0:     unset($this->instanceIDs[$instance_id]);
Chris@0:     $this->remove($instance_id);
Chris@0:   }
Chris@0: 
Chris@0:   public function getIterator() {
Chris@0:     $instances = [];
Chris@0:     foreach ($this->getInstanceIds() as $instance_id) {
Chris@0:       $instances[$instance_id] = $this->get($instance_id);
Chris@0:     }
Chris@0:     return new \ArrayIterator($instances);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * {@inheritdoc}
Chris@0:    */
Chris@0:   public function count() {
Chris@0:     return count($this->instanceIDs);
Chris@0:   }
Chris@0: 
Chris@0: }