File adapter interface

CHANGELOG.md

@@ -7,7 +7,7 @@ Updates should follow the [Keep a Changelog](http://keepachangelog.com/) princip
 ## Unreleased - YYYY-MM-DD
 
 ### Added
-- Nothing
+- File adapter interface.
 
 ### Deprecated
 - Nothing

composer.json

@@ -22,7 +22,9 @@
         }
     ],
     "require": {
-        "php": ">=7.4"
+        "php": ">=7.4",
+        "psr/http-message": "^1.0.1",
+        "stadly/http": "^1.0"
     },
     "require-dev": {
         "pepakriz/phpstan-exception-rules": "^0.11.7",

src/Adapter.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stadly\FileWaiter;
+
+use Psr\Http\Message\StreamInterface;
+use Stadly\FileWaiter\Exception\StreamCouldNotBeOpened;
+use Stadly\Http\Header\Value\Date;
+use Stadly\Http\Header\Value\EntityTag\EntityTag;
+use Stadly\Http\Header\Value\MediaType\MediaType;
+
+/**
+ * Interface for file adapters.
+ */
+interface Adapter
+{
+    /**
+     * @return StreamInterface File stream that can be used to read from the file.
+     * @throws StreamCouldNotBeOpened If the file stream could not be opened.
+     */
+    public function getFileStream(): StreamInterface;
+
+    /**
+     * @return string|null File name, or null if not known.
+     */
+    public function getFileName(): ?string;
+
+    /**
+     * @return int|null File size, or null if not known.
+     */
+    public function getFileSize(): ?int;
+
+    /**
+     * @return MediaType|null Media type of the file, or null if not known.
+     */
+    public function getMediaType(): ?MediaType;
+
+    /**
+     * @return Date|null Date when the file was last modified, or null if not known.
+     */
+    public function getLastModifiedDate(): ?Date;
+
+    /**
+     * @return EntityTag|null Entity tag for the file, or null if not known.
+     */
+    public function getEntityTag(): ?EntityTag;
+}

src/Exception/StreamCouldNotBeOpened.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stadly\FileWaiter\Exception;
+
+use RuntimeException;
+use Throwable;
+
+/**
+ * Exception thrown when a file stream could not be opened.
+ */
+final class StreamCouldNotBeOpened extends RuntimeException
+{
+    /**
+     * @var string Path to file.
+     */
+    private $filePath;
+
+    /**
+     * Constructor.
+     *
+     * @param string $filePath Path to file.
+     * @param Throwable $previous Previous exception, used for exception chaining.
+     */
+    public function __construct(string $filePath, ?Throwable $previous = null)
+    {
+        $this->filePath = $filePath;
+
+        parent::__construct('File stream could not be opened: ' . $filePath, /*code*/0, $previous);
+    }
+
+    /**
+     * @return string Path to file.
+     */
+    public function getFilePath(): string
+    {
+        return $this->filePath;
+    }
+}

tests/Exception/StreamCouldNotBeOpenedTest.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stadly\FileWaiter\Exception;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @coversDefaultClass \Stadly\FileWaiter\Exception\StreamCouldNotBeOpened
+ * @covers ::<protected>
+ * @covers ::<private>
+ */
+final class StreamCouldNotBeOpenedTest extends TestCase
+{
+    /**
+     * @covers ::__construct
+     */
+    public function testCanConstructException(): void
+    {
+        $exception = new StreamCouldNotBeOpened('foo/bar.baz');
+
+        // Force generation of code coverage
+        $exceptionConstruct = new StreamCouldNotBeOpened('foo/bar.baz');
+        self::assertEquals($exception, $exceptionConstruct);
+    }
+
+    /**
+     * @covers ::getFilePath
+     */
+    public function testCanGetFilePath(): void
+    {
+        $exception = new StreamCouldNotBeOpened('foo/bar.baz');
+
+        self::assertSame('foo/bar.baz', $exception->getFilePath());
+    }
+}