[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  namespace WordPress\AiClientDependencies\Psr\Http\Message;
   4  
   5  /**
   6   * Describes a data stream.
   7   *
   8   * Typically, an instance will wrap a PHP stream; this interface provides
   9   * a wrapper around the most common operations, including serialization of
  10   * the entire stream to a string.
  11   */
  12  interface StreamInterface
  13  {
  14      /**
  15       * Reads all data from the stream into a string, from the beginning to end.
  16       *
  17       * This method MUST attempt to seek to the beginning of the stream before
  18       * reading data and read the stream until the end is reached.
  19       *
  20       * Warning: This could attempt to load a large amount of data into memory.
  21       *
  22       * This method MUST NOT raise an exception in order to conform with PHP's
  23       * string casting operations.
  24       *
  25       * @see http://php.net/manual/en/language.oop5.magic.php#object.tostring
  26       * @return string
  27       */
  28      public function __toString(): string;
  29      /**
  30       * Closes the stream and any underlying resources.
  31       *
  32       * @return void
  33       */
  34      public function close(): void;
  35      /**
  36       * Separates any underlying resources from the stream.
  37       *
  38       * After the stream has been detached, the stream is in an unusable state.
  39       *
  40       * @return resource|null Underlying PHP stream, if any
  41       */
  42      public function detach();
  43      /**
  44       * Get the size of the stream if known.
  45       *
  46       * @return int|null Returns the size in bytes if known, or null if unknown.
  47       */
  48      public function getSize(): ?int;
  49      /**
  50       * Returns the current position of the file read/write pointer
  51       *
  52       * @return int Position of the file pointer
  53       * @throws \RuntimeException on error.
  54       */
  55      public function tell(): int;
  56      /**
  57       * Returns true if the stream is at the end of the stream.
  58       *
  59       * @return bool
  60       */
  61      public function eof(): bool;
  62      /**
  63       * Returns whether or not the stream is seekable.
  64       *
  65       * @return bool
  66       */
  67      public function isSeekable(): bool;
  68      /**
  69       * Seek to a position in the stream.
  70       *
  71       * @link http://www.php.net/manual/en/function.fseek.php
  72       * @param int $offset Stream offset
  73       * @param int $whence Specifies how the cursor position will be calculated
  74       *     based on the seek offset. Valid values are identical to the built-in
  75       *     PHP $whence values for `fseek()`.  SEEK_SET: Set position equal to
  76       *     offset bytes SEEK_CUR: Set position to current location plus offset
  77       *     SEEK_END: Set position to end-of-stream plus offset.
  78       * @throws \RuntimeException on failure.
  79       */
  80      public function seek(int $offset, int $whence = \SEEK_SET): void;
  81      /**
  82       * Seek to the beginning of the stream.
  83       *
  84       * If the stream is not seekable, this method will raise an exception;
  85       * otherwise, it will perform a seek(0).
  86       *
  87       * @see seek()
  88       * @link http://www.php.net/manual/en/function.fseek.php
  89       * @throws \RuntimeException on failure.
  90       */
  91      public function rewind(): void;
  92      /**
  93       * Returns whether or not the stream is writable.
  94       *
  95       * @return bool
  96       */
  97      public function isWritable(): bool;
  98      /**
  99       * Write data to the stream.
 100       *
 101       * @param string $string The string that is to be written.
 102       * @return int Returns the number of bytes written to the stream.
 103       * @throws \RuntimeException on failure.
 104       */
 105      public function write(string $string): int;
 106      /**
 107       * Returns whether or not the stream is readable.
 108       *
 109       * @return bool
 110       */
 111      public function isReadable(): bool;
 112      /**
 113       * Read data from the stream.
 114       *
 115       * @param int $length Read up to $length bytes from the object and return
 116       *     them. Fewer than $length bytes may be returned if underlying stream
 117       *     call returns fewer bytes.
 118       * @return string Returns the data read from the stream, or an empty string
 119       *     if no bytes are available.
 120       * @throws \RuntimeException if an error occurs.
 121       */
 122      public function read(int $length): string;
 123      /**
 124       * Returns the remaining contents in a string
 125       *
 126       * @return string
 127       * @throws \RuntimeException if unable to read or an error occurs while
 128       *     reading.
 129       */
 130      public function getContents(): string;
 131      /**
 132       * Get stream metadata as an associative array or retrieve a specific key.
 133       *
 134       * The keys returned are identical to the keys returned from PHP's
 135       * stream_get_meta_data() function.
 136       *
 137       * @link http://php.net/manual/en/function.stream-get-meta-data.php
 138       * @param string|null $key Specific metadata to retrieve.
 139       * @return array|mixed|null Returns an associative array if no key is
 140       *     provided. Returns a specific key value if a key is provided and the
 141       *     value is found, or null if the key is not found.
 142       */
 143      public function getMetadata(?string $key = null);
 144  }