Sync interfaces with recent changes in proposal

- [php-fig/fig-standards#330] Add attach to stream interface
- [php-fig/fig-standards#331] Clarify return value of stream interface detach()
  method
- [php-fig/fig-standards#332] Add getMetadata() to stream interface
- [php-fig/fig-standards#333] Remove $maxLength parameter from stream interface
  getContents() method
- [php-fig/fig-standards#334] Rename StreamInterface to StreamableInterface

Author: weierophinney

src/MessageInterface.php

@@ -20,23 +20,23 @@ public function getProtocolVersion();
     /**
      * Gets the body of the message.
      *
-     * @return StreamInterface|null Returns the body, or null if not set.
+     * @return StreamableInterface|null Returns the body, or null if not set.
      */
     public function getBody();
 
     /**
      * Sets the body of the message.
      *
-     * The body MUST be a StreamInterface object. Setting the body to null MUST
+     * The body MUST be a StreamableInterface object. Setting the body to null MUST
      * remove the existing body.
      *
-     * @param StreamInterface|null $body Body.
+     * @param StreamableInterface|null $body Body.
      *
      * @return void
      *
      * @throws \InvalidArgumentException When the body is not valid.
      */
-    public function setBody(StreamInterface $body = null);
+    public function setBody(StreamableInterface $body = null);
 
     /**
      * Gets all message headers.

src/StreamInterface.php renamed to src/StreamableInterface.php

@@ -5,7 +5,7 @@
 /**
  * Describes a stream instance.
  */
-interface StreamInterface
+interface StreamableInterface
 {
     /**
      * Reads all data from the stream into a string, from the beginning to end.
@@ -31,10 +31,25 @@ public function close();
      *
      * After the stream has been detached, the stream is in an unusable state.
      *
-     * @return void
+     * @return resource|null Underlying PHP stream, if any
      */
     public function detach();
 
+    /**
+     * Replaces the underlying stream resource with the provided stream.
+     *
+     * Use this method to replace the underlying stream with another; as an
+     * example, in server-side code, if you decide to return a file, you
+     * would replace the original content-oriented stream with the file
+     * stream.
+     *
+     * Any internal state such as caching of cursor position should be reset
+     * when attach() is called, as the stream has changed.
+     *
+     * @return void
+     */
+    public function attach($stream);
+
     /**
      * Get the size of the stream if known
      *
@@ -115,11 +130,25 @@ public function isReadable();
     public function read($length);
 
     /**
-     * Returns the remaining contents in a string, up to maxlength bytes.
+     * Returns the remaining contents in a string
      *
-     * @param int $maxLength The maximum bytes to read. Defaults to -1 (read
-     *                       all the remaining buffer).
      * @return string
      */
-    public function getContents($maxLength = -1);
+    public function getContents();
+
+    /**
+     * Get stream metadata as an associative array or retrieve a specific key.
+     *
+     * The keys returned are identical to the keys returned from PHP's
+     * stream_get_meta_data() function.
+     *
+     * @param string $key Specific metadata to retrieve.
+     *
+     * @return array|mixed|null Returns an associative array if no key is
+     *                          provided. Returns a specific key value if a key
+     *                          is provided and the value is found, or null if
+     *                          the key is not found.
+     * @see http://php.net/manual/en/function.stream-get-meta-data.php
+     */
+    public function getMetadata($key = null);
 }