Stream.php

Go to the documentation of this file.

<?php

declare(strict_types=1);

namespace ILIAS\Filesystem\Stream;

use ILIAS\Filesystem\Util\PHPStreamFunctions;

/******************************************************************************
 *
 * This file is part of ILIAS, a powerful learning management system.
 *
 * ILIAS is licensed with the GPL-3.0, you should have received a copy
 * of said license along with the source code.
 *
 * If this is not the case or you just want to try ILIAS, you'll find
 * us at:
 *      https://www.ilias.de
 *      https://github.com/ILIAS-eLearning
 *
 *****************************************************************************/
class Stream implements FileStream
{
    public const MASK_ACCESS_READ = 01;
    public const MASK_ACCESS_WRITE = 02;
    public const MASK_ACCESS_READ_WRITE = 03;

    private static array $accessMap = [
        'r' => self::MASK_ACCESS_READ,
        'w+' => self::MASK_ACCESS_READ_WRITE,
        'r+' => self::MASK_ACCESS_READ_WRITE,
        'x+' => self::MASK_ACCESS_READ_WRITE,
        'c+' => self::MASK_ACCESS_READ_WRITE,
        'rb' => self::MASK_ACCESS_READ,
        'w+b' => self::MASK_ACCESS_READ_WRITE,
        'r+b' => self::MASK_ACCESS_READ_WRITE,
        'x+b' => self::MASK_ACCESS_READ_WRITE,
        'c+b' => self::MASK_ACCESS_READ_WRITE,
        'rt' => self::MASK_ACCESS_READ,
        'w+t' => self::MASK_ACCESS_READ_WRITE,
        'r+t' => self::MASK_ACCESS_READ_WRITE,
        'x+t' => self::MASK_ACCESS_READ_WRITE,
        'c+t' => self::MASK_ACCESS_READ_WRITE,
        'a+' => self::MASK_ACCESS_READ_WRITE,
        'w' => self::MASK_ACCESS_WRITE,
        'rw' => self::MASK_ACCESS_WRITE,
        'wb' => self::MASK_ACCESS_WRITE,
        'a' => self::MASK_ACCESS_WRITE
    ];

    private bool $readable;
    private bool $writeable;
    private bool $seekable;
    private $stream;
    private ?int $size = null;
    private ?string $uri = null;
    private array $customMetadata;


    public function __construct($stream, StreamOptions $options = null)
    {
        if (!is_resource($stream)) {
            throw new \InvalidArgumentException('Stream must be a valid resource but "' . gettype($stream) . '" was given.');
        }

        if ($options !== null) {
            $this->customMetadata = $options->getMetadata();
            $this->size = ($options->getSize() !== -1) ? $options->getSize() : null;
        } else {
            $this->customMetadata = [];
        }

        $this->stream = $stream;

        $meta = stream_get_meta_data($this->stream);
        $mode = $meta['mode'];

        $this->readable = array_key_exists($mode, self::$accessMap) && boolval(self::$accessMap[$mode] & self::MASK_ACCESS_READ);
        $this->writeable = array_key_exists($mode, self::$accessMap) && boolval(self::$accessMap[$mode] & self::MASK_ACCESS_WRITE);
        $this->seekable = boolval($meta['seekable']);
        $this->uri = $this->getMetadata('uri');
    }


    public function close(): void
    {
        if (is_resource($this->stream)) {
            PHPStreamFunctions::fclose($this->stream);
        }

        $this->detach();
    }


    public function detach()
    {
        $stream = $this->stream;
        $this->stream = $this->size = $this->uri = null;

        return $stream;
    }


    public function getSize(): ?int
    {
        //check if we know the size
        if ($this->size !== null) {
            return $this->size;
        }

        //check if stream is detached
        if ($this->stream === null) {
            return null;
        }

        //clear stat cache if we got a uri (indicates that we have a file resource)
        if ($this->uri !== null) {
            clearstatcache(true, $this->uri);
        }

        $stats = fstat($this->stream);
        if (array_key_exists('size', $stats)) {
            $this->size = $stats['size'];
            return $this->size;
        }

        //unable to determine stream size
        return null;
    }


    public function tell()
    {
        $this->assertStreamAttached();

        $result = PHPStreamFunctions::ftell($this->stream);

        if ($result === false) {
            throw new \RuntimeException('Unable to determine stream position');
        }

        return $result;
    }


    public function eof(): bool
    {
        $this->assertStreamAttached();

        return feof($this->stream);
    }


    public function isSeekable(): bool
    {
        return $this->seekable;
    }


    public function seek($offset, $whence = SEEK_SET): void
    {
        $this->assertStreamAttached();

        if (!$this->isSeekable()) {
            throw new \RuntimeException('Stream is not seekable');
        }

        if (PHPStreamFunctions::fseek($this->stream, $offset, $whence) === -1) {
            throw new \RuntimeException("Unable to seek to stream position \"$offset\" with whence \"$whence\"");
        }
    }


    public function rewind(): void
    {
        $this->seek(0);
    }


    public function isWritable(): bool
    {
        return $this->writeable;
    }


    public function write($string)
    {
        $this->assertStreamAttached();

        if (!$this->isWritable()) {
            throw new \RuntimeException('Can not write to a non-writable stream');
        }

        //we can't know the new size
        $this->size = null;
        $result = PHPStreamFunctions::fwrite($this->stream, $string);

        if ($result === false) {
            throw new \RuntimeException('Unable to write to stream');
        }

        return $result;
    }


    public function isReadable(): bool
    {
        return $this->readable;
    }


    public function read($length)
    {
        $this->assertStreamAttached();

        if (!$this->isReadable()) {
            throw new \RuntimeException('Can not read from non-readable stream');
        }

        if ($length < 0) {
            throw new \RuntimeException('Length parameter must not be negative');
        }

        if ($length === 0) {
            return '';
        }

        $junk = PHPStreamFunctions::fread($this->stream, $length);
        if ($junk === false) {
            throw new \RuntimeException('Unable to read from stream');
        }

        return $junk;
    }


    public function getContents()
    {
        $this->assertStreamAttached();

        $content = PHPStreamFunctions::stream_get_contents($this->stream);

        if ($content === false) {
            throw new \RuntimeException('Unable to read stream contents');
        }

        return $content;
    }


    public function getMetadata($key = null)
    {

        //return empty array if stream is detached
        if ($this->stream === null) {
            return [];
        }

        //return merged metadata if key is missing
        if ($key === null) {
            return array_merge(stream_get_meta_data($this->stream), $this->customMetadata);
        }

        //return value if key was provided

        //try fetch data from custom metadata
        if (array_key_exists($key, $this->customMetadata)) {
            return $this->customMetadata[$key];
        }

        //try to fetch data from php resource metadata
        $meta = stream_get_meta_data($this->stream);
        if (array_key_exists($key, $meta)) {
            return $meta[$key];
        }

        //the key was not found in standard and custom metadata.
        return null;
    }

    public function __toString()
    {
        try {
            $this->rewind();
            return strval($this->getContents());
        } catch (\Exception $ex) {
            //to string must not throw an error.
            return '';
        }
    }


    public function __destruct()
    {

        //cleanup the resource on object destruction if the stream is not detached.
        if (!is_null($this->stream)) {
            $this->close();
        }
    }


    private function assertStreamAttached(): void
    {
        if ($this->stream === null) {
            throw new \RuntimeException('Stream is detached');
        }
    }
}