From 4efd05cdf1e0a41989da8ece4957afeae859f626 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin?= <kevinar9@hotmail.fr>
Date: Mon, 30 Oct 2023 15:53:34 +0100
Subject: [PATCH] refacto: type filesystem and filesystem interface

---
 src/Gaufrette/Filesystem.php          | 61 +++++++++--------------
 src/Gaufrette/FilesystemInterface.php | 72 ++++++---------------------
 2 files changed, 38 insertions(+), 95 deletions(-)

diff --git a/src/Gaufrette/Filesystem.php b/src/Gaufrette/Filesystem.php
index e08d1921d..bd9157666 100644
--- a/src/Gaufrette/Filesystem.php
+++ b/src/Gaufrette/Filesystem.php
@@ -12,14 +12,14 @@
  */
 class Filesystem implements FilesystemInterface
 {
-    protected $adapter;
+    protected Adapter $adapter;
 
     /**
      * Contains File objects created with $this->createFile() method.
      *
      * @var array
      */
-    protected $fileRegister = [];
+    protected array $fileRegister = [];
 
     /**
      * @param Adapter $adapter A configured Adapter instance
@@ -29,12 +29,7 @@ public function __construct(Adapter $adapter)
         $this->adapter = $adapter;
     }
 
-    /**
-     * Returns the adapter.
-     *
-     * @return Adapter
-     */
-    public function getAdapter()
+    public function getAdapter(): Adapter
     {
         return $this->adapter;
     }
@@ -42,7 +37,7 @@ public function getAdapter()
     /**
      * {@inheritdoc}
      */
-    public function has($key)
+    public function has(string $key): bool
     {
         self::assertValidKey($key);
 
@@ -52,7 +47,7 @@ public function has($key)
     /**
      * {@inheritdoc}
      */
-    public function rename($sourceKey, $targetKey)
+    public function rename(string $sourceKey, string $targetKey): bool
     {
         self::assertValidKey($sourceKey);
         self::assertValidKey($targetKey);
@@ -78,7 +73,7 @@ public function rename($sourceKey, $targetKey)
     /**
      * {@inheritdoc}
      */
-    public function get($key, $create = false)
+    public function get(string $key, bool $create = false): File
     {
         self::assertValidKey($key);
 
@@ -92,7 +87,7 @@ public function get($key, $create = false)
     /**
      * {@inheritdoc}
      */
-    public function write($key, $content, $overwrite = false)
+    public function write(string $key, string $content, bool $overwrite = false): int
     {
         self::assertValidKey($key);
 
@@ -112,7 +107,7 @@ public function write($key, $content, $overwrite = false)
     /**
      * {@inheritdoc}
      */
-    public function read($key)
+    public function read(string $key): string
     {
         self::assertValidKey($key);
 
@@ -130,7 +125,7 @@ public function read($key)
     /**
      * {@inheritdoc}
      */
-    public function delete($key)
+    public function delete(string $key): bool
     {
         self::assertValidKey($key);
 
@@ -148,7 +143,7 @@ public function delete($key)
     /**
      * {@inheritdoc}
      */
-    public function keys()
+    public function keys(): array
     {
         return $this->adapter->keys();
     }
@@ -156,7 +151,7 @@ public function keys()
     /**
      * {@inheritdoc}
      */
-    public function listKeys($prefix = '')
+    public function listKeys(string $prefix = ''): array
     {
         if ($this->adapter instanceof ListKeysAware) {
             return $this->adapter->listKeys($prefix);
@@ -184,7 +179,7 @@ public function listKeys($prefix = '')
     /**
      * {@inheritdoc}
      */
-    public function mtime($key)
+    public function mtime(string $key): int|bool
     {
         self::assertValidKey($key);
 
@@ -196,7 +191,7 @@ public function mtime($key)
     /**
      * {@inheritdoc}
      */
-    public function checksum($key)
+    public function checksum(string $key): string
     {
         self::assertValidKey($key);
 
@@ -212,7 +207,7 @@ public function checksum($key)
     /**
      * {@inheritdoc}
      */
-    public function size($key)
+    public function size(string $key): int
     {
         self::assertValidKey($key);
 
@@ -228,7 +223,7 @@ public function size($key)
     /**
      * {@inheritdoc}
      */
-    public function createStream($key)
+    public function createStream(string $key): Stream|Stream\InMemoryBuffer
     {
         self::assertValidKey($key);
 
@@ -242,7 +237,7 @@ public function createStream($key)
     /**
      * {@inheritdoc}
      */
-    public function createFile($key)
+    public function createFile(string $key): File
     {
         self::assertValidKey($key);
 
@@ -260,7 +255,7 @@ public function createFile($key)
     /**
      * {@inheritdoc}
      */
-    public function mimeType($key)
+    public function mimeType(string $key): string|bool
     {
         self::assertValidKey($key);
 
@@ -282,11 +277,9 @@ public function mimeType($key)
      * Key must be non empty string, otherwise it will throw Exception\FileNotFound
      * {@see http://php.net/manual/en/function.empty.php}
      *
-     * @param string $key
-     *
      * @throws Exception\FileNotFound when sourceKey does not exist
      */
-    private function assertHasFile($key)
+    private function assertHasFile(string $key): void
     {
         if (!$this->has($key)) {
             throw new Exception\FileNotFound($key);
@@ -295,12 +288,8 @@ private function assertHasFile($key)
 
     /**
      * Checks if matching File object by given key exists in the fileRegister.
-     *
-     * @param string $key
-     *
-     * @return bool
      */
-    private function isFileInRegister($key)
+    private function isFileInRegister(string $key): bool
     {
         return array_key_exists($key, $this->fileRegister);
     }
@@ -308,17 +297,15 @@ private function isFileInRegister($key)
     /**
      * Clear files register.
      */
-    public function clearFileRegister()
+    public function clearFileRegister(): void
     {
         $this->fileRegister = [];
     }
 
     /**
      * Removes File object from register.
-     *
-     * @param string $key
      */
-    public function removeFromRegister($key)
+    public function removeFromRegister(string $key): void
     {
         if ($this->isFileInRegister($key)) {
             unset($this->fileRegister[$key]);
@@ -328,17 +315,15 @@ public function removeFromRegister($key)
     /**
      * {@inheritdoc}
      */
-    public function isDirectory($key)
+    public function isDirectory(string $key): bool
     {
         return $this->adapter->isDirectory($key);
     }
 
     /**
-     * @param string $key
-     *
      * @throws \InvalidArgumentException Given $key should not be empty
      */
-    private static function assertValidKey($key)
+    private static function assertValidKey(string $key): void
     {
         if (empty($key)) {
             throw new \InvalidArgumentException('Object path is empty.');
diff --git a/src/Gaufrette/FilesystemInterface.php b/src/Gaufrette/FilesystemInterface.php
index 57d16dd76..aacb265d0 100644
--- a/src/Gaufrette/FilesystemInterface.php
+++ b/src/Gaufrette/FilesystemInterface.php
@@ -7,22 +7,17 @@ interface FilesystemInterface
     /**
      * Indicates whether the file matching the specified key exists.
      *
-     * @param string $key
-     *
      * @return bool TRUE if the file exists, FALSE otherwise
      *
      * @throws \InvalidArgumentException If $key is invalid
      */
-    public function has($key);
+    public function has(string $key): bool;
 
     /**
      * Renames a file.
      *
      * File::rename should be preferred or you may face bad filesystem consistency.
      *
-     * @param string $sourceKey
-     * @param string $targetKey
-     *
      * @return bool TRUE if the rename was successful
      *
      * @throws Exception\FileNotFound    when sourceKey does not exist
@@ -32,7 +27,7 @@ public function has($key);
      *
      * @see File::rename()
      */
-    public function rename($sourceKey, $targetKey);
+    public function rename(string $sourceKey, string $targetKey): bool;
 
     /**
      * Returns the file matching the specified key.
@@ -42,10 +37,8 @@ public function rename($sourceKey, $targetKey);
      *
      * @throws Exception\FileNotFound
      * @throws \InvalidArgumentException If $key is invalid
-     *
-     * @return File
      */
-    public function get($key, $create = false);
+    public function get(string $key, bool $create = false): File;
 
     /**
      * Writes the given content into the file.
@@ -60,7 +53,7 @@ public function get($key, $create = false);
      *
      * @return int The number of bytes that were written into the file
      */
-    public function write($key, $content, $overwrite = false);
+    public function write(string $key, string $content, bool $overwrite = false): int;
 
     /**
      * Reads the content from the file.
@@ -70,27 +63,19 @@ public function write($key, $content, $overwrite = false);
      * @throws Exception\FileNotFound    when file does not exist
      * @throws \RuntimeException         when cannot read file
      * @throws \InvalidArgumentException If $key is invalid
-     *
-     * @return string
      */
-    public function read($key);
+    public function read(string $key): string;
 
     /**
      * Deletes the file matching the specified key.
      *
-     * @param string $key
-     *
      * @throws \RuntimeException         when cannot read file
      * @throws \InvalidArgumentException If $key is invalid
-     *
-     * @return bool
      */
-    public function delete($key);
+    public function delete(string $key): bool;
 
     /**
      * Returns an array of all keys.
-     *
-     * @return array
      */
     public function keys();
 
@@ -100,83 +85,56 @@ public function keys();
      *
      * if adapter implements ListKeysAware interface, adapter's implementation will be used,
      * in not, ALL keys will be requested and iterated through.
-     *
-     * @param string $prefix
-     *
-     * @return array
      */
-    public function listKeys($prefix = '');
+    public function listKeys(string $prefix = ''): array;
 
     /**
      * Returns the last modified time of the specified file.
      *
-     * @param string $key
-     *
-     * @return int An UNIX like timestamp
+     * @return int|bool An UNIX like timestamp or false
      *
      * @throws \InvalidArgumentException If $key is invalid
      */
-    public function mtime($key);
+    public function mtime(string $key): int|bool;
 
     /**
      * Returns the checksum of the specified file's content.
      *
-     * @param string $key
-     *
      * @return string A MD5 hash
      *
      * @throws \InvalidArgumentException If $key is invalid
      */
-    public function checksum($key);
+    public function checksum(string $key): string;
 
     /**
      * Returns the size of the specified file's content.
      *
-     * @param string $key
-     *
      * @return int File size in Bytes
      *
      * @throws \InvalidArgumentException If $key is invalid
      */
-    public function size($key);
+    public function size(string $key): int;
 
     /**
      * Gets a new stream instance of the specified file.
      *
-     * @param $key
-     *
-     * @return Stream|Stream\InMemoryBuffer
-     *
      * @throws \InvalidArgumentException If $key is invalid
      */
-    public function createStream($key);
+    public function createStream(string $key): Stream|Stream\InMemoryBuffer;
 
     /**
      * Creates a new file in a filesystem.
      *
-     * @param $key
-     *
-     * @return File
-     *
      * @throws \InvalidArgumentException If $key is invalid
      */
-    public function createFile($key);
+    public function createFile(string $key): File;
 
     /**
      * Get the mime type of the provided key.
      *
-     * @param string $key
-     *
-     * @return string|false
-     *
      * @throws \InvalidArgumentException If $key is invalid
      */
-    public function mimeType($key);
+    public function mimeType(string $key): string|bool;
 
-    /**
-     * @param string $key
-     *
-     * @return bool
-     */
-    public function isDirectory($key);
+    public function isDirectory(string $key): bool;
 }