$streams
$streams : \Psr\Http\Message\StreamInterface[]
Reads from multiple streams, one after the other.
This is a read-only stream decorator.
$streams : \Psr\Http\Message\StreamInterface[]
__toString() : string
Reads all data from the stream into a string, from the beginning to end.
This method MUST attempt to seek to the beginning of the stream before reading data and read the stream until the end is reached.
Warning: This could attempt to load a large amount of data into memory.
This method MUST NOT raise an exception in order to conform with PHP's string casting operations.
getSize() : int|null
Tries to calculate the size by adding the size of each stream.
If any of the streams do not return a valid number, then the size of the append stream cannot be determined and null is returned.
{@inheritdoc}
Returns the size in bytes if known, or null if unknown.
seek(mixed $offset, mixed $whence = SEEK_SET) : mixed
Attempts to seek to the given position. Only supports SEEK_SET.
{@inheritdoc}
| mixed | $offset | Stream offset |
| mixed | $whence | 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 |
read(mixed $length) : string
Reads from all of the appended streams until the length is met or EOF.
{@inheritdoc}
| mixed | $length | Read up to $length bytes from the object and return them. Fewer than $length bytes may be returned if underlying stream call returns fewer bytes. |
Returns the data read from the stream, or an empty string if no bytes are available.
getMetadata(mixed $key = null) : array|mixed|null
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.
| mixed | $key | Specific metadata to retrieve. |
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.
<?php
namespace GuzzleHttp\Psr7;
use Psr\Http\Message\StreamInterface;
/**
* Reads from multiple streams, one after the other.
*
* This is a read-only stream decorator.
*
* @final
*/
class AppendStream implements StreamInterface
{
/** @var StreamInterface[] Streams being decorated */
private $streams = [];
private $seekable = true;
private $current = 0;
private $pos = 0;
/**
* @param StreamInterface[] $streams Streams to decorate. Each stream must
* be readable.
*/
public function __construct(array $streams = [])
{
foreach ($streams as $stream) {
$this->addStream($stream);
}
}
public function __toString()
{
try {
$this->rewind();
return $this->getContents();
} catch (\Exception $e) {
return '';
}
}
/**
* Add a stream to the AppendStream
*
* @param StreamInterface $stream Stream to append. Must be readable.
*
* @throws \InvalidArgumentException if the stream is not readable
*/
public function addStream(StreamInterface $stream)
{
if (!$stream->isReadable()) {
throw new \InvalidArgumentException('Each stream must be readable');
}
// The stream is only seekable if all streams are seekable
if (!$stream->isSeekable()) {
$this->seekable = false;
}
$this->streams[] = $stream;
}
public function getContents()
{
return Utils::copyToString($this);
}
/**
* Closes each attached stream.
*
* {@inheritdoc}
*/
public function close()
{
$this->pos = $this->current = 0;
$this->seekable = true;
foreach ($this->streams as $stream) {
$stream->close();
}
$this->streams = [];
}
/**
* Detaches each attached stream.
*
* Returns null as it's not clear which underlying stream resource to return.
*
* {@inheritdoc}
*/
public function detach()
{
$this->pos = $this->current = 0;
$this->seekable = true;
foreach ($this->streams as $stream) {
$stream->detach();
}
$this->streams = [];
return null;
}
public function tell()
{
return $this->pos;
}
/**
* Tries to calculate the size by adding the size of each stream.
*
* If any of the streams do not return a valid number, then the size of the
* append stream cannot be determined and null is returned.
*
* {@inheritdoc}
*/
public function getSize()
{
$size = 0;
foreach ($this->streams as $stream) {
$s = $stream->getSize();
if ($s === null) {
return null;
}
$size += $s;
}
return $size;
}
public function eof()
{
return !$this->streams ||
($this->current >= count($this->streams) - 1 &&
$this->streams[$this->current]->eof());
}
public function rewind()
{
$this->seek(0);
}
/**
* Attempts to seek to the given position. Only supports SEEK_SET.
*
* {@inheritdoc}
*/
public function seek($offset, $whence = SEEK_SET)
{
if (!$this->seekable) {
throw new \RuntimeException('This AppendStream is not seekable');
} elseif ($whence !== SEEK_SET) {
throw new \RuntimeException('The AppendStream can only seek with SEEK_SET');
}
$this->pos = $this->current = 0;
// Rewind each stream
foreach ($this->streams as $i => $stream) {
try {
$stream->rewind();
} catch (\Exception $e) {
throw new \RuntimeException('Unable to seek stream '
. $i . ' of the AppendStream', 0, $e);
}
}
// Seek to the actual position by reading from each stream
while ($this->pos < $offset && !$this->eof()) {
$result = $this->read(min(8096, $offset - $this->pos));
if ($result === '') {
break;
}
}
}
/**
* Reads from all of the appended streams until the length is met or EOF.
*
* {@inheritdoc}
*/
public function read($length)
{
$buffer = '';
$total = count($this->streams) - 1;
$remaining = $length;
$progressToNext = false;
while ($remaining > 0) {
// Progress to the next stream if needed.
if ($progressToNext || $this->streams[$this->current]->eof()) {
$progressToNext = false;
if ($this->current === $total) {
break;
}
$this->current++;
}
$result = $this->streams[$this->current]->read($remaining);
// Using a loose comparison here to match on '', false, and null
if ($result == null) {
$progressToNext = true;
continue;
}
$buffer .= $result;
$remaining = $length - strlen($buffer);
}
$this->pos += strlen($buffer);
return $buffer;
}
public function isReadable()
{
return true;
}
public function isWritable()
{
return false;
}
public function isSeekable()
{
return $this->seekable;
}
public function write($string)
{
throw new \RuntimeException('Cannot write to an AppendStream');
}
public function getMetadata($key = null)
{
return $key ? null : [];
}
}