Chris@0
|
1 <?php
|
Chris@0
|
2
|
Chris@0
|
3 namespace Drupal\Core\StreamWrapper;
|
Chris@0
|
4
|
Chris@0
|
5 /**
|
Chris@0
|
6 * Defines a Drupal stream wrapper extension.
|
Chris@0
|
7 *
|
Chris@0
|
8 * Provides a Drupal interface and classes to implement PHP stream wrappers for
|
Chris@17
|
9 * public, private, and temporary files. Extends the PhpStreamWrapperInterface
|
Chris@0
|
10 * with methods expected by Drupal stream wrapper classes.
|
Chris@0
|
11 *
|
Chris@0
|
12 * A stream wrapper is an abstraction of a file system that allows Drupal to
|
Chris@0
|
13 * use the same set of methods to access both local files and remote resources.
|
Chris@0
|
14 *
|
Chris@0
|
15 * Note that PHP 5.2 fopen() only supports URIs of the form "scheme://target"
|
Chris@0
|
16 * despite the fact that according to RFC 3986 a URI's scheme component
|
Chris@0
|
17 * delimiter is in general just ":", not "://". Because of this PHP limitation
|
Chris@0
|
18 * and for consistency Drupal will only accept URIs of form "scheme://target".
|
Chris@0
|
19 *
|
Chris@0
|
20 * @see http://www.faqs.org/rfcs/rfc3986.html
|
Chris@0
|
21 * @see http://bugs.php.net/bug.php?id=47070
|
Chris@0
|
22 */
|
Chris@0
|
23 interface StreamWrapperInterface extends PhpStreamWrapperInterface {
|
Chris@0
|
24
|
Chris@0
|
25 /**
|
Chris@0
|
26 * Stream wrapper bit flags that are the basis for composite types.
|
Chris@0
|
27 *
|
Chris@0
|
28 * Note that 0x0002 is skipped, because it was the value of a constant that
|
Chris@0
|
29 * has since been removed.
|
Chris@0
|
30 */
|
Chris@0
|
31
|
Chris@0
|
32 /**
|
Chris@0
|
33 * A filter that matches all wrappers.
|
Chris@0
|
34 */
|
Chris@0
|
35 const ALL = 0x0000;
|
Chris@0
|
36
|
Chris@0
|
37 /**
|
Chris@0
|
38 * Refers to a local file system location.
|
Chris@0
|
39 */
|
Chris@0
|
40 const LOCAL = 0x0001;
|
Chris@0
|
41
|
Chris@0
|
42 /**
|
Chris@0
|
43 * Wrapper is readable (almost always true).
|
Chris@0
|
44 */
|
Chris@0
|
45 const READ = 0x0004;
|
Chris@0
|
46
|
Chris@0
|
47 /**
|
Chris@0
|
48 * Wrapper is writeable.
|
Chris@0
|
49 */
|
Chris@0
|
50 const WRITE = 0x0008;
|
Chris@0
|
51
|
Chris@0
|
52 /**
|
Chris@0
|
53 * Exposed in the UI and potentially web accessible.
|
Chris@0
|
54 */
|
Chris@0
|
55 const VISIBLE = 0x0010;
|
Chris@0
|
56
|
Chris@0
|
57 /**
|
Chris@0
|
58 * Composite stream wrapper bit flags that are usually used as the types.
|
Chris@0
|
59 */
|
Chris@0
|
60
|
Chris@0
|
61 /**
|
Chris@0
|
62 * Defines the stream wrapper bit flag for a hidden file.
|
Chris@0
|
63 *
|
Chris@0
|
64 * This is not visible in the UI or accessible via web, but readable and
|
Chris@0
|
65 * writable; for instance, the temporary directory for file uploads.
|
Chris@0
|
66 */
|
Chris@0
|
67 const HIDDEN = 0x000C;
|
Chris@0
|
68
|
Chris@0
|
69 /**
|
Chris@0
|
70 * Hidden, readable and writeable using local files.
|
Chris@0
|
71 */
|
Chris@0
|
72 const LOCAL_HIDDEN = 0x000D;
|
Chris@0
|
73
|
Chris@0
|
74 /**
|
Chris@0
|
75 * Visible, readable and writeable.
|
Chris@0
|
76 */
|
Chris@0
|
77 const WRITE_VISIBLE = 0x001C;
|
Chris@0
|
78
|
Chris@0
|
79 /**
|
Chris@0
|
80 * Visible and read-only.
|
Chris@0
|
81 */
|
Chris@0
|
82 const READ_VISIBLE = 0x0014;
|
Chris@0
|
83
|
Chris@0
|
84 /**
|
Chris@17
|
85 * This is the default 'type' flag. This does not include
|
Chris@0
|
86 * StreamWrapperInterface::LOCAL, because PHP grants a greater trust level to
|
Chris@0
|
87 * local files (for example, they can be used in an "include" statement,
|
Chris@0
|
88 * regardless of the "allow_url_include" setting), so stream wrappers need to
|
Chris@0
|
89 * explicitly opt-in to this.
|
Chris@0
|
90 */
|
Chris@0
|
91 const NORMAL = 0x001C;
|
Chris@0
|
92
|
Chris@0
|
93 /**
|
Chris@0
|
94 * Visible, readable and writeable using local files.
|
Chris@0
|
95 */
|
Chris@0
|
96 const LOCAL_NORMAL = 0x001D;
|
Chris@0
|
97
|
Chris@0
|
98 /**
|
Chris@0
|
99 * Returns the type of stream wrapper.
|
Chris@0
|
100 *
|
Chris@0
|
101 * @return int
|
Chris@0
|
102 */
|
Chris@0
|
103 public static function getType();
|
Chris@0
|
104
|
Chris@0
|
105 /**
|
Chris@0
|
106 * Returns the name of the stream wrapper for use in the UI.
|
Chris@0
|
107 *
|
Chris@0
|
108 * @return string
|
Chris@0
|
109 * The stream wrapper name.
|
Chris@0
|
110 */
|
Chris@0
|
111 public function getName();
|
Chris@0
|
112
|
Chris@0
|
113 /**
|
Chris@0
|
114 * Returns the description of the stream wrapper for use in the UI.
|
Chris@0
|
115 *
|
Chris@0
|
116 * @return string
|
Chris@0
|
117 * The stream wrapper description.
|
Chris@0
|
118 */
|
Chris@0
|
119 public function getDescription();
|
Chris@0
|
120
|
Chris@0
|
121 /**
|
Chris@0
|
122 * Sets the absolute stream resource URI.
|
Chris@0
|
123 *
|
Chris@0
|
124 * This allows you to set the URI. Generally is only called by the factory
|
Chris@0
|
125 * method.
|
Chris@0
|
126 *
|
Chris@0
|
127 * @param string $uri
|
Chris@0
|
128 * A string containing the URI that should be used for this instance.
|
Chris@0
|
129 */
|
Chris@0
|
130 public function setUri($uri);
|
Chris@0
|
131
|
Chris@0
|
132 /**
|
Chris@0
|
133 * Returns the stream resource URI.
|
Chris@0
|
134 *
|
Chris@0
|
135 * @return string
|
Chris@0
|
136 * Returns the current URI of the instance.
|
Chris@0
|
137 */
|
Chris@0
|
138 public function getUri();
|
Chris@0
|
139
|
Chris@0
|
140 /**
|
Chris@0
|
141 * Returns a web accessible URL for the resource.
|
Chris@0
|
142 *
|
Chris@0
|
143 * This function should return a URL that can be embedded in a web page
|
Chris@0
|
144 * and accessed from a browser. For example, the external URL of
|
Chris@0
|
145 * "youtube://xIpLd0WQKCY" might be
|
Chris@0
|
146 * "http://www.youtube.com/watch?v=xIpLd0WQKCY".
|
Chris@0
|
147 *
|
Chris@0
|
148 * @return string
|
Chris@0
|
149 * Returns a string containing a web accessible URL for the resource.
|
Chris@0
|
150 */
|
Chris@0
|
151 public function getExternalUrl();
|
Chris@0
|
152
|
Chris@0
|
153 /**
|
Chris@0
|
154 * Returns canonical, absolute path of the resource.
|
Chris@0
|
155 *
|
Chris@0
|
156 * Implementation placeholder. PHP's realpath() does not support stream
|
Chris@0
|
157 * wrappers. We provide this as a default so that individual wrappers may
|
Chris@0
|
158 * implement their own solutions.
|
Chris@0
|
159 *
|
Chris@0
|
160 * @return string
|
Chris@0
|
161 * Returns a string with absolute pathname on success (implemented
|
Chris@0
|
162 * by core wrappers), or FALSE on failure or if the registered
|
Chris@0
|
163 * wrapper does not provide an implementation.
|
Chris@0
|
164 */
|
Chris@0
|
165 public function realpath();
|
Chris@0
|
166
|
Chris@0
|
167 /**
|
Chris@0
|
168 * Gets the name of the directory from a given path.
|
Chris@0
|
169 *
|
Chris@18
|
170 * This method is usually accessed through
|
Chris@18
|
171 * \Drupal\Core\File\FileSystemInterface::dirname(), which wraps around the
|
Chris@18
|
172 * normal PHP dirname() function, which does not support stream wrappers.
|
Chris@0
|
173 *
|
Chris@0
|
174 * @param string $uri
|
Chris@0
|
175 * An optional URI.
|
Chris@0
|
176 *
|
Chris@0
|
177 * @return string
|
Chris@0
|
178 * A string containing the directory name, or FALSE if not applicable.
|
Chris@0
|
179 *
|
Chris@18
|
180 * @see \Drupal\Core\File\FileSystemInterface::dirname()
|
Chris@0
|
181 */
|
Chris@0
|
182 public function dirname($uri = NULL);
|
Chris@0
|
183
|
Chris@0
|
184 }
|