www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/StreamWrapper/StreamWrapperInterface.php

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