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 }
|