Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\StreamWrapper;
Chris@0: 
Chris@0: /**
Chris@0:  * Provides a StreamWrapper manager.
Chris@0:  *
Chris@0:  * @see \Drupal\Core\StreamWrapper\StreamWrapperInterface
Chris@0:  */
Chris@0: interface StreamWrapperManagerInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Provides Drupal stream wrapper registry.
Chris@0:    *
Chris@0:    * A stream wrapper is an abstraction of a file system that allows Drupal to
Chris@0:    * use the same set of methods to access both local files and remote
Chris@0:    * resources.
Chris@0:    *
Chris@0:    * Provide a facility for managing and querying user-defined stream wrappers
Chris@0:    * in PHP. PHP's internal stream_get_wrappers() doesn't return the class
Chris@0:    * registered to handle a stream, which we need to be able to find the
Chris@0:    * handler
Chris@0:    * for class instantiation.
Chris@0:    *
Chris@0:    * If a module registers a scheme that is already registered with PHP, the
Chris@0:    * existing scheme will be unregistered and replaced with the specified
Chris@0:    * class.
Chris@0:    *
Chris@0:    * A stream is referenced as "scheme://target".
Chris@0:    *
Chris@0:    * The optional $filter parameter can be used to retrieve only the stream
Chris@0:    * wrappers that are appropriate for particular usage. For example, this
Chris@0:    * returns only stream wrappers that use local file storage:
Chris@0:    *
Chris@0:    * @code
Chris@0:    *   $stream_wrapper_manager = \Drupal::service('stream_wrapper_manager');
Chris@0:    *   $local_stream_wrappers = $stream_wrapper_manager->getWrappers(StreamWrapperInterface::LOCAL);
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * The $filter parameter can only filter to types containing a particular
Chris@0:    * flag. In some cases, you may want to filter to types that do not contain a
Chris@0:    * particular flag. For example, you may want to retrieve all stream wrappers
Chris@0:    * that are not writable, or all stream wrappers that are not local. PHP's
Chris@0:    * array_diff_key() function can be used to help with this. For example, this
Chris@0:    * returns only stream wrappers that do not use local file storage:
Chris@0:    * @code
Chris@0:    *   $stream_wrapper_manager = \Drupal::service('stream_wrapper_manager');
Chris@0:    *   $remote_stream_wrappers = array_diff_key(
Chris@0:    *     $stream_wrapper_manager->getWrappers(StreamWrapperInterface::ALL),
Chris@0:    *     $stream_wrapper_manager->getWrappers(StreamWrapperInterface::LOCAL)
Chris@0:    *   );
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * @param int $filter
Chris@0:    *   (Optional) Filters out all types except those with an on bit for each on
Chris@0:    *   bit in $filter. For example, if $filter is
Chris@0:    *   StreamWrapperInterface::WRITE_VISIBLE, which is equal to
Chris@0:    *   (StreamWrapperInterface::READ | StreamWrapperInterface::WRITE |
Chris@0:    *   StreamWrapperInterface::VISIBLE), then only stream wrappers with all
Chris@0:    *   three of these bits set are returned. Defaults to
Chris@0:    *   StreamWrapperInterface::ALL, which returns all registered stream
Chris@0:    *   wrappers.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array keyed by scheme, with values containing an array of information
Chris@0:    *   about the stream wrapper, as returned by hook_stream_wrappers(). If
Chris@0:    *   $filter is omitted or set to StreamWrapperInterface::ALL, the entire
Chris@0:    *   Drupal stream wrapper registry is returned. Otherwise only the stream
Chris@0:    *   wrappers whose 'type' bitmask has an on bit for each bit specified in
Chris@0:    *   $filter are returned.
Chris@0:    */
Chris@0:   public function getWrappers($filter = StreamWrapperInterface::ALL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns registered stream wrapper names.
Chris@0:    *
Chris@0:    * @param int $filter
Chris@0:    *   (Optional) Filters out all types except those with an on bit for each on
Chris@0:    *   bit in $filter. For example, if $filter is
Chris@0:    *   StreamWrapperInterface::WRITE_VISIBLE, which is equal to
Chris@0:    *   (StreamWrapperInterface::READ | StreamWrapperInterface::WRITE |
Chris@0:    *   StreamWrapperInterface::VISIBLE), then only stream wrappers with all
Chris@0:    *   three of these bits set are returned. Defaults to
Chris@0:    *   StreamWrapperInterface::ALL, which returns all registered stream
Chris@0:    *   wrappers.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   Stream wrapper names, keyed by scheme.
Chris@0:    */
Chris@0:   public function getNames($filter = StreamWrapperInterface::ALL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns registered stream wrapper descriptions.
Chris@0:    *
Chris@0:    * @param int $filter
Chris@0:    *   (Optional) Filters out all types except those with an on bit for each on
Chris@0:    *   bit in $filter. For example, if $filter is
Chris@0:    *   StreamWrapperInterface::WRITE_VISIBLE, which is equal to
Chris@0:    *   (StreamWrapperInterface::READ | StreamWrapperInterface::WRITE |
Chris@0:    *   StreamWrapperInterface::VISIBLE), then only stream wrappers with all
Chris@0:    *   three of these bits set are returned. Defaults to
Chris@0:    *   StreamWrapperInterface::ALL, which returns all registered stream
Chris@0:    *   wrappers.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   Stream wrapper descriptions, keyed by scheme.
Chris@0:    */
Chris@0:   public function getDescriptions($filter = StreamWrapperInterface::ALL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a reference to the stream wrapper class responsible for a scheme.
Chris@0:    *
Chris@0:    * This helper method returns a stream instance using a scheme. That is, the
Chris@0:    * passed string does not contain a "://". For example, "public" is a scheme
Chris@0:    * but "public://" is a URI (stream). This is because the later contains both
Chris@0:    * a scheme and target despite target being empty.
Chris@0:    *
Chris@0:    * Note: the instance URI will be initialized to "scheme://" so that you can
Chris@0:    * make the customary method calls as if you had retrieved an instance by URI.
Chris@0:    *
Chris@0:    * @param string $scheme
Chris@0:    *   If the stream was "public://target", "public" would be the scheme.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\StreamWrapper\StreamWrapperInterface|bool
Chris@0:    *   Returns a new stream wrapper object appropriate for the given $scheme.
Chris@0:    *   For example, for the public scheme a stream wrapper object
Chris@0:    *   (Drupal\Core\StreamWrapper\PublicStream).
Chris@0:    *   FALSE is returned if no registered handler could be found.
Chris@0:    */
Chris@0:   public function getViaScheme($scheme);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a reference to the stream wrapper class responsible for a URI.
Chris@0:    *
Chris@0:    * The scheme determines the stream wrapper class that should be
Chris@0:    * used by consulting the stream wrapper registry.
Chris@0:    *
Chris@0:    * @param string $uri
Chris@0:    *   A stream, referenced as "scheme://target".
Chris@0:    *
Chris@0:    * @return \Drupal\Core\StreamWrapper\StreamWrapperInterface|bool
Chris@0:    *   Returns a new stream wrapper object appropriate for the given URI or
Chris@0:    *   FALSE if no registered handler could be found. For example, a URI of
Chris@0:    *   "private://example.txt" would return a new private stream wrapper object
Chris@0:    *   (Drupal\Core\StreamWrapper\PrivateStream).
Chris@0:    */
Chris@0:   public function getViaUri($uri);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the stream wrapper class name for a given scheme.
Chris@0:    *
Chris@0:    * @param string $scheme
Chris@0:    *   Stream scheme.
Chris@0:    *
Chris@0:    * @return string|bool
Chris@0:    *   Return string if a scheme has a registered handler, or FALSE.
Chris@0:    */
Chris@0:   public function getClass($scheme);
Chris@0: 
Chris@0:   /**
Chris@0:    * Registers stream wrapper with PHP.
Chris@0:    *
Chris@0:    * @param string $scheme
Chris@0:    *   The scheme of the stream wrapper.
Chris@0:    * @param string $class
Chris@0:    *   The class of the stream wrapper.
Chris@0:    * @param int $type
Chris@0:    *   The type of the stream wrapper.
Chris@0:    */
Chris@0:   public function registerWrapper($scheme, $class, $type);
Chris@0: 
Chris@0: }