[Summary view] [Print] [Text view]

   1  <?php
   2  namespace GuzzleHttp\Stream;
   3  
   4  /**
   5   * Describes a stream instance.
   6   */
   7  interface StreamInterface
   8  {
   9      /**
  10       * Attempts to seek to the beginning of the stream and reads all data into
  11       * a string until the end of the stream is reached.
  12       *
  13       * Warning: This could attempt to load a large amount of data into memory.
  14       *
  15       * @return string
  16       */
  17      public function __toString();
  18  
  19      /**
  20       * Closes the stream and any underlying resources.
  21       */
  22      public function close();
  23  
  24      /**
  25       * Separates any underlying resources from the stream.
  26       *
  27       * After the underlying resource has been detached, the stream object is in
  28       * an unusable state. If you wish to use a Stream object as a PHP stream
  29       * but keep the Stream object in a consistent state, use
  30       * {@see GuzzleHttp\Stream\GuzzleStreamWrapper::getResource}.
  31       *
  32       * @return resource|null Returns the underlying PHP stream resource or null
  33       *                       if the Stream object did not utilize an underlying
  34       *                       stream resource.
  35       */
  36      public function detach();
  37  
  38      /**
  39       * Replaces the underlying stream resource with the provided stream.
  40       *
  41       * Use this method to replace the underlying stream with another; as an
  42       * example, in server-side code, if you decide to return a file, you
  43       * would replace the original content-oriented stream with the file
  44       * stream.
  45       *
  46       * Any internal state such as caching of cursor position should be reset
  47       * when attach() is called, as the stream has changed.
  48       *
  49       * @param resource $stream
  50       *
  51       * @return void
  52       */
  53      public function attach($stream);
  54  
  55      /**
  56       * Get the size of the stream if known
  57       *
  58       * @return int|null Returns the size in bytes if known, or null if unknown
  59       */
  60      public function getSize();
  61  
  62      /**
  63       * Returns the current position of the file read/write pointer
  64       *
  65       * @return int|bool Returns the position of the file pointer or false on error
  66       */
  67      public function tell();
  68  
  69      /**
  70       * Returns true if the stream is at the end of the stream.
  71       *
  72       * @return bool
  73       */
  74      public function eof();
  75  
  76      /**
  77       * Returns whether or not the stream is seekable
  78       *
  79       * @return bool
  80       */
  81      public function isSeekable();
  82  
  83      /**
  84       * Seek to a position in the stream
  85       *
  86       * @param int $offset Stream offset
  87       * @param int $whence Specifies how the cursor position will be calculated
  88       *                    based on the seek offset. Valid values are identical
  89       *                    to the built-in PHP $whence values for `fseek()`.
  90       *                    SEEK_SET: Set position equal to offset bytes
  91       *                    SEEK_CUR: Set position to current location plus offset
  92       *                    SEEK_END: Set position to end-of-stream plus offset
  93       *
  94       * @return bool Returns true on success or false on failure
  95       * @link   http://www.php.net/manual/en/function.fseek.php
  96       */
  97      public function seek($offset, $whence = SEEK_SET);
  98  
  99      /**
 100       * Returns whether or not the stream is writable
 101       *
 102       * @return bool
 103       */
 104      public function isWritable();
 105  
 106      /**
 107       * Write data to the stream
 108       *
 109       * @param string $string The string that is to be written.
 110       *
 111       * @return int|bool Returns the number of bytes written to the stream on
 112       *                  success returns false on failure (e.g., broken pipe,
 113       *                  writer needs to slow down, buffer is full, etc.)
 114       */
 115      public function write($string);
 116  
 117      /**
 118       * Returns whether or not the stream is readable
 119       *
 120       * @return bool
 121       */
 122      public function isReadable();
 123  
 124      /**
 125       * Read data from the stream
 126       *
 127       * @param int $length Read up to $length bytes from the object and return
 128       *                    them. Fewer than $length bytes may be returned if
 129       *                    underlying stream call returns fewer bytes.
 130       *
 131       * @return string     Returns the data read from the stream.
 132       */
 133      public function read($length);
 134  
 135      /**
 136       * Returns the remaining contents of the stream as a string.
 137       *
 138       * Note: this could potentially load a large amount of data into memory.
 139       *
 140       * @return string
 141       */
 142      public function getContents();
 143  
 144      /**
 145       * Get stream metadata as an associative array or retrieve a specific key.
 146       *
 147       * The keys returned are identical to the keys returned from PHP's
 148       * stream_get_meta_data() function.
 149       *
 150       * @param string $key Specific metadata to retrieve.
 151       *
 152       * @return array|mixed|null Returns an associative array if no key is
 153       *                          no key is provided. Returns a specific key
 154       *                          value if a key is provided and the value is
 155       *                          found, or null if the key is not found.
 156       * @see http://php.net/manual/en/function.stream-get-meta-data.php
 157       */
 158      public function getMetadata($key = null);
 159  }