annotate core/lib/Drupal/Core/StreamWrapper/StreamWrapperManagerInterface.php @ 19:fa3358dc1485 tip

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