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

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
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 * 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 }