HTTP Response (PSR-7)

PSR-7 HTTP Stream - 图1

Overview

Phalcon\Http\Message\Stream is an implementation of the PSR-7 HTTP messaging interface as defined by PHP-FIG.

PSR-7 HTTP Stream - 图2

This class describes a data stream. Typically, an instance will wrap a PHP stream; this interface provides a wrapper around the most common operations, including serialization of the entire stream to a string.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. echo $stream->getContents(); // 'The MIT License (MIT) ...'

Constructor

  1. public function __construct(
  2.     mixed $stream, 
  3.     string $mode = "rb"
  4. )

The first parameter can be a string representing the location of the file on the file system or storage area. It can also be a resource, as returned by a method such as fopen. The second parameter is the open mode for the stream. The default mode is rb. For a list of available modes, you can check the documentation for fopen.

  • stream - string or resource
  • mode - A string representing the mode the file is to be opened.If there is an error, a RuntimeException will be thrown.

Getters

__toString()

Reads all data from the stream into a string, from the beginning to end. The method will first try to seek() to the beginning of the stream before reading the data and read the stream until the end is reached.

NOTE Calling this method on large files will result in a large amount of data being loaded in memory{ .alert .alert-danger }

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. echo (string) $stream; // 'The MIT License (MIT) ...'

getContents()

Returns a string with the remaining contents in a string. If the stream cannot be read or an error occurs, a RuntimeException will be thrown.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. echo $stream->getContents(); // 'The MIT License (MIT) ...'

getMetadata()

Returns the stream metadata as an associative array. If the parameter $key is defined, the relevant string element will be returned. The method is a wrapper for PHP’s stream_get_meta_data() function. If the key is not found, the method will return null.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. var_dump(
  10.     $stream->getMetadata()
  11. );
  13. // [
  14. //     'timed_out'    => false,
  15. //     'blocked'      => true,
  16. //     'eof'          => false,
  17. //     'wrapper_type' => 'plainfile',
  18. //     'stream_type'  => 'STDIO',
  19. //     'mode'         => 'rb',
  20. //     'unread_bytes' => 0,
  21. //     'seekable'     => true,
  22. //     'uri'          => $fileName,
  23. // ];
  25. echo $stream->getMetadata('wrapper_type'); // 'plainfile'
  26. echo $stream->getMetadata('unknown');      // null

getSize()

Returns the size of the stream. If it is not known, null will be returned

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. echo $stream->getSize(); // 1087

Is

isSeekable()

Returns true if the stream is seekable, false otherwise.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. echo $stream->isSeekable(); // 'true'

isReadable()

Returns true if the stream is readable, false otherwise.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'w');
  9. echo $stream->isReadable(); // 'false'

isWritable()

Returns true if the stream is writable, false otherwise.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. echo $stream->isWritable(); // 'false'

close()

Closes the stream and any underlying resources.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. $stream->close();

detach()

Separates any underlying resources from the stream. After the stream has been detached, the stream is in an unusable state. Calling this method on a closed/detached stream will return null

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. echo $stream->detach(); // The handle
  10. echo $stream->detach(); // null

eof()

Returns true if the stream is at the end of the stream, false otherwise.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. echo $stream->eof(); // false
  11. $stream->seek(9999);
  13. echo $stream->eof(); // true

read()

Read data from the stream. The method accepts an integer specifying the number of bytes from the object and return them. The method could return less number of bytes than specified if the end of the stream is defined. If no more data is available an empty string will be returned. If an error occurs, a RuntimeException will be thrown.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. echo $stream->read(15); // 'The MIT License'

rewind()

Seek to the beginning of the stream. Uses fseek() calling seek(0) internally. If the stream is not seekable, a RuntimeException will be thrown.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. $stream->seek(8);
  10. echo $stream->read(7); // 'License'
  11. $stream->rewind();
  12. echo $stream->read(3); // 'The'

seek()

Seek to a position in the stream. Uses fseek() internally. It accepts:

  • offset - int The stream offset
  • whence - int Specifies how the cursor position will be calculated based on the seek offset. Valid values are identical to the built-in PHP $whence values for fseek().
    • SEEK_SET Set position equal to offset bytes
    • SEEK_CUR Set position to current location plus offset
    • SEEK_END Set position to end-of-stream plus offset.If an error occurs, a RuntimeException will be thrown.
  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. $stream->seek(8);
  10. echo $stream->read(7); // 'License'
  11. $stream->rewind();
  12. echo $stream->read(3); // 'The'

tell()

Returns the current position of the file read/write pointer as an integer. If an error occurs, a RuntimeException will be thrown.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $fileName = dataDir('assets/stream/mit.txt');
  7. $stream = new Stream($fileName, 'rb');
  9. $stream->seek(8);
  10. echo $stream->tell(); // 8

write()

Write data to the stream. It accepts a string parameter as the contents to be written. The method returns the number of bytes written to the stream as an integer. If an error occurs, a RuntimeException will be thrown.

  1. <?php
  3. use Phalcon\Http\Message\Stream;
  5. $stream = new Stream('php://memory', 'wb');
  6. $source = 'The above copyright notice and this permission '
  7.         . 'notice shall be included in all copies or '
  8.         . 'substantial portions of the Software.';
  10. echo $stream->write($source); // 126