From 9448095e2f44b595247410d0fc497b7b68e5240c Mon Sep 17 00:00:00 2001
From: azjezz <azjezz@protonmail.com>
Date: Tue, 23 Feb 2021 13:06:12 +0100
Subject: [PATCH] [Filesystem] Introduce filesystem component

---
 phpunit.xml.dist                              |  14 ++
 .../Exception/ExceptionInterface.php          |  11 ++
 .../Filesystem/Exception/RuntimeException.php |  11 ++
 src/Psl/Filesystem/Internal/write_file.php    |  67 +++++++
 src/Psl/Filesystem/append_file.php            |  21 ++
 src/Psl/Filesystem/canonicalize.php           |  18 ++
 src/Psl/Filesystem/change_group.php           |  38 ++++
 src/Psl/Filesystem/change_owner.php           |  37 ++++
 src/Psl/Filesystem/change_permissions.php     |  33 ++++
 src/Psl/Filesystem/constants.php              |  12 ++
 src/Psl/Filesystem/copy.php                   |  72 +++++++
 src/Psl/Filesystem/create_directory.php       |  32 +++
 src/Psl/Filesystem/create_file.php            |  51 +++++
 src/Psl/Filesystem/create_hard_link.php       |  55 ++++++
 src/Psl/Filesystem/create_symbolic_link.php   |  53 +++++
 src/Psl/Filesystem/create_temporary_file.php  |  58 ++++++
 src/Psl/Filesystem/delete_directory.php       |  54 +++++
 src/Psl/Filesystem/delete_file.php            |  34 ++++
 src/Psl/Filesystem/exists.php                 |  22 +++
 src/Psl/Filesystem/file_size.php              |  33 ++++
 src/Psl/Filesystem/get_access_time.php        |  40 ++++
 src/Psl/Filesystem/get_basename.php           |  30 +++
 src/Psl/Filesystem/get_change_time.php        |  41 ++++
 src/Psl/Filesystem/get_directory.php          |  33 ++++
 src/Psl/Filesystem/get_extension.php          |  19 ++
 src/Psl/Filesystem/get_filename.php           |  21 ++
 src/Psl/Filesystem/get_group.php              |  38 ++++
 src/Psl/Filesystem/get_inode.php              |  40 ++++
 src/Psl/Filesystem/get_modification_time.php  |  41 ++++
 src/Psl/Filesystem/get_owner.php              |  38 ++++
 src/Psl/Filesystem/get_permissions.php        |  40 ++++
 src/Psl/Filesystem/is_directory.php           |  25 +++
 src/Psl/Filesystem/is_executable.php          |  23 +++
 src/Psl/Filesystem/is_file.php                |  25 +++
 src/Psl/Filesystem/is_readable.php            |  23 +++
 src/Psl/Filesystem/is_symbolic_link.php       |  22 +++
 src/Psl/Filesystem/is_writable.php            |  23 +++
 src/Psl/Filesystem/read_directory.php         |  30 +++
 src/Psl/Filesystem/read_file.php              |  51 +++++
 src/Psl/Filesystem/read_symbolic_link.php     |  44 +++++
 src/Psl/Filesystem/write_file.php             |  21 ++
 src/Psl/Internal/Loader.php                   |  43 ++++
 src/Psl/Internal/box.php                      |  53 +++++
 src/Psl/Math/maxva.php                        |   3 +-
 tests/.cache/.gitignore                       |   2 +
 .../Psl/Filesystem/AbstractFilesystemTest.php |  60 ++++++
 tests/Psl/Filesystem/CopyTest.php             |  58 ++++++
 tests/Psl/Filesystem/FileTest.php             | 179 +++++++++++++++++
 tests/Psl/Filesystem/LinkTest.php             | 187 ++++++++++++++++++
 tests/Psl/Filesystem/PathTest.php             |  68 +++++++
 tests/Psl/Filesystem/PermissionsTest.php      |  56 ++++++
 tests/Psl/Filesystem/ReadDirectoryTest.php    |  73 +++++++
 52 files changed, 2175 insertions(+), 1 deletion(-)
 create mode 100644 src/Psl/Filesystem/Exception/ExceptionInterface.php
 create mode 100644 src/Psl/Filesystem/Exception/RuntimeException.php
 create mode 100644 src/Psl/Filesystem/Internal/write_file.php
 create mode 100644 src/Psl/Filesystem/append_file.php
 create mode 100644 src/Psl/Filesystem/canonicalize.php
 create mode 100644 src/Psl/Filesystem/change_group.php
 create mode 100644 src/Psl/Filesystem/change_owner.php
 create mode 100644 src/Psl/Filesystem/change_permissions.php
 create mode 100644 src/Psl/Filesystem/constants.php
 create mode 100644 src/Psl/Filesystem/copy.php
 create mode 100644 src/Psl/Filesystem/create_directory.php
 create mode 100644 src/Psl/Filesystem/create_file.php
 create mode 100644 src/Psl/Filesystem/create_hard_link.php
 create mode 100644 src/Psl/Filesystem/create_symbolic_link.php
 create mode 100644 src/Psl/Filesystem/create_temporary_file.php
 create mode 100644 src/Psl/Filesystem/delete_directory.php
 create mode 100644 src/Psl/Filesystem/delete_file.php
 create mode 100644 src/Psl/Filesystem/exists.php
 create mode 100644 src/Psl/Filesystem/file_size.php
 create mode 100644 src/Psl/Filesystem/get_access_time.php
 create mode 100644 src/Psl/Filesystem/get_basename.php
 create mode 100644 src/Psl/Filesystem/get_change_time.php
 create mode 100644 src/Psl/Filesystem/get_directory.php
 create mode 100644 src/Psl/Filesystem/get_extension.php
 create mode 100644 src/Psl/Filesystem/get_filename.php
 create mode 100644 src/Psl/Filesystem/get_group.php
 create mode 100644 src/Psl/Filesystem/get_inode.php
 create mode 100644 src/Psl/Filesystem/get_modification_time.php
 create mode 100644 src/Psl/Filesystem/get_owner.php
 create mode 100644 src/Psl/Filesystem/get_permissions.php
 create mode 100644 src/Psl/Filesystem/is_directory.php
 create mode 100644 src/Psl/Filesystem/is_executable.php
 create mode 100644 src/Psl/Filesystem/is_file.php
 create mode 100644 src/Psl/Filesystem/is_readable.php
 create mode 100644 src/Psl/Filesystem/is_symbolic_link.php
 create mode 100644 src/Psl/Filesystem/is_writable.php
 create mode 100644 src/Psl/Filesystem/read_directory.php
 create mode 100644 src/Psl/Filesystem/read_file.php
 create mode 100644 src/Psl/Filesystem/read_symbolic_link.php
 create mode 100644 src/Psl/Filesystem/write_file.php
 create mode 100644 src/Psl/Internal/box.php
 create mode 100644 tests/.cache/.gitignore
 create mode 100644 tests/Psl/Filesystem/AbstractFilesystemTest.php
 create mode 100644 tests/Psl/Filesystem/CopyTest.php
 create mode 100644 tests/Psl/Filesystem/FileTest.php
 create mode 100644 tests/Psl/Filesystem/LinkTest.php
 create mode 100644 tests/Psl/Filesystem/PathTest.php
 create mode 100644 tests/Psl/Filesystem/PermissionsTest.php
 create mode 100644 tests/Psl/Filesystem/ReadDirectoryTest.php

diff --git a/phpunit.xml.dist b/phpunit.xml.dist
index f02d12eb..91fdd28e 100644
--- a/phpunit.xml.dist
+++ b/phpunit.xml.dist
@@ -6,12 +6,26 @@
       <directory>src</directory>
     </include>
     <exclude>
+      <!-- Internal -->
       <file>src/preload.php</file>
       <file>src/bootstrap.php</file>
       <directory>src/Psl/Internal</directory>
+
+      <!-- Base Exceptions -->
       <directory>src/Psl/Exception</directory>
+
+      <!-- Constants -->
       <file>src/Psl/Str/constants.php</file>
       <file>src/Psl/Math/constants.php</file>
+      <file>src/Psl/Filesystem/constants.php</file>
+
+      <!-- Things that are not easily tested -->
+      <file>src/Psl/Filesystem/get_group.php</file>
+      <file>src/Psl/Filesystem/change_group.php</file>
+      <file>src/Psl/Filesystem/Internal/change_group.php</file>
+      <file>src/Psl/Filesystem/get_owner.php</file>
+      <file>src/Psl/Filesystem/change_owner.php</file>
+      <file>src/Psl/Filesystem/Internal/change_owner.php</file>
     </exclude>
     <report>
       <clover outputFile="tests/logs/clover.xml"/>
diff --git a/src/Psl/Filesystem/Exception/ExceptionInterface.php b/src/Psl/Filesystem/Exception/ExceptionInterface.php
new file mode 100644
index 00000000..62c9103d
--- /dev/null
+++ b/src/Psl/Filesystem/Exception/ExceptionInterface.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem\Exception;
+
+use Psl\Exception;
+
+interface ExceptionInterface extends Exception\ExceptionInterface
+{
+}
diff --git a/src/Psl/Filesystem/Exception/RuntimeException.php b/src/Psl/Filesystem/Exception/RuntimeException.php
new file mode 100644
index 00000000..4ac835fa
--- /dev/null
+++ b/src/Psl/Filesystem/Exception/RuntimeException.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem\Exception;
+
+use Psl\Exception;
+
+class RuntimeException extends Exception\RuntimeException implements ExceptionInterface
+{
+}
diff --git a/src/Psl/Filesystem/Internal/write_file.php b/src/Psl/Filesystem/Internal/write_file.php
new file mode 100644
index 00000000..bda0f50e
--- /dev/null
+++ b/src/Psl/Filesystem/Internal/write_file.php
@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem\Internal;
+
+use Psl;
+use Psl\Filesystem;
+use Psl\Filesystem\Exception;
+use Psl\Internal;
+use Psl\Str;
+
+use function file_put_contents;
+
+use const FILE_APPEND;
+use const LOCK_EX;
+
+/**
+ * Write $content to $file.
+ *
+ * @param bool $append If true, and $file exists, append $content to $file instead of overwriting it.
+ *
+ * @throws Psl\Exception\InvariantViolationException If the file specified by
+ *  $file does not exist, or is not writeable.
+ * @throws Exception\RuntimeException In case of an error.
+ */
+function write_file(string $file, string $content, bool $append): void
+{
+    if (Filesystem\exists($file)) {
+        Psl\invariant(Filesystem\is_file($file), '$file is not a file.');
+        Psl\invariant(Filesystem\is_writable($file), '$file is not writeable.');
+    } else {
+        Filesystem\create_file($file);
+    }
+
+    if ($append) {
+        // Mutually exclusive with LOCK_EX since appends are atomic
+        // and thus there is no reason to lock.
+        $flags = FILE_APPEND;
+    } else {
+        $flags = LOCK_EX;
+    }
+
+    [$written, $error] = Internal\box(
+        static fn() => file_put_contents($file, $content, $flags)
+    );
+
+    // @codeCoverageIgnoreStart
+    if (false === $written || null !== $error) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to write to file "%s": %s.',
+            $file,
+            $error ?? 'internal error',
+        ));
+    }
+
+    $length = Str\Byte\length($content);
+    if ($written !== $length) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to write the whole content to "%s" ( %g of %g bytes written ).',
+            $file,
+            $written,
+            $length,
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+}
diff --git a/src/Psl/Filesystem/append_file.php b/src/Psl/Filesystem/append_file.php
new file mode 100644
index 00000000..857bd490
--- /dev/null
+++ b/src/Psl/Filesystem/append_file.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+
+/**
+ * Append $content to $file.
+ *
+ * If $file does not exist, it will be created.
+ *
+ * @throws Psl\Exception\InvariantViolationException If the file specified by
+ *  $file is a directory, or is not writeable.
+ * @throws Exception\RuntimeException In case of an error.
+ */
+function append_file(string $file, string $content): void
+{
+     Internal\write_file($file, $content, true);
+}
diff --git a/src/Psl/Filesystem/canonicalize.php b/src/Psl/Filesystem/canonicalize.php
new file mode 100644
index 00000000..7342a3f0
--- /dev/null
+++ b/src/Psl/Filesystem/canonicalize.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use function realpath;
+
+/**
+ * Returns canonicalized absolute pathname.
+ *
+ * @return string|null  The canonicalized absolute pathname on success.
+ *  The resulting path will have no symbolic link, '/./' or '/../' components.
+ */
+function canonicalize(string $path): ?string
+{
+    return realpath($path) ?: null;
+}
diff --git a/src/Psl/Filesystem/change_group.php b/src/Psl/Filesystem/change_group.php
new file mode 100644
index 00000000..0284d08e
--- /dev/null
+++ b/src/Psl/Filesystem/change_group.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Internal;
+use Psl\Str;
+
+use function chgrp;
+use function lchgrp;
+
+/**
+ * Change the group ownership of $filename.
+ *
+ * @throws Exception\RuntimeException If unable to change the group ownership for $filename.
+ * @throws Psl\Exception\InvariantViolationException If $filename does not exist.
+ */
+function change_group(string $filename, int $group): void
+{
+    Psl\invariant(exists($filename), '$filename does not exist.');
+
+    if (is_symbolic_link($filename)) {
+        $fun = static fn(): bool => lchgrp($filename, $group);
+    } else {
+        $fun = static fn(): bool => chgrp($filename, $group);
+    }
+
+    [$success, $error] = Internal\box($fun);
+    if (!$success) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to change the group for file "%s": %s',
+            $filename,
+            $error ?? 'internal error.',
+        ));
+    }
+}
diff --git a/src/Psl/Filesystem/change_owner.php b/src/Psl/Filesystem/change_owner.php
new file mode 100644
index 00000000..ac305797
--- /dev/null
+++ b/src/Psl/Filesystem/change_owner.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Internal;
+use Psl\Str;
+
+use function chown;
+use function lchown;
+
+/**
+ * Change the owner of $filename.
+ *
+ * @throws Exception\RuntimeException   If unable to change the ownership for $filename.
+ * @throws Psl\Exception\InvariantViolationException If $filename does not exist.
+ */
+function change_owner(string $filename, int $user): void
+{
+    Psl\invariant(exists($filename), '$filename does not exist.');
+    if (is_symbolic_link($filename)) {
+        $fun = static fn(): bool => lchown($filename, $user);
+    } else {
+        $fun = static fn(): bool => chown($filename, $user);
+    }
+
+    [$success, $error] = Internal\box($fun);
+    if (!$success) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to change owner for file "%s": %s',
+            $filename,
+            $error ?? 'internal error.',
+        ));
+    }
+}
diff --git a/src/Psl/Filesystem/change_permissions.php b/src/Psl/Filesystem/change_permissions.php
new file mode 100644
index 00000000..ed7ae346
--- /dev/null
+++ b/src/Psl/Filesystem/change_permissions.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Internal;
+use Psl\Str;
+
+use function chmod;
+
+/**
+ * Changes mode permission of $filename.
+ *
+ * @throws Exception\RuntimeException If unable to change the mode for the given $filename.
+ * @throws Psl\Exception\InvariantViolationException If $filename does not exists.
+ */
+function change_permissions(string $filename, int $permissions): void
+{
+    Psl\invariant(exists($filename), '$filename does not exist.');
+
+    [$success, $error] = Internal\box(static fn(): bool => chmod($filename, $permissions));
+    // @codeCoverageIgnoreStart
+    if (!$success) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to change permissions for file "%s": %s',
+            $filename,
+            $error ?? 'internal error.',
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+}
diff --git a/src/Psl/Filesystem/constants.php b/src/Psl/Filesystem/constants.php
new file mode 100644
index 00000000..70af81d4
--- /dev/null
+++ b/src/Psl/Filesystem/constants.php
@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use const DIRECTORY_SEPARATOR;
+
+/**
+ * @var string
+ */
+const SEPARATOR = DIRECTORY_SEPARATOR;
diff --git a/src/Psl/Filesystem/copy.php b/src/Psl/Filesystem/copy.php
new file mode 100644
index 00000000..9b224850
--- /dev/null
+++ b/src/Psl/Filesystem/copy.php
@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Internal;
+use Psl\Str;
+
+use function fclose;
+use function fopen;
+use function stream_copy_to_stream;
+
+/**
+ * Change the group ownership of $filename.
+ *
+ * @throws Exception\RuntimeException If unable to change the group ownership for $filename.
+ * @throws Psl\Exception\InvariantViolationException If $source does not exist or is not readable.
+ */
+function copy(string $source, string $destination, bool $overwrite = false): void
+{
+    Psl\invariant(is_file($source) && is_readable($source), '$source does not exist or is not readable.');
+
+    if (!$overwrite && is_file($destination)) {
+        return;
+    }
+
+    /**
+     * @psalm-suppress InvalidArgument - callable is not pure..
+     */
+    $source_stream = Internal\suppress(static fn() => fopen($source, 'rb'));
+    // @codeCoverageIgnoreStart
+    if (false === $source_stream) {
+        throw new Exception\RuntimeException('Failed to open $source file for reading');
+    }
+    // @codeCoverageIgnoreEnd
+
+    /**
+     * @psalm-suppress InvalidArgument - callable is not pure..
+     */
+    $destination_stream = Internal\suppress(static fn() => fopen($destination, 'wb'));
+    // @codeCoverageIgnoreStart
+    if (false === $destination_stream) {
+        throw new Exception\RuntimeException('Failed to open $destination file for writing.');
+    }
+    // @codeCoverageIgnoreEnd
+
+    $copied_bytes = stream_copy_to_stream($source_stream, $destination_stream);
+    fclose($source_stream);
+    fclose($destination_stream);
+
+    $total_bytes = file_size($source);
+
+    // preserve executable permission bits
+    change_permissions(
+        $destination,
+        get_permissions($destination) | (get_permissions($source) & 0111)
+    );
+
+    // @codeCoverageIgnoreStart
+    if ($copied_bytes !== $total_bytes) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to copy the whole content of "%s" to "%s" ( %g of %g bytes copied ).',
+            $source,
+            $destination,
+            $copied_bytes,
+            $total_bytes
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+}
diff --git a/src/Psl/Filesystem/create_directory.php b/src/Psl/Filesystem/create_directory.php
new file mode 100644
index 00000000..f9756a95
--- /dev/null
+++ b/src/Psl/Filesystem/create_directory.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl\Internal;
+use Psl\Str;
+
+use function mkdir;
+
+/**
+ * Create the directory specified by $directory.
+ *
+ * @throws Exception\RuntimeException If unable to create the directory.
+ */
+function create_directory(string $directory, int $permissions = 0777): void
+{
+    [$result, $error_message] = Internal\box(
+        static fn() => mkdir($directory, $permissions, true)
+    );
+
+    // @codeCoverageIgnoreStart
+    if (false === $result && !is_directory($directory)) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to create directory "%s": %s.',
+            $directory,
+            $error_message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+}
diff --git a/src/Psl/Filesystem/create_file.php b/src/Psl/Filesystem/create_file.php
new file mode 100644
index 00000000..ba8f9a7f
--- /dev/null
+++ b/src/Psl/Filesystem/create_file.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl\Internal;
+use Psl\Math;
+use Psl\Str;
+
+use function touch;
+
+/**
+ * Create the file specified by $filename.
+ *
+ * @param int|null $time The touch time as a Unix timestamp,
+ *  If not supplied the current system time is used.
+ * @param int|null $access_time The access time as a Unix timestamp,
+ *  If not supplied the current system time is used.
+ *
+ * @throws Exception\RuntimeException If unable to create the file.
+ */
+function create_file(string $filename, ?int $time = null, ?int $access_time = null): void
+{
+    if (null === $access_time && null === $time) {
+        $fun = static fn(): bool => touch($filename);
+    } elseif (null === $access_time) {
+        $fun = static fn(): bool => touch($filename, $time);
+    } else {
+        $time = $time ?? $access_time;
+
+        $fun = static fn(): bool => touch($filename, $time, Math\maxva($access_time, $time));
+    }
+
+    /** @psalm-suppress MissingThrowsDocblock */
+    $directory = get_directory($filename);
+    if (!is_directory($directory)) {
+        create_directory($directory);
+    }
+
+    [$result, $error_message] = Internal\box($fun);
+    // @codeCoverageIgnoreStart
+    if (false === $result && !is_file($filename)) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to create file "%s": %s.',
+            $filename,
+            $error_message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+}
diff --git a/src/Psl/Filesystem/create_hard_link.php b/src/Psl/Filesystem/create_hard_link.php
new file mode 100644
index 00000000..e918ad2e
--- /dev/null
+++ b/src/Psl/Filesystem/create_hard_link.php
@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Internal;
+use Psl\Str;
+
+use function link;
+
+/**
+ * Create a hard link for $source.
+ *
+ * @param string $source The file to create a hard link for.
+ *
+ * @throws Psl\Exception\InvariantViolationException If $source is not a file, or does not exist.
+ * @throws Exception\RuntimeException If unable to create a hard file.
+ */
+function create_hard_link(string $source, string $destination): void
+{
+    Psl\invariant(exists($source), '$source file does not exist.');
+    Psl\invariant(is_file($source), '$source is not a file.');
+
+    $destination_directory = get_directory($destination);
+    if (!is_directory($destination_directory)) {
+        create_directory($destination_directory);
+    }
+
+    if (exists($destination)) {
+        if (get_inode($destination) === get_inode($source)) {
+            // already exists.
+            return;
+        }
+
+        if (is_directory($destination)) {
+            delete_directory($destination, true);
+        } else {
+            delete_file($destination);
+        }
+    }
+
+    [$result, $error_message] = Internal\box(static fn() => link($source, $destination));
+    // @codeCoverageIgnoreStart
+    if (false === $result) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to create hard link "%s" from "%s": %s.',
+            $destination,
+            $source,
+            $error_message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+}
diff --git a/src/Psl/Filesystem/create_symbolic_link.php b/src/Psl/Filesystem/create_symbolic_link.php
new file mode 100644
index 00000000..4069ae07
--- /dev/null
+++ b/src/Psl/Filesystem/create_symbolic_link.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Internal;
+use Psl\Str;
+
+use function symlink;
+
+/**
+ * Create a symbolic link for $source.
+ *
+ * @param string $source The file to create a hard link for.
+ *
+ * @throws Exception\RuntimeException If unable to create the symbolic link.
+ * @throws Psl\Exception\InvariantViolationException If $source does not exist.
+ */
+function create_symbolic_link(string $source, string $destination): void
+{
+    Psl\invariant(exists($source), '$source does not exist.');
+    $destination_directory = get_directory($destination);
+    if (!is_directory($destination_directory)) {
+        create_directory($destination_directory);
+    }
+
+    if (exists($destination)) {
+        if (is_symbolic_link($destination) && read_symbolic_link($destination) === $source) {
+            // already exists.
+            return;
+        }
+
+        if (is_directory($destination)) {
+            delete_directory($destination, true);
+        } else {
+            delete_file($destination);
+        }
+    }
+
+    [$result, $error_message] = Internal\box(static fn() => symlink($source, $destination));
+    // @codeCoverageIgnoreStart
+    if (false === $result) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to create symbolic link "%s" from "%s": %s.',
+            $destination,
+            $source,
+            $error_message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+}
diff --git a/src/Psl/Filesystem/create_temporary_file.php b/src/Psl/Filesystem/create_temporary_file.php
new file mode 100644
index 00000000..91220f2a
--- /dev/null
+++ b/src/Psl/Filesystem/create_temporary_file.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Env;
+use Psl\SecureRandom;
+use Psl\Str;
+
+/**
+ * Create a temporary file.
+ *
+ * @param string|null $directory    The directory where the temporary filename will be created.
+ *                                  If no specified, `Env\temp_dir()` will be used to retrieve
+ *                                  the system default temporary directory.
+ *
+ * @param string|null $prefix The prefix of the generated temporary filename.
+ *
+ * @return string The absolute path to the temporary file.
+ *
+ * @throws Psl\Exception\InvariantViolationException If $directory doesn't exist or is not writable.
+ * @throws Psl\Exception\InvariantViolationException If $prefix contains a directory separator.
+ *
+ * @throws Exception\RuntimeException If unable to create the file.
+ */
+function create_temporary_file(?string $directory = null, ?string $prefix = null): string
+{
+    if (null !== $directory) {
+        Psl\invariant(is_directory($directory), '$directory is not a directory.');
+        Psl\invariant(is_writable($directory), '$directory is not writable.');
+    } else {
+        $directory = Env\temp_dir();
+    }
+
+    if (null !== $prefix) {
+        Psl\invariant(
+            !Str\contains($prefix, SEPARATOR),
+            '$prefix should not contain a directory separator ( "%s" ).',
+            SEPARATOR
+        );
+    } else {
+        $prefix = '';
+    }
+
+    try {
+        $filename = $directory . '/' . $prefix . SecureRandom\string(8);
+        // @codeCoverageIgnoreStart
+    } catch (SecureRandom\Exception\InsufficientEntropyException $e) {
+        throw new Exception\RuntimeException('Unable to gather enough entropy to generate filename.', 0, $e);
+    }
+    // @codeCoverageIgnoreEnd
+
+    create_file($filename);
+
+    return $filename;
+}
diff --git a/src/Psl/Filesystem/delete_directory.php b/src/Psl/Filesystem/delete_directory.php
new file mode 100644
index 00000000..b526fe34
--- /dev/null
+++ b/src/Psl/Filesystem/delete_directory.php
@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Fun;
+use Psl\Internal;
+use Psl\Iter;
+use Psl\Str;
+use Psl\Vec;
+
+use function rmdir;
+
+/**
+ * Delete the directory specified by $directory.
+ *
+ * @throws Exception\RuntimeException If unable to delete the directory.
+ * @throws Psl\Exception\InvariantViolationException If the directory specified by
+ *  $directory does not exist.
+ */
+function delete_directory(string $directory, bool $recursive = false): void
+{
+    Psl\invariant(is_directory($directory), '$directory does not exists.');
+
+    if ($recursive && !is_symbolic_link($directory)) {
+        [$symbolic_nodes, $nodes] = Vec\partition(
+            read_directory($directory),
+            static fn(string $node): bool => is_symbolic_link($node)
+        );
+
+        Iter\apply($symbolic_nodes, static fn(string $node) => delete_file($node));
+        Iter\apply(
+            $nodes,
+            Fun\when(
+                static fn(string $node) => is_directory($node),
+                static fn(string $node) => delete_directory($node, true),
+                static fn(string $node) => delete_file($node),
+            )
+        );
+    }
+
+    [$result, $error_message] = Internal\box(static fn() => rmdir($directory));
+    // @codeCoverageIgnoreStart
+    if (false === $result && is_directory($directory)) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to delete directory "%s": %s.',
+            $directory,
+            $error_message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+}
diff --git a/src/Psl/Filesystem/delete_file.php b/src/Psl/Filesystem/delete_file.php
new file mode 100644
index 00000000..938799d9
--- /dev/null
+++ b/src/Psl/Filesystem/delete_file.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Internal;
+use Psl\Str;
+
+use function unlink;
+
+/**
+ * Delete the file specified by $filename.
+ *
+ * @throws Exception\RuntimeException If unable to delete the file.
+ * @throws Psl\Exception\InvariantViolationException If the file specified by
+ *  $filename does not exist.
+ */
+function delete_file(string $filename): void
+{
+    Psl\invariant(is_file($filename), '$filename does not exists.');
+
+    [$result, $error_message] = Internal\box(static fn() => unlink($filename));
+    // @codeCoverageIgnoreStart
+    if (false === $result && is_file($filename)) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to delete file "%s": %s.',
+            $filename,
+            $error_message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+}
diff --git a/src/Psl/Filesystem/exists.php b/src/Psl/Filesystem/exists.php
new file mode 100644
index 00000000..dab93a2d
--- /dev/null
+++ b/src/Psl/Filesystem/exists.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use function file_exists;
+
+/**
+ * Check whether $filename exists.
+ *
+ * @param string $filename  Path to the file.
+ *
+ * If $filename is a relative filename, it will be checked relative to
+ * the current working directory.
+ *
+ * @return bool true if $filename exists, false otherwise.
+ */
+function exists(string $filename): bool
+{
+    return file_exists($filename);
+}
diff --git a/src/Psl/Filesystem/file_size.php b/src/Psl/Filesystem/file_size.php
new file mode 100644
index 00000000..e9745abb
--- /dev/null
+++ b/src/Psl/Filesystem/file_size.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Internal;
+use Psl\Str;
+
+/**
+ * Ge the size of $filename.
+ *
+ * @throws Psl\Exception\InvariantViolationException If $filename does not exist or is not readable.
+ * @throws Exception\RuntimeException In case of an error.
+ */
+function file_size(string $filename): int
+{
+    Psl\invariant(is_file($filename) && is_readable($filename), '$filename does not exist.');
+
+    // @codeCoverageIgnoreStart
+    [$size, $message] = Internal\box(static fn() => filesize($filename));
+    if (false === $size) {
+        throw new Exception\RuntimeException(Str\format(
+            'Error reading the size of file "%s": %s',
+            $filename,
+            $message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+
+    return $size;
+}
diff --git a/src/Psl/Filesystem/get_access_time.php b/src/Psl/Filesystem/get_access_time.php
new file mode 100644
index 00000000..49b710fe
--- /dev/null
+++ b/src/Psl/Filesystem/get_access_time.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Str;
+
+use function fileatime;
+
+/**
+ * Gets last access time of $filename.
+ *
+ * @throws Psl\Exception\InvariantViolationException If $filename does not exist.
+ * @throws Exception\RuntimeException In case of an error.
+ */
+function get_access_time(string $filename): int
+{
+    Psl\invariant(exists($filename), '$filename does not exists.');
+
+    [$result, $message] = Psl\Internal\box(
+        /**
+         * @return false|int
+         */
+        static fn() => fileatime($filename)
+    );
+
+    // @codeCoverageIgnoreStart
+    if (false === $result) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to retrieve the access time of "%s": %s',
+            $filename,
+            $message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+
+    return $result;
+}
diff --git a/src/Psl/Filesystem/get_basename.php b/src/Psl/Filesystem/get_basename.php
new file mode 100644
index 00000000..e526c81e
--- /dev/null
+++ b/src/Psl/Filesystem/get_basename.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use function basename as php_basename;
+
+/**
+ * Returns trailing name component of path.
+ *
+ * On Windows, both forward slash `/` and back slash `\` are used
+ * as directory separator character.
+ *
+ * In other environments, it is the forward slash `/`.
+ *
+ * @param string|null $suffix If the filename ends in a suffix, this will also be cut off.
+ *
+ * @return string the base name of the given path.
+ *
+ * @psalm-pure
+ */
+function get_basename(string $path, ?string $suffix = null): string
+{
+    if (null === $suffix) {
+        return php_basename($path);
+    }
+
+    return php_basename($path, $suffix);
+}
diff --git a/src/Psl/Filesystem/get_change_time.php b/src/Psl/Filesystem/get_change_time.php
new file mode 100644
index 00000000..ec500225
--- /dev/null
+++ b/src/Psl/Filesystem/get_change_time.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Str;
+
+use function filectime;
+
+/**
+ * Get the last time the inode of $filename
+ * was changed ( e.g: permission change, ownership change .. etc )
+ *
+ * @throws Psl\Exception\InvariantViolationException If $filename does not exist.
+ * @throws Exception\RuntimeException In case of an error.
+ */
+function get_change_time(string $filename): int
+{
+    Psl\invariant(exists($filename), '$filename does not exists.');
+
+    [$result, $message] = Psl\Internal\box(
+        /**
+         * @return false|int
+         */
+        static fn() => filectime($filename)
+    );
+
+    // @codeCoverageIgnoreStart
+    if (false === $result) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to retrieve the change time of "%s": %s',
+            $filename,
+            $message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+
+    return $result;
+}
diff --git a/src/Psl/Filesystem/get_directory.php b/src/Psl/Filesystem/get_directory.php
new file mode 100644
index 00000000..52f165bb
--- /dev/null
+++ b/src/Psl/Filesystem/get_directory.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+
+use function dirname;
+
+/**
+ * Returns a parent directory's path
+ *
+ * On Windows, both forward slash `/` and back slash `\` are used
+ * as directory separator character.
+ *
+ * In other environments, it is the forward slash `/`.
+ *
+ * @param positive-int $levels The number of parent directories to go up.
+ *
+ * @return string the base name of the given path.
+ *
+ * @throws Psl\Exception\InvariantViolationException If $levels is not a positive integer.
+ *
+ * @psalm-pure
+ */
+function get_directory(string $path, int $levels = 1): string
+{
+    /** @psalm-suppress RedundantCondition */
+    Psl\invariant($levels > 0, '$levels must be a positive integer, %d given.', $levels);
+
+    return dirname($path, $levels);
+}
diff --git a/src/Psl/Filesystem/get_extension.php b/src/Psl/Filesystem/get_extension.php
new file mode 100644
index 00000000..9d7bfb36
--- /dev/null
+++ b/src/Psl/Filesystem/get_extension.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use function pathinfo;
+
+/**
+ * Returns the $filename extension.
+ *
+ * @return string|null the $filename extensions, or null if none.
+ *
+ * @psalm-pure
+ */
+function get_extension(string $filename): ?string
+{
+    return pathinfo($filename)['extension'] ?? null;
+}
diff --git a/src/Psl/Filesystem/get_filename.php b/src/Psl/Filesystem/get_filename.php
new file mode 100644
index 00000000..eb5c66b2
--- /dev/null
+++ b/src/Psl/Filesystem/get_filename.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use function pathinfo;
+
+use const PATHINFO_FILENAME;
+
+/**
+ * Returns trailing name component of path.
+ *
+ * @return string the base name of the given path.
+ *
+ * @psalm-pure
+ */
+function get_filename(string $path): string
+{
+    return pathinfo($path, PATHINFO_FILENAME);
+}
diff --git a/src/Psl/Filesystem/get_group.php b/src/Psl/Filesystem/get_group.php
new file mode 100644
index 00000000..5a96558f
--- /dev/null
+++ b/src/Psl/Filesystem/get_group.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Str;
+
+use function filegroup;
+
+/**
+ * Get the group of $filename.
+ *
+ * @throws Psl\Exception\InvariantViolationException If $filename does not exist.
+ * @throws Exception\RuntimeException In case of an error.
+ */
+function get_group(string $filename): int
+{
+    Psl\invariant(exists($filename), '$filename does not exists.');
+
+    [$result, $message] = Psl\Internal\box(
+        /**
+         * @return false|int
+         */
+        static fn() => filegroup($filename)
+    );
+
+    if (false === $result) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to retrieve group of file "%s": %s',
+            $filename,
+            $message ?? 'internal error'
+        ));
+    }
+
+    return $result;
+}
diff --git a/src/Psl/Filesystem/get_inode.php b/src/Psl/Filesystem/get_inode.php
new file mode 100644
index 00000000..02773c2e
--- /dev/null
+++ b/src/Psl/Filesystem/get_inode.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Str;
+
+use function fileinode;
+
+/**
+ * Get the last time the content of $filename was modified.
+ *
+ * @throws Psl\Exception\InvariantViolationException If $filename does not exist.
+ * @throws Exception\RuntimeException In case of an error.
+ */
+function get_inode(string $filename): int
+{
+    Psl\invariant(exists($filename), '$filename does not exists.');
+
+    [$result, $message] = Psl\Internal\box(
+        /**
+         * @return false|int
+         */
+        static fn() => fileinode($filename)
+    );
+
+    // @codeCoverageIgnoreStart
+    if (false === $result) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to retrieve the inode of "%s": %s',
+            $filename,
+            $message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+
+    return $result;
+}
diff --git a/src/Psl/Filesystem/get_modification_time.php b/src/Psl/Filesystem/get_modification_time.php
new file mode 100644
index 00000000..f86dab1f
--- /dev/null
+++ b/src/Psl/Filesystem/get_modification_time.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Internal;
+use Psl\Str;
+
+use function filemtime;
+
+/**
+ * Get the last time the content of $filename was modified.
+ *
+ * @throws Psl\Exception\InvariantViolationException If $filename does not exist.
+ * @throws Exception\RuntimeException In case of an error.
+ */
+function get_modification_time(string $filename): int
+{
+    Psl\invariant(exists($filename), '$filename does not exists.');
+
+    [$result, $message] = Internal\box(
+        /**
+         * @return false|int
+         */
+        static fn() => filemtime($filename)
+    );
+
+    // @codeCoverageIgnoreStart
+    if (false === $result) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to retrieve the modification time of "%s": %s',
+            $filename,
+            $message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+
+    return $result;
+}
diff --git a/src/Psl/Filesystem/get_owner.php b/src/Psl/Filesystem/get_owner.php
new file mode 100644
index 00000000..321eea22
--- /dev/null
+++ b/src/Psl/Filesystem/get_owner.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Str;
+
+use function fileowner;
+
+/**
+ * Get the owner of $filename.
+ *
+ * @throws Psl\Exception\InvariantViolationException If $filename does not exist.
+ * @throws Exception\RuntimeException In case of an error.
+ */
+function get_owner(string $filename): int
+{
+    Psl\invariant(exists($filename), '$filename does not exists.');
+
+    [$result, $message] = Psl\Internal\box(
+        /**
+         * @return false|int
+         */
+        static fn() => fileowner($filename)
+    );
+
+    if (false === $result) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to retrieve owner of file "%s": %s',
+            $filename,
+            $message ?? 'internal error'
+        ));
+    }
+
+    return $result;
+}
diff --git a/src/Psl/Filesystem/get_permissions.php b/src/Psl/Filesystem/get_permissions.php
new file mode 100644
index 00000000..68244171
--- /dev/null
+++ b/src/Psl/Filesystem/get_permissions.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Str;
+
+use function fileperms;
+
+/**
+ * Get the permissions of $filename.
+ *
+ * @throws Psl\Exception\InvariantViolationException If $filename does not exist.
+ * @throws Exception\RuntimeException In case of an error.
+ */
+function get_permissions(string $filename): int
+{
+    Psl\invariant(exists($filename), '$filename does not exists.');
+
+    [$result, $message] = Psl\Internal\box(
+        /**
+         * @return false|int
+         */
+        static fn() => fileperms($filename)
+    );
+
+    // @codeCoverageIgnoreStart
+    if (false === $result) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to retrieve permissions of file "%s": %s',
+            $filename,
+            $message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+
+    return $result;
+}
diff --git a/src/Psl/Filesystem/is_directory.php b/src/Psl/Filesystem/is_directory.php
new file mode 100644
index 00000000..fee1fa92
--- /dev/null
+++ b/src/Psl/Filesystem/is_directory.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use function is_dir;
+
+/**
+ * Check whether $filename is a directory.
+ *
+ * @param string $filename  Path to the file.
+ *
+ * If $filename is a relative filename, it will be checked relative to
+ * the current working directory.
+ *
+ * If $filename is a symbolic or hard link then the link
+ * will be resolved and checked.
+ *
+ * @return bool true if $filename exists and is a directory, false otherwise.
+ */
+function is_directory(string $filename): bool
+{
+    return is_dir($filename);
+}
diff --git a/src/Psl/Filesystem/is_executable.php b/src/Psl/Filesystem/is_executable.php
new file mode 100644
index 00000000..63ca2a20
--- /dev/null
+++ b/src/Psl/Filesystem/is_executable.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use function is_executable as php_is_executable;
+
+/**
+ * Check whether $filename is executable.
+ *
+ * @param string $filename  Path to the file.
+ *
+ * If $filename is a relative filename, it will be checked relative to
+ * the current working directory.
+ *
+ * @return bool true if the file or directory specified by $filename exists
+ *  and is executable, false otherwise.
+ */
+function is_executable(string $filename): bool
+{
+    return php_is_executable($filename);
+}
diff --git a/src/Psl/Filesystem/is_file.php b/src/Psl/Filesystem/is_file.php
new file mode 100644
index 00000000..b7686fe6
--- /dev/null
+++ b/src/Psl/Filesystem/is_file.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use function is_file as php_is_file;
+
+/**
+ * Check whether $filename is a regular file.
+ *
+ * @param string $filename  Path to the file.
+ *
+ * If $filename is a relative filename, it will be checked relative to
+ * the current working directory.
+ *
+ * If $filename is a symbolic or hard link then the link
+ * will be resolved and checked.
+ *
+ * @return bool true if $filename exists and is a regular file, false otherwise.
+ */
+function is_file(string $filename): bool
+{
+    return php_is_file($filename);
+}
diff --git a/src/Psl/Filesystem/is_readable.php b/src/Psl/Filesystem/is_readable.php
new file mode 100644
index 00000000..01010949
--- /dev/null
+++ b/src/Psl/Filesystem/is_readable.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use function is_readable as php_is_readable;
+
+/**
+ * Check whether $filename is readable.
+ *
+ * @param string $filename  Path to the file.
+ *
+ * If $filename is a relative filename, it will be checked relative to
+ * the current working directory.
+ *
+ * @return bool true if the file or directory specified by $filename exists
+ *  and is readable, false otherwise.
+ */
+function is_readable(string $filename): bool
+{
+    return php_is_readable($filename);
+}
diff --git a/src/Psl/Filesystem/is_symbolic_link.php b/src/Psl/Filesystem/is_symbolic_link.php
new file mode 100644
index 00000000..ca849ce2
--- /dev/null
+++ b/src/Psl/Filesystem/is_symbolic_link.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use function is_link as php_is_link;
+
+/**
+ * Check whether $symbolic_link is a symbolic link.
+ *
+ * @param string $symbolic_link  Path to the file.
+ *
+ * If $symbolic_link is a relative filename, it will be checked relative to
+ * the current working directory.
+ *
+ * @return bool if the $symbolic_link exists and is a symbolic link, false otherwise.
+ */
+function is_symbolic_link(string $symbolic_link): bool
+{
+    return php_is_link($symbolic_link);
+}
diff --git a/src/Psl/Filesystem/is_writable.php b/src/Psl/Filesystem/is_writable.php
new file mode 100644
index 00000000..1860bf58
--- /dev/null
+++ b/src/Psl/Filesystem/is_writable.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use function is_writable as php_is_writable;
+
+/**
+ * Check whether $filename is writable.
+ *
+ * @param string $filename  Path to the file.
+ *
+ * If $filename is a relative filename, it will be checked relative to
+ * the current working directory.
+ *
+ * @return bool true if the file or directory specified by $filename exists
+ *  and is writable, false otherwise.
+ */
+function is_writable(string $filename): bool
+{
+    return php_is_writable($filename);
+}
diff --git a/src/Psl/Filesystem/read_directory.php b/src/Psl/Filesystem/read_directory.php
new file mode 100644
index 00000000..2fc1994a
--- /dev/null
+++ b/src/Psl/Filesystem/read_directory.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use FilesystemIterator;
+use Psl;
+use Psl\Vec;
+
+/**
+ * Return a vec of files and directories inside the specified directory.
+ *
+ * @return list<string>
+ *
+ * @throws Psl\Exception\InvariantViolationException If the directory specified by
+ *  $directory does not exist, or is not readable.
+ */
+function read_directory(string $directory): array
+{
+    Psl\invariant(exists($directory), '$directory does not exists.');
+    Psl\invariant(is_directory($directory), '$directory is not a directory.');
+    Psl\invariant(is_readable($directory), '$directory is not readable.');
+
+    /** @var list<string> */
+    return Vec\values(new FilesystemIterator(
+        $directory,
+        FilesystemIterator::CURRENT_AS_PATHNAME | FilesystemIterator::SKIP_DOTS
+    ));
+}
diff --git a/src/Psl/Filesystem/read_file.php b/src/Psl/Filesystem/read_file.php
new file mode 100644
index 00000000..3e04c196
--- /dev/null
+++ b/src/Psl/Filesystem/read_file.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Internal;
+use Psl\Str;
+
+use function file_get_contents;
+
+/**
+ * Reads entire file into a string.
+ *
+ * @param int       $offset The offset where the reading starts.
+ * @param null|int  $length Maximum length of data read. The default is to read
+ *                          until end of file is reached.
+ *
+ * @throws Psl\Exception\InvariantViolationException If the file specified by
+ *  $file does not exist, or is not readable.
+ * @throws Exception\RuntimeException If an error
+ */
+function read_file(string $file, int $offset = 0, ?int $length = null): string
+{
+    Psl\invariant(exists($file), '$file does not exist.');
+    Psl\invariant(is_file($file), '$file is not a file.');
+    Psl\invariant(is_readable($file), '$file is not readable.');
+
+    if (null === $length) {
+        [$content, $error] = Internal\box(
+            static fn() => file_get_contents($file, false, null, $offset)
+        );
+    } else {
+        [$content, $error] = Internal\box(
+            static fn() => file_get_contents($file, false, null, $offset, $length)
+        );
+    }
+
+    // @codeCoverageIgnoreStart
+    if (false === $content || null !== $error) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to read file "%s": %s.',
+            $file,
+            $error ?? 'internal error',
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+
+    return $content;
+}
diff --git a/src/Psl/Filesystem/read_symbolic_link.php b/src/Psl/Filesystem/read_symbolic_link.php
new file mode 100644
index 00000000..da7e0588
--- /dev/null
+++ b/src/Psl/Filesystem/read_symbolic_link.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+use Psl\Internal;
+use Psl\Str;
+
+use function readlink;
+
+/**
+ * Returns the target of a symbolic link.
+ *
+ * @throws Psl\Exception\InvariantViolationException If the link specified by
+ *  $symbolic_link does not exist, or is not a symbolic link.
+ * @throws Exception\RuntimeException If unable to retrieve the target
+ *  of $symbolic_link.
+ */
+function read_symbolic_link(string $symbolic_link): string
+{
+    Psl\invariant(exists($symbolic_link), '$symbolic_link does not exists.');
+    Psl\invariant(is_symbolic_link($symbolic_link), '$symbolic_link is not a symbolic link.');
+
+    [$result, $message] = Internal\box(
+        /**
+         * @return false|string
+         */
+        static fn() => readlink($symbolic_link)
+    );
+
+    // @codeCoverageIgnoreStart
+    if (false === $result) {
+        throw new Exception\RuntimeException(Str\format(
+            'Failed to retrieve the target of symbolic link "%s": %s',
+            $symbolic_link,
+            $message ?? 'internal error'
+        ));
+    }
+    // @codeCoverageIgnoreEnd
+
+    return $result;
+}
diff --git a/src/Psl/Filesystem/write_file.php b/src/Psl/Filesystem/write_file.php
new file mode 100644
index 00000000..75bd5ace
--- /dev/null
+++ b/src/Psl/Filesystem/write_file.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Filesystem;
+
+use Psl;
+
+/**
+ * Write $content to $file.
+ *
+ * If $file does not exist, it will be created.
+ *
+ * @throws Psl\Exception\InvariantViolationException If the file specified by
+ *  $file is a directory, or is not writeable.
+ * @throws Exception\RuntimeException In case of an error.
+ */
+function write_file(string $file, string $content): void
+{
+    Internal\write_file($file, $content, false);
+}
diff --git a/src/Psl/Internal/Loader.php b/src/Psl/Internal/Loader.php
index 155ac93f..7eb37748 100644
--- a/src/Psl/Internal/Loader.php
+++ b/src/Psl/Internal/Loader.php
@@ -48,6 +48,7 @@ final class Loader
         'Psl\Str\ALPHABET_ALPHANUMERIC',
         'Psl\Password\DEFAULT_ALGORITHM',
         'Psl\Password\BCRYPT_ALGORITHM',
+        'Psl\Filesystem\SEPARATOR',
     ];
 
     public const FUNCTIONS = [
@@ -141,6 +142,7 @@ final class Loader
         'Psl\Internal\boolean',
         'Psl\Internal\type',
         'Psl\Internal\suppress',
+        'Psl\Internal\box',
         'Psl\Internal\validate_offset',
         'Psl\Internal\validate_offset_lower_bound',
         'Psl\Internal\internal_encoding',
@@ -465,6 +467,43 @@ final class Loader
         'Psl\Html\decode',
         'Psl\Html\decode_special_characters',
         'Psl\Html\strip_tags',
+        'Psl\Filesystem\Internal\write_file',
+        'Psl\Filesystem\change_group',
+        'Psl\Filesystem\change_owner',
+        'Psl\Filesystem\change_permissions',
+        'Psl\Filesystem\copy',
+        'Psl\Filesystem\create_directory',
+        'Psl\Filesystem\create_file',
+        'Psl\Filesystem\delete_directory',
+        'Psl\Filesystem\delete_file',
+        'Psl\Filesystem\exists',
+        'Psl\Filesystem\file_size',
+        'Psl\Filesystem\get_group',
+        'Psl\Filesystem\get_owner',
+        'Psl\Filesystem\get_permissions',
+        'Psl\Filesystem\get_basename',
+        'Psl\Filesystem\get_directory',
+        'Psl\Filesystem\get_extension',
+        'Psl\Filesystem\get_filename',
+        'Psl\Filesystem\is_directory',
+        'Psl\Filesystem\is_file',
+        'Psl\Filesystem\is_symbolic_link',
+        'Psl\Filesystem\is_readable',
+        'Psl\Filesystem\is_writable',
+        'Psl\Filesystem\canonicalize',
+        'Psl\Filesystem\is_executable',
+        'Psl\Filesystem\read_directory',
+        'Psl\Filesystem\read_file',
+        'Psl\Filesystem\read_symbolic_link',
+        'Psl\Filesystem\append_file',
+        'Psl\Filesystem\write_file',
+        'Psl\Filesystem\create_temporary_file',
+        'Psl\Filesystem\create_hard_link',
+        'Psl\Filesystem\create_symbolic_link',
+        'Psl\Filesystem\get_access_time',
+        'Psl\Filesystem\get_change_time',
+        'Psl\Filesystem\get_modification_time',
+        'Psl\Filesystem\get_inode',
     ];
 
     public const INTERFACES = [
@@ -490,7 +529,9 @@ final class Loader
         'Psl\Type\TypeInterface',
         'Psl\Type\Exception\ExceptionInterface',
         'Psl\Regex\Exception\ExceptionInterface',
+        'Psl\SecureRandom\Exception\ExceptionInterface',
         'Psl\Shell\Exception\ExceptionInterface',
+        'Psl\Filesystem\Exception\ExceptionInterface',
     ];
 
     public const TRAITS = [];
@@ -542,6 +583,7 @@ final class Loader
         'Psl\Hash\Context',
         'Psl\Encoding\Exception\IncorrectPaddingException',
         'Psl\Encoding\Exception\RangeException',
+        'Psl\SecureRandom\Exception\InsufficientEntropyException',
         'Psl\Regex\Exception\InvalidPatternException',
         'Psl\Regex\Exception\RuntimeException',
         'Psl\Shell\Exception\FailedExecutionException',
@@ -549,6 +591,7 @@ final class Loader
         'Psl\Shell\Exception\PossibleAttackException',
         'Psl\Math\Exception\ArithmeticException',
         'Psl\Math\Exception\DivisionByZeroException',
+        'Psl\Filesystem\Exception\RuntimeException',
     ];
 
     private const TYPE_CONSTANTS = 1;
diff --git a/src/Psl/Internal/box.php b/src/Psl/Internal/box.php
new file mode 100644
index 00000000..2c2933c2
--- /dev/null
+++ b/src/Psl/Internal/box.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Internal;
+
+use Psl\Str;
+
+use function restore_error_handler;
+use function set_error_handler;
+
+/**
+ * @psalm-template T
+ *
+ * @psalm-param (callable(): T) $fun
+ *
+ * @psalm-return array{0: T, 1: ?string}
+ *
+ * @internal
+ *
+ * @psalm-suppress MissingThrowsDocblock
+ */
+function box(callable $fun): array
+{
+    $last_message = null;
+    /** @psalm-suppress InvalidArgument */
+    set_error_handler(static function (int $_type, string $message) use (&$last_message) {
+        $last_message = $message;
+    });
+
+    /**
+     * @var string|null $last_message
+     */
+
+    if (null !== $last_message && Str\contains($last_message, '): ')) {
+        $last_message = Str\after(
+            Str\lowercase($last_message),
+            // how i feel toward PHP error handling:
+            '): '
+        );
+    }
+
+    try {
+        $value = $fun();
+
+        /** @var array{0: T, 1: ?string} $result */
+        $result = [$value, $last_message];
+
+        return $result;
+    } finally {
+        restore_error_handler();
+    }
+}
diff --git a/src/Psl/Math/maxva.php b/src/Psl/Math/maxva.php
index 7fcae5d3..94917e39 100644
--- a/src/Psl/Math/maxva.php
+++ b/src/Psl/Math/maxva.php
@@ -13,7 +13,8 @@
  * @psalm-param T $second
  * @psalm-param T ...$rest
  *
- * @psalm-return T
+ * @return int|float
+ * @psalm-return (T is int ? int : float)
  *
  * @psalm-pure
  */
diff --git a/tests/.cache/.gitignore b/tests/.cache/.gitignore
new file mode 100644
index 00000000..c96a04f0
--- /dev/null
+++ b/tests/.cache/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
\ No newline at end of file
diff --git a/tests/Psl/Filesystem/AbstractFilesystemTest.php b/tests/Psl/Filesystem/AbstractFilesystemTest.php
new file mode 100644
index 00000000..df2b1c67
--- /dev/null
+++ b/tests/Psl/Filesystem/AbstractFilesystemTest.php
@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Filesystem;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Env;
+use Psl\Filesystem;
+use Psl\Str;
+use Psl\Type;
+
+use const PHP_OS_FAMILY;
+
+abstract class AbstractFilesystemTest extends TestCase
+{
+    protected string $function;
+    protected string $cacheDirectory;
+    protected string $directory;
+    private int $directoryPermissions;
+
+    protected function setUp(): void
+    {
+        $this->cacheDirectory = Type\string()->assert(Filesystem\canonicalize(Str\join([
+            __DIR__, '..', '..', '.cache'
+        ], Filesystem\SEPARATOR)));
+
+        $this->directory = Str\join([$this->cacheDirectory, $this->function], Filesystem\SEPARATOR);
+        Filesystem\create_directory($this->directory);
+        $this->directoryPermissions = Filesystem\get_permissions($this->directory) & 0777;
+
+        static::assertTrue(Filesystem\exists($this->directory));
+        static::assertTrue(Filesystem\is_directory($this->directory));
+    }
+
+    protected function tearDown(): void
+    {
+        Filesystem\change_permissions($this->directory, $this->directoryPermissions);
+        Filesystem\delete_directory($this->directory, true);
+
+        static::assertFalse(Filesystem\is_directory($this->directory));
+    }
+
+    protected static function runOnlyOnLinux(): void
+    {
+        if ('Linux' !== PHP_OS_FAMILY) {
+            static::markTestSkipped('Test can only be executed on linux.');
+        }
+    }
+
+    protected static function runOnlyUsingRoot(): void
+    {
+        $user = Env\get_var('USER');
+        if (null === $user || 'root' === $user) {
+            return;
+        }
+
+        static::markTestSkipped('Test can only be executed by a superuser.');
+    }
+}
diff --git a/tests/Psl/Filesystem/CopyTest.php b/tests/Psl/Filesystem/CopyTest.php
new file mode 100644
index 00000000..4a3b6689
--- /dev/null
+++ b/tests/Psl/Filesystem/CopyTest.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Filesystem;
+
+use Psl\Filesystem;
+use Psl\Str;
+
+final class CopyTest extends AbstractFilesystemTest
+{
+    protected string $function = 'copy';
+
+    public function testCopy(): void
+    {
+        $text_file = Str\join([$this->directory, 'hello.txt'], Filesystem\SEPARATOR);
+        $markdown_file = Str\join([$this->directory, 'hello.md'], Filesystem\SEPARATOR);
+
+        Filesystem\write_file($text_file, 'Hello, World!');
+        Filesystem\copy($text_file, $markdown_file);
+
+        static::assertSame('Hello, World!', Filesystem\read_file($markdown_file));
+    }
+
+    public function testCopyOverwrite(): void
+    {
+        $text_file = Str\join([$this->directory, 'hello.txt'], Filesystem\SEPARATOR);
+        $markdown_file = Str\join([$this->directory, 'hello.md'], Filesystem\SEPARATOR);
+
+        Filesystem\write_file($text_file, 'Hello, World!');
+        Filesystem\write_file($markdown_file, '# Hello, World!');
+        Filesystem\copy($text_file, $markdown_file);
+
+        static::assertSame('Hello, World!', Filesystem\read_file($text_file));
+        static::assertSame('# Hello, World!', Filesystem\read_file($markdown_file));
+
+        Filesystem\copy($text_file, $markdown_file, true);
+
+        static::assertSame('Hello, World!', Filesystem\read_file($text_file));
+        static::assertSame('Hello, World!', Filesystem\read_file($markdown_file));
+    }
+
+    public function testCopyExecutableBits(): void
+    {
+        $shell_file = Str\join([$this->directory, 'hello.sh'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($shell_file);
+        Filesystem\change_permissions($shell_file, 0557);
+
+        static::assertTrue(Filesystem\is_executable($shell_file));
+
+        $shell_file_copy = Str\join([$this->directory, 'hey.sh'], Filesystem\SEPARATOR);
+
+        Filesystem\copy($shell_file, $shell_file_copy);
+
+        static::assertTrue(Filesystem\is_executable($shell_file_copy));
+    }
+}
diff --git a/tests/Psl/Filesystem/FileTest.php b/tests/Psl/Filesystem/FileTest.php
new file mode 100644
index 00000000..93909d07
--- /dev/null
+++ b/tests/Psl/Filesystem/FileTest.php
@@ -0,0 +1,179 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Filesystem;
+
+use Psl\Env;
+use Psl\Exception\InvariantViolationException;
+use Psl\Filesystem;
+use Psl\Str;
+
+use function time;
+
+final class FileTest extends AbstractFilesystemTest
+{
+    protected string $function = 'file';
+
+    public function testTemporaryFile(): void
+    {
+        $file = Filesystem\create_temporary_file($this->directory);
+
+        static::assertTrue(Filesystem\is_file($file));
+        static::assertSame($this->directory, Filesystem\get_directory($file));
+    }
+
+    public function testTemporaryFileWithPrefix(): void
+    {
+        $file = Filesystem\create_temporary_file($this->directory, 'foo');
+
+        static::assertTrue(Filesystem\is_file($file));
+        static::assertSame($this->directory, Filesystem\get_directory($file));
+        static::assertStringContainsString('foo', Filesystem\get_filename($file));
+    }
+
+    public function testTemporaryFileIsCreateInTempDirectoryByDefault(): void
+    {
+        $file = Filesystem\create_temporary_file();
+
+        static::assertSame(Env\temp_dir(), Filesystem\get_directory($file));
+    }
+
+    public function testTemporaryFileThrowsForNonExistingDirectory(): void
+    {
+        $this->expectException(InvariantViolationException::class);
+        $this->expectExceptionMessage('$directory is not a directory.');
+
+        Filesystem\create_temporary_file(__FILE__);
+    }
+
+    public function testTemporaryFileThrowsForPrefixWithSeparator(): void
+    {
+        $prefix = Str\join(['a', 'b'], Filesystem\SEPARATOR);
+
+        $this->expectException(InvariantViolationException::class);
+        $this->expectExceptionMessage(
+            '$prefix should not contain a directory separator ( "' . Filesystem\SEPARATOR . '" ).'
+        );
+
+        Filesystem\create_temporary_file($this->directory, $prefix);
+    }
+
+    public function testCreateFileAndParentDirectory(): void
+    {
+        $directory = Str\join([$this->directory, 'foo'], Filesystem\SEPARATOR);
+        $file = Str\join([$directory, 'write.txt'], Filesystem\SEPARATOR);
+
+        static::assertFalse(Filesystem\is_directory($directory));
+
+        Filesystem\create_file($file);
+
+        static::assertTrue(Filesystem\is_directory($directory));
+        static::assertTrue(Filesystem\is_file($file));
+    }
+
+    public function testWriteFile(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+
+        static::assertFileDoesNotExist($file);
+
+        Filesystem\write_file($file, 'Hello!');
+
+        static::assertFileExists($file);
+
+        static::assertStringEqualsFile($file, 'Hello!');
+
+        Filesystem\write_file($file, 'Hello');
+
+        static::assertStringEqualsFile($file, 'Hello');
+
+        Filesystem\append_file($file, ', World!');
+
+        static::assertStringEqualsFile($file, 'Hello, World!');
+
+        Filesystem\delete_file($file);
+    }
+
+    public function testWriteFileThrowsForDirectories(): void
+    {
+        $this->expectException(InvariantViolationException::class);
+        $this->expectExceptionMessage('$file is not a file.');
+
+        Filesystem\write_file($this->directory, 'hello');
+    }
+
+    public function testWriteFileThrowsForNonWritableFiles(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+        Filesystem\create_file($file);
+        Filesystem\change_permissions($file, 0111);
+
+        $this->expectException(InvariantViolationException::class);
+        $this->expectExceptionMessage('$file is not writeable.');
+
+        Filesystem\write_file($file, 'hello');
+    }
+
+    public function testReadFile(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+        Filesystem\write_file($file, 'PHP Standard Library');
+        Filesystem\append_file($file, ' - a modern, consistent, centralized');
+        Filesystem\append_file($file, ' well-typed set of APIs for PHP programmers.');
+
+        $content = Filesystem\read_file($file, 0, 20);
+
+        static::assertSame('PHP Standard Library', $content);
+
+        $content = Filesystem\read_file($file, 84, 16);
+
+        static::assertSame('PHP programmers.', $content);
+    }
+
+    public function testFileModificationAndAccessTime(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+
+        $modification_time = time() - 3600;
+        $access_time = time() - 1800;
+
+        Filesystem\create_file($file, $modification_time, $access_time);
+
+        static::assertSame($modification_time, Filesystem\get_modification_time($file));
+        static::assertSame($access_time, Filesystem\get_access_time($file));
+    }
+
+    public function testFileAccessTime(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+
+        $access_time = time() - 1800;
+
+        Filesystem\create_file($file, null, $access_time);
+
+        static::assertSame($access_time, Filesystem\get_modification_time($file));
+        static::assertSame($access_time, Filesystem\get_access_time($file));
+    }
+
+    public function testFileModificationTime(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+
+        $modification_time = time() - 3600;
+
+        Filesystem\create_file($file, $modification_time);
+
+        static::assertSame($modification_time, Filesystem\get_modification_time($file));
+        static::assertSame($modification_time, Filesystem\get_access_time($file));
+    }
+
+    public function testFileChangeTime(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($file);
+
+        static::assertEqualsWithDelta(time(), Filesystem\get_change_time($file), 1.0);
+    }
+}
diff --git a/tests/Psl/Filesystem/LinkTest.php b/tests/Psl/Filesystem/LinkTest.php
new file mode 100644
index 00000000..7179160c
--- /dev/null
+++ b/tests/Psl/Filesystem/LinkTest.php
@@ -0,0 +1,187 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Filesystem;
+
+use Psl\Filesystem;
+use Psl\Str;
+
+final class LinkTest extends AbstractFilesystemTest
+{
+    protected string $function = 'link';
+
+    public function testSymbolicLink(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+        $symlink = Str\join([$this->directory, 'symlink.txt'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($file);
+
+        Filesystem\create_symbolic_link($file, $symlink);
+
+        static::assertTrue(Filesystem\exists($symlink));
+        static::assertTrue(Filesystem\is_symbolic_link($symlink));
+
+        static::assertSame($file, Filesystem\read_symbolic_link($symlink));
+    }
+
+    public function testSymbolicLinkAlreadyExists(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+        $symlink = Str\join([$this->directory, 'symlink.txt'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($file);
+
+        Filesystem\create_symbolic_link($file, $symlink);
+
+        static::assertTrue(Filesystem\exists($symlink));
+        static::assertTrue(Filesystem\is_symbolic_link($symlink));
+
+        static::assertSame($file, Filesystem\read_symbolic_link($symlink));
+
+        Filesystem\create_symbolic_link($file, $symlink);
+
+        static::assertTrue(Filesystem\exists($symlink));
+        static::assertTrue(Filesystem\is_symbolic_link($symlink));
+
+        static::assertSame($file, Filesystem\read_symbolic_link($symlink));
+    }
+
+    public function testSymbolicLinkOverwrite(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+        $symbolic_link = Str\join([$this->directory, 'symbolic_link.txt'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($file);
+        Filesystem\create_file($symbolic_link);
+
+        static::assertFalse(Filesystem\is_symbolic_link($symbolic_link));
+
+        Filesystem\create_symbolic_link($file, $symbolic_link);
+
+        static::assertTrue(Filesystem\is_symbolic_link($symbolic_link));
+        static::assertSame($file, Filesystem\read_symbolic_link($symbolic_link));
+
+        $file = Str\join([$this->directory, 'foo', 'bar'], Filesystem\SEPARATOR);
+        $symbolic_link = Str\join([$this->directory, 'foo', 'baz'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($file);
+        Filesystem\create_directory($symbolic_link);
+
+        static::assertFalse(Filesystem\is_symbolic_link($symbolic_link));
+
+        Filesystem\create_symbolic_link($file, $symbolic_link);
+
+        static::assertTrue(Filesystem\is_symbolic_link($symbolic_link));
+        static::assertSame($file, Filesystem\read_symbolic_link($symbolic_link));
+    }
+
+    public function testSymbolicLinkCreatesDestinationsDirectory(): void
+    {
+        self::runOnlyOnLinux();
+
+        $directory = Str\join([$this->directory, 'foo'], Filesystem\SEPARATOR);
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+        $symbolic_link = Str\join([$directory, 'symbolic.txt'], Filesystem\SEPARATOR);
+
+        static::assertFalse(Filesystem\is_directory($directory));
+
+        Filesystem\create_file($file);
+        Filesystem\create_symbolic_link($file, $symbolic_link);
+
+        static::assertTrue(Filesystem\is_directory($directory));
+    }
+
+    public function testHardLink(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+        $hardlink = Str\join([$this->directory, 'hardlink.txt'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($file);
+
+        Filesystem\create_hard_link($file, $hardlink);
+
+        static::assertTrue(Filesystem\exists($hardlink));
+        static::assertFalse(Filesystem\is_symbolic_link($hardlink));
+
+        static::assertSame(Filesystem\get_inode($file), Filesystem\get_inode($hardlink));
+    }
+
+    public function testHardLinkAlreadyExists(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+        $hardlink = Str\join([$this->directory, 'hardlink.txt'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($file);
+
+        Filesystem\create_hard_link($file, $hardlink);
+
+        static::assertTrue(Filesystem\exists($hardlink));
+        static::assertFalse(Filesystem\is_symbolic_link($hardlink));
+
+        static::assertSame(Filesystem\get_inode($file), Filesystem\get_inode($hardlink));
+
+        Filesystem\create_hard_link($file, $hardlink);
+
+        static::assertSame(Filesystem\get_inode($file), Filesystem\get_inode($hardlink));
+    }
+
+    public function testHardLinkCreatesDestinationDirectory(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+        $destination_directory = Str\join([$this->directory, 'foo'], Filesystem\SEPARATOR);
+        $hardlink = Str\join([$destination_directory, 'hardlink.txt'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($file);
+
+        static::assertFalse(Filesystem\is_directory($destination_directory));
+
+        Filesystem\create_hard_link($file, $hardlink);
+
+        static::assertTrue(Filesystem\is_directory($destination_directory));
+        static::assertTrue(Filesystem\exists($hardlink));
+        static::assertFalse(Filesystem\is_symbolic_link($hardlink));
+
+        static::assertSame(Filesystem\get_inode($file), Filesystem\get_inode($hardlink));
+    }
+
+    public function testHardLinkOverwrite(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+        $hardlink = Str\join([$this->directory, 'hardlink.txt'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($file);
+        Filesystem\create_file($hardlink);
+
+        static::assertNotSame(Filesystem\get_inode($file), Filesystem\get_inode($hardlink));
+
+        Filesystem\create_hard_link($file, $hardlink);
+
+        static::assertSame(Filesystem\get_inode($file), Filesystem\get_inode($hardlink));
+
+        $file = Str\join([$this->directory, 'foo', 'bar'], Filesystem\SEPARATOR);
+        $hardlink = Str\join([$this->directory, 'foo', 'baz'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($file);
+        Filesystem\create_directory($hardlink);
+
+        static::assertNotSame(Filesystem\get_inode($file), Filesystem\get_inode($hardlink));
+
+        Filesystem\create_hard_link($file, $hardlink);
+
+        static::assertSame(Filesystem\get_inode($file), Filesystem\get_inode($hardlink));
+    }
+
+    public function testHardLinkCreatesDestinationsDirectory(): void
+    {
+        $file = Str\join([$this->directory, 'write.txt'], Filesystem\SEPARATOR);
+        $hardlink = Str\join([$this->directory, 'baz', 'hardlink.txt'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($file);
+
+        Filesystem\create_hard_link($file, $hardlink);
+
+        static::assertSame(Filesystem\get_inode($file), Filesystem\get_inode($hardlink));
+    }
+}
diff --git a/tests/Psl/Filesystem/PathTest.php b/tests/Psl/Filesystem/PathTest.php
new file mode 100644
index 00000000..d47a31aa
--- /dev/null
+++ b/tests/Psl/Filesystem/PathTest.php
@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Filesystem;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Exception\InvariantViolationException;
+use Psl\Filesystem;
+
+final class PathTest extends TestCase
+{
+    /**
+     * @dataProvider providePathInformationData
+     */
+    public function testPathInformation(
+        string $path,
+        string $directory,
+        string $basename,
+        string $filename,
+        ?string $extension
+    ): void {
+        static::assertSame($directory, Filesystem\get_directory($path));
+        static::assertSame($basename, Filesystem\get_basename($path));
+        static::assertSame($filename, Filesystem\get_filename($path));
+        static::assertSame($extension, Filesystem\get_extension($path));
+    }
+
+    public function providePathInformationData(): iterable
+    {
+        yield [
+            '/home/azjezz/Projects/psl/src/bootstrap.php',
+            '/home/azjezz/Projects/psl/src',
+            'bootstrap.php',
+            'bootstrap',
+            'php'
+        ];
+
+        yield [
+            '/home/azjezz/Projects/psl/src/Psl',
+            '/home/azjezz/Projects/psl/src',
+            'Psl',
+            'Psl',
+            null
+        ];
+    }
+
+    public function testGetBasenameWithSuffix(): void
+    {
+        static::assertSame('bootstrap.p', Filesystem\get_basename('/home/azjezz/Projects/psl/src/bootstrap.php', 'hp'));
+    }
+
+    public function testGetDirectoryWithMultipleLevels(): void
+    {
+        static::assertSame(
+            '/home/azjezz/Projects',
+            Filesystem\get_directory('/home/azjezz/Projects/psl/src/Psl', 3)
+        );
+    }
+
+    public function testGetDirectoryWithNegativeLevelThrows(): void
+    {
+        $this->expectException(InvariantViolationException::class);
+        $this->expectExceptionMessage('$levels must be a positive integer, -3 given.');
+
+        Filesystem\get_directory('/home/azjezz/Projects/psl/src/Psl', -3);
+    }
+}
diff --git a/tests/Psl/Filesystem/PermissionsTest.php b/tests/Psl/Filesystem/PermissionsTest.php
new file mode 100644
index 00000000..8162cc0d
--- /dev/null
+++ b/tests/Psl/Filesystem/PermissionsTest.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Filesystem;
+
+use Psl\Filesystem;
+use Psl\Str;
+
+final class PermissionsTest extends AbstractFilesystemTest
+{
+    protected string $function = 'permissions';
+
+    public function testChangePermissions(): void
+    {
+        $filename = Str\join([$this->directory, 'foo.txt'], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($filename);
+
+        $permissions = Filesystem\get_permissions($filename) & 0777;
+
+        try {
+            Filesystem\change_permissions($filename, 0444);
+
+            static::assertTrue(Filesystem\is_readable($filename));
+            static::assertFalse(Filesystem\is_writable($filename));
+            static::assertFalse(Filesystem\is_executable($filename));
+
+            Filesystem\change_permissions($filename, 0222);
+
+            static::assertTrue(Filesystem\is_writable($filename));
+            static::assertFalse(Filesystem\is_readable($filename));
+            static::assertFalse(Filesystem\is_executable($filename));
+
+            Filesystem\change_permissions($filename, 0111);
+
+            static::assertTrue(Filesystem\is_executable($filename));
+            static::assertFalse(Filesystem\is_writable($filename));
+            static::assertFalse(Filesystem\is_readable($filename));
+
+            Filesystem\change_permissions($filename, 0666);
+
+            static::assertTrue(Filesystem\is_writable($filename));
+            static::assertTrue(Filesystem\is_readable($filename));
+            static::assertFalse(Filesystem\is_executable($filename));
+
+            Filesystem\change_permissions($filename, 0777);
+
+            static::assertTrue(Filesystem\is_writable($filename));
+            static::assertTrue(Filesystem\is_readable($filename));
+            static::assertTrue(Filesystem\is_executable($filename));
+        } finally {
+            Filesystem\change_permissions($filename, $permissions);
+        }
+    }
+}
diff --git a/tests/Psl/Filesystem/ReadDirectoryTest.php b/tests/Psl/Filesystem/ReadDirectoryTest.php
new file mode 100644
index 00000000..f9842920
--- /dev/null
+++ b/tests/Psl/Filesystem/ReadDirectoryTest.php
@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Filesystem;
+
+use Psl\Env;
+use Psl\Exception\InvariantViolationException;
+use Psl\Filesystem;
+use Psl\Str;
+use Psl\Vec;
+
+final class ReadDirectoryTest extends AbstractFilesystemTest
+{
+    protected string $function = 'read_directory';
+
+    public function testReadDirectory(): void
+    {
+        Filesystem\create_file(Str\join([
+            $this->directory, 'hello.txt'
+        ], Filesystem\SEPARATOR));
+
+        Filesystem\create_directory(Str\join([
+            $this->directory, 'foo'
+        ], Filesystem\SEPARATOR));
+
+        $children = Filesystem\read_directory($this->directory);
+
+        static::assertCount(2, $children);
+        static::assertSame([
+            Str\join([$this->directory, 'foo'], Filesystem\SEPARATOR),
+            Str\join([$this->directory, 'hello.txt'], Filesystem\SEPARATOR),
+        ], Vec\sort($children));
+    }
+
+    public function testReadDirectoryThrowsIfDirectoryDoesNotExist(): void
+    {
+        $this->expectException(InvariantViolationException::class);
+        $this->expectExceptionMessage('$directory does not exists.');
+
+        Filesystem\read_directory(Env\temp_dir() . '/foo-bar-baz');
+    }
+
+    public function testReadDirectoryThrowsIfNotDirectory(): void
+    {
+        $filename = Str\join([
+            $this->directory, 'hello.txt'
+        ], Filesystem\SEPARATOR);
+
+        Filesystem\create_file($filename);
+
+        $this->expectException(InvariantViolationException::class);
+        $this->expectExceptionMessage('$directory is not a directory.');
+
+        Filesystem\read_directory($filename);
+    }
+
+    public function testReadDirectoryThrowsIfNotReadable(): void
+    {
+        Filesystem\change_permissions($this->directory, 0077);
+
+        $this->expectException(InvariantViolationException::class);
+        $this->expectExceptionMessage('$directory is not readable.');
+
+        try {
+            Filesystem\read_directory($this->directory);
+        } finally {
+            // restore $this->directory permissions, otherwise we won't
+            // be able to delete it.
+            Filesystem\change_permissions($this->directory, 0777);
+        }
+    }
+}