www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/StreamWrapper/StreamWrapperManagerInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\StreamWrapper;
   4
   5 /**
   6  * Provides a StreamWrapper manager.
   7  *
   8  * @see \Drupal\Core\StreamWrapper\StreamWrapperInterface
   9  */
  10 interface StreamWrapperManagerInterface {
  11
  12   /**
  13    * Provides Drupal stream wrapper registry.
  14    *
  15    * A stream wrapper is an abstraction of a file system that allows Drupal to
  16    * use the same set of methods to access both local files and remote
  17    * resources.
  18    *
  19    * Provide a facility for managing and querying user-defined stream wrappers
  20    * in PHP. PHP's internal stream_get_wrappers() doesn't return the class
  21    * registered to handle a stream, which we need to be able to find the
  22    * handler
  23    * for class instantiation.
  24    *
  25    * If a module registers a scheme that is already registered with PHP, the
  26    * existing scheme will be unregistered and replaced with the specified
  27    * class.
  28    *
  29    * A stream is referenced as "scheme://target".
  30    *
  31    * The optional $filter parameter can be used to retrieve only the stream
  32    * wrappers that are appropriate for particular usage. For example, this
  33    * returns only stream wrappers that use local file storage:
  34    *
  35    * @code
  36    *   $stream_wrapper_manager = \Drupal::service('stream_wrapper_manager');
  37    *   $local_stream_wrappers = $stream_wrapper_manager->getWrappers(StreamWrapperInterface::LOCAL);
  38    * @endcode
  39    *
  40    * The $filter parameter can only filter to types containing a particular
  41    * flag. In some cases, you may want to filter to types that do not contain a
  42    * particular flag. For example, you may want to retrieve all stream wrappers
  43    * that are not writable, or all stream wrappers that are not local. PHP's
  44    * array_diff_key() function can be used to help with this. For example, this
  45    * returns only stream wrappers that do not use local file storage:
  46    * @code
  47    *   $stream_wrapper_manager = \Drupal::service('stream_wrapper_manager');
  48    *   $remote_stream_wrappers = array_diff_key(
  49    *     $stream_wrapper_manager->getWrappers(StreamWrapperInterface::ALL),
  50    *     $stream_wrapper_manager->getWrappers(StreamWrapperInterface::LOCAL)
  51    *   );
  52    * @endcode
  53    *
  54    * @param int $filter
  55    *   (Optional) Filters out all types except those with an on bit for each on
  56    *   bit in $filter. For example, if $filter is
  57    *   StreamWrapperInterface::WRITE_VISIBLE, which is equal to
  58    *   (StreamWrapperInterface::READ | StreamWrapperInterface::WRITE |
  59    *   StreamWrapperInterface::VISIBLE), then only stream wrappers with all
  60    *   three of these bits set are returned. Defaults to
  61    *   StreamWrapperInterface::ALL, which returns all registered stream
  62    *   wrappers.
  63    *
  64    * @return array
  65    *   An array keyed by scheme, with values containing an array of information
  66    *   about the stream wrapper, as returned by hook_stream_wrappers(). If
  67    *   $filter is omitted or set to StreamWrapperInterface::ALL, the entire
  68    *   Drupal stream wrapper registry is returned. Otherwise only the stream
  69    *   wrappers whose 'type' bitmask has an on bit for each bit specified in
  70    *   $filter are returned.
  71    */
  72   public function getWrappers($filter = StreamWrapperInterface::ALL);
  73
  74   /**
  75    * Returns registered stream wrapper names.
  76    *
  77    * @param int $filter
  78    *   (Optional) Filters out all types except those with an on bit for each on
  79    *   bit in $filter. For example, if $filter is
  80    *   StreamWrapperInterface::WRITE_VISIBLE, which is equal to
  81    *   (StreamWrapperInterface::READ | StreamWrapperInterface::WRITE |
  82    *   StreamWrapperInterface::VISIBLE), then only stream wrappers with all
  83    *   three of these bits set are returned. Defaults to
  84    *   StreamWrapperInterface::ALL, which returns all registered stream
  85    *   wrappers.
  86    *
  87    * @return array
  88    *   Stream wrapper names, keyed by scheme.
  89    */
  90   public function getNames($filter = StreamWrapperInterface::ALL);
  91
  92   /**
  93    * Returns registered stream wrapper descriptions.
  94    *
  95    * @param int $filter
  96    *   (Optional) Filters out all types except those with an on bit for each on
  97    *   bit in $filter. For example, if $filter is
  98    *   StreamWrapperInterface::WRITE_VISIBLE, which is equal to
  99    *   (StreamWrapperInterface::READ | StreamWrapperInterface::WRITE |
 100    *   StreamWrapperInterface::VISIBLE), then only stream wrappers with all
 101    *   three of these bits set are returned. Defaults to
 102    *   StreamWrapperInterface::ALL, which returns all registered stream
 103    *   wrappers.
 104    *
 105    * @return array
 106    *   Stream wrapper descriptions, keyed by scheme.
 107    */
 108   public function getDescriptions($filter = StreamWrapperInterface::ALL);
 109
 110   /**
 111    * Returns a reference to the stream wrapper class responsible for a scheme.
 112    *
 113    * This helper method returns a stream instance using a scheme. That is, the
 114    * passed string does not contain a "://". For example, "public" is a scheme
 115    * but "public://" is a URI (stream). This is because the later contains both
 116    * a scheme and target despite target being empty.
 117    *
 118    * Note: the instance URI will be initialized to "scheme://" so that you can
 119    * make the customary method calls as if you had retrieved an instance by URI.
 120    *
 121    * @param string $scheme
 122    *   If the stream was "public://target", "public" would be the scheme.
 123    *
 124    * @return \Drupal\Core\StreamWrapper\StreamWrapperInterface|bool
 125    *   Returns a new stream wrapper object appropriate for the given $scheme.
 126    *   For example, for the public scheme a stream wrapper object
 127    *   (Drupal\Core\StreamWrapper\PublicStream).
 128    *   FALSE is returned if no registered handler could be found.
 129    */
 130   public function getViaScheme($scheme);
 131
 132   /**
 133    * Returns a reference to the stream wrapper class responsible for a URI.
 134    *
 135    * The scheme determines the stream wrapper class that should be
 136    * used by consulting the stream wrapper registry.
 137    *
 138    * @param string $uri
 139    *   A stream, referenced as "scheme://target".
 140    *
 141    * @return \Drupal\Core\StreamWrapper\StreamWrapperInterface|bool
 142    *   Returns a new stream wrapper object appropriate for the given URI or
 143    *   FALSE if no registered handler could be found. For example, a URI of
 144    *   "private://example.txt" would return a new private stream wrapper object
 145    *   (Drupal\Core\StreamWrapper\PrivateStream).
 146    */
 147   public function getViaUri($uri);
 148
 149   /**
 150    * Returns the stream wrapper class name for a given scheme.
 151    *
 152    * @param string $scheme
 153    *   Stream scheme.
 154    *
 155    * @return string|bool
 156    *   Return string if a scheme has a registered handler, or FALSE.
 157    */
 158   public function getClass($scheme);
 159
 160   /**
 161    * Registers stream wrapper with PHP.
 162    *
 163    * @param string $scheme
 164    *   The scheme of the stream wrapper.
 165    * @param string $class
 166    *   The class of the stream wrapper.
 167    * @param int $type
 168    *   The type of the stream wrapper.
 169    */
 170   public function registerWrapper($scheme, $class, $type);
 171
 172 }