www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/file_mdm/src/Plugin/FileMetadataPluginInterface.php

   1 <?php
   2
   3 namespace Drupal\file_mdm\Plugin;
   4
   5 use Drupal\Component\Plugin\PluginInspectionInterface;
   6 use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
   7 use Drupal\Core\Plugin\PluginFormInterface;
   8
   9 /**
  10  * Provides an interface defining a FileMetadata plugin.
  11  */
  12 interface FileMetadataPluginInterface extends ContainerFactoryPluginInterface, PluginInspectionInterface, PluginFormInterface {
  13
  14   /**
  15    * Gets default configuration for this plugin.
  16    *
  17    * @return array
  18    *   An associative array with the default configuration.
  19    */
  20   public static function defaultConfiguration();
  21
  22   /**
  23    * Sets the URI of the file.
  24    *
  25    * @param string $uri
  26    *   A URI.
  27    *
  28    * @return $this
  29    *
  30    * @throws \Drupal\file_mdm\FileMetadataException
  31    *   If no URI is specified.
  32    */
  33   public function setUri($uri);
  34
  35   /**
  36    * Gets the URI of the file.
  37    *
  38    * @return string
  39    *   The URI of the file.
  40    */
  41   public function getUri();
  42
  43   /**
  44    * Sets the local filesystem path to the file.
  45    *
  46    * This is used to allow accessing local copies of files stored remotely, to
  47    * minimise remote calls and allow functions that cannot access remote stream
  48    * wrappers to operate locally.
  49    *
  50    * @param string $temp_path
  51    *   A filesystem path.
  52    *
  53    * @return $this
  54    */
  55   public function setLocalTempPath($temp_path);
  56
  57   /**
  58    * Gets the local filesystem path to the file.
  59    *
  60    * This is used to allow accessing local copies of files stored remotely, to
  61    * minimise remote calls and allow functions that cannot access remote stream
  62    * wrappers to operate locally.
  63    *
  64    * @return string
  65    *   The local filesystem path to the file.
  66    */
  67   public function getLocalTempPath();
  68
  69   /**
  70    * Sets the hash used to reference the URI by the metadata manager.
  71    *
  72    * @param string $hash
  73    *   A hash string.
  74    *
  75    * @return $this
  76    *
  77    * @throws \Drupal\file_mdm\FileMetadataException
  78    *   If no hash is specified.
  79    */
  80   public function setHash($hash);
  81
  82   /**
  83    * Returns a list of metadata keys supported by the plugin.
  84    *
  85    * @param mixed $options
  86    *   (optional) Allows specifying additional options to control the list of
  87    *   metadata keys returned.
  88    *
  89    * @return array
  90    *   A simple array of metadata keys supported.
  91    */
  92   public function getSupportedKeys($options = NULL);
  93
  94   /**
  95    * Checks if file metadata has been already loaded.
  96    *
  97    * @return bool
  98    *   TRUE if metadata is loaded, FALSE otherwise.
  99    */
 100   public function isMetadataLoaded();
 101
 102   /**
 103    * Loads file metadata from an in-memory object/array.
 104    *
 105    * @param mixed $metadata
 106    *   The file metadata associated to the file at URI.
 107    *
 108    * @return bool
 109    *   TRUE if metadata was loaded successfully, FALSE otherwise.
 110    */
 111   public function loadMetadata($metadata);
 112
 113   /**
 114    * Loads file metadata from the file at URI/local path.
 115    *
 116    * @return bool
 117    *   TRUE if metadata was loaded successfully, FALSE otherwise.
 118    *
 119    * @throws \Drupal\file_mdm\FileMetadataException
 120    *   In case there were significant errors reading from file.
 121    */
 122   public function loadMetadataFromFile();
 123
 124   /**
 125    * Loads file metadata from a cache entry.
 126    *
 127    * @return bool
 128    *   TRUE if metadata was loaded successfully, FALSE otherwise.
 129    *
 130    * @throws \Drupal\file_mdm\FileMetadataException
 131    *   In case of significant errors.
 132    */
 133   public function loadMetadataFromCache();
 134
 135   /**
 136    * Gets a metadata element.
 137    *
 138    * @param mixed|null $key
 139    *   A key to determine the metadata element to be returned. If NULL, the
 140    *   entire metadata will be returned.
 141    *
 142    * @return mixed
 143    *   The value of the element specified by $key. If $key is NULL, the entire
 144    *   metadata.
 145    */
 146   public function getMetadata($key = NULL);
 147
 148   /**
 149    * Sets a metadata element.
 150    *
 151    * @param mixed $key
 152    *   A key to determine the metadata element to be changed.
 153    * @param mixed $value
 154    *   The value to change the metadata element to.
 155    *
 156    * @return bool
 157    *   TRUE if metadata was changed successfully, FALSE otherwise.
 158    */
 159   public function setMetadata($key, $value);
 160
 161   /**
 162    * Removes a metadata element.
 163    *
 164    * @param mixed $key
 165    *   A key to determine the metadata element to be removed.
 166    *
 167    * @return bool
 168    *   TRUE if metadata was removed successfully, FALSE otherwise.
 169    */
 170   public function removeMetadata($key);
 171
 172   /**
 173    * Determines if plugin is capable of writing metadata to files.
 174    *
 175    * @return bool
 176    *   TRUE if plugin can save data to files, FALSE otherwise.
 177    */
 178   public function isSaveToFileSupported();
 179
 180   /**
 181    * Saves metadata to file at URI.
 182    *
 183    * @return bool
 184    *   TRUE if metadata was saved successfully, FALSE otherwise.
 185    */
 186   public function saveMetadataToFile();
 187
 188   /**
 189    * Caches metadata for file at URI.
 190    *
 191    * Uses the 'file_mdm' cache bin.
 192    *
 193    * @param array $tags
 194    *   (optional) An array of cache tags to save to cache.
 195    *
 196    * @return bool
 197    *   TRUE if metadata was saved successfully, FALSE otherwise.
 198    */
 199   public function saveMetadataToCache(array $tags = []);
 200
 201   /**
 202    * Removes cached metadata for file at URI.
 203    *
 204    * Uses the 'file_mdm' cache bin.
 205    *
 206    * @return bool
 207    *   TRUE if metadata was removed, FALSE otherwise.
 208    */
 209   public function deleteCachedMetadata();
 210
 211 }