feat: Introduce new tmp methods

README.md

@@ -4,9 +4,120 @@ This is a tiny wrapper around the [Symfony filesystem]. It provides a `FileSyste
 a few more utilities.
 
 
+## New methods
+
+```php
+interface FileSystem extends SymfonyFileSystem
+{
+    /**
+     * Replaces the path directory separator with the system one.
+     *
+     * For example, on Windows:
+     * 'C:/path/to/file' => 'C:\path\to\file',
+     */
+    public function escapePath(string $path): string;
+
+    /**
+     * Returns the absolute path, but the path will not be normalized.
+     *
+     * For example, `::realpath('C:\Users\Name\file.txt')` on Windows will
+     * return "C:\Users\Name\file.txt" (backslashes).
+     *
+     * @see https://php.net/manual/en/function.realpath.php
+     *
+     * @throws IOException When the file or symlink target does not exist.
+     */
+    public function realPath(string $file): string;
+
+    /**
+     * Returns the absolute normalized path.
+     *
+     * For example, `::realpath('C:\Users\Name\file.txt')` on Windows will
+     * return "C:/Users/Name/file.txt".
+     *
+     * @see https://php.net/manual/en/function.realpath.php
+     *
+     * @throws IOException When the file or symlink target does not exist.
+     */
+    public function normalizedRealPath(string $file): string;
+
+    /**
+     * Creates a temporary file with support for custom stream wrappers. Same as tempnam(),
+     * but targets the system default temporary directory by default and has a more consistent
+     * name with tmpDir.
+     *
+     * For example:
+     *
+     *  ```php
+     *  tmpFile('build')
+     *
+     *  // on OSX
+     *  => '/var/folders/p3/lkw0cgjj2fq0656q_9rd0mk80000gn/T/build8d9e0f1a'
+     *  // on Windows
+     *  => C:\Windows\Temp\build8d9e0f1a.tmp
+     *  ```
+     *
+     * @param string $prefix          The prefix of the generated temporary file name.
+     * @param string $suffix          The suffix of the generated temporary file name.
+     * @param string $targetDirectory The directory where to create the temporary directory.
+     *                                Defaults to the system default temporary directory.
+     *
+     * @return string The new temporary file pathname.
+     *
+     * @throws IOException
+     *
+     * @see tempnam()
+     * @see SymfonyFileSystem::tempnam()
+     * @see self::tmpDir()
+     */
+    public function tmpFile(string $prefix, string $suffix = '', ?string $targetDirectory = null): string;
+
+    /**
+     * Creates a temporary directory with support for custom stream wrappers. Similar to tempnam()
+     * but creates a directory instead of a file.
+     *
+     * For example:
+     *
+     * ```php
+     * tmpDir('build')
+     *
+     * // on OSX
+     * => '/var/folders/p3/lkw0cgjj2fq0656q_9rd0mk80000gn/T/build8d9e0f1a'
+     * // on Windows
+     * => C:\Windows\Temp\build8d9e0f1a.tmp
+     * ```
+     *
+     * @param string|null $prefix          The prefix of the generated temporary directory name.
+     * @param string      $targetDirectory The directory where to create the temporary directory.
+     *                                     Defaults to the system default temporary directory.
+     *
+     * @throws IOException
+     *
+     * @return string The new temporary directory pathname.
+     *
+     * @see tempnam()
+     */
+    public function tmpDir(string $prefix, ?string $targetDirectory = null): string;
+
+    /**
+     * Tells whether a file exists and is readable.
+     *
+     * @throws IOException When Window's path is longer than 258 characters
+     */
+    public function isReadable(string $filename): bool;
+
+    public function isReadableFile(string $filename): bool;
+
+    public function isReadableDirectory(string $filename): bool;
+
+    public function createFinder(): Finder;
+}
+```
+
+
 ## FileSystemTestCase
 
-An example of PHPUnit test:
+An example of a PHPUnit test:
 
 ```php
 

infection.json.dist

@@ -18,6 +18,8 @@
             // Too dangerous to mutate outside a container
             "Fidry\\FileSystem\\NativeFileSystem::makeTmpDir",
             "Fidry\\FileSystem\\NativeFileSystem::getNamespacedTmpDir",
+            "Fidry\\FileSystem\\NativeFileSystem::tmpDir",
+            "Fidry\\FileSystem\\NativeFileSystem::tmpFile",
             "Fidry\\FileSystem\\Test\\FileSystemTestCase::tearDown"
         ],
 

src/FS.php

@@ -253,6 +253,9 @@ public static function mirror(string $originDir, string $targetDir, ?Traversable
     }
 
     /**
+     * @deprecated Deprecated since 2.0. Use `Path::isAbsolute()` instead.
+     * @see Path::isAbsolute()
+     *
      * Returns whether the file path is an absolute path.
      */
     public static function isAbsolutePath(string $file): bool
@@ -299,6 +302,9 @@ public static function appendToFile(string $filename, $content/* , bool $lock =
     }
 
     /**
+     * @deprecated Deprecated since 2.0. Use `Path::isRelative()` instead. Will be removed in 3.0.
+     * @see Path::isRelative())
+     *
      * Returns whether a path is relative.
      *
      * @param string $path a path string
@@ -317,6 +323,9 @@ public static function escapePath(string $path): string
     }
 
     /**
+     * @deprecated Use the `::readFile()` method. Deprecated since 2.0 and it will be removed in 3.0.
+     * @see SymfonyFileSystem::readFile()
+     *
      * Gets the contents of a file.
      *
      * @param string $file File path
@@ -341,6 +350,9 @@ public static function readFile(string $file): string
     }
 
     /**
+     * @deprecated Use the `::tmpDir()` method. Deprecated since 2.0 and it will be removed in 3.0.
+     * @see self::tmpDir()
+     *
      * Creates a temporary directory.
      *
      * @param string $namespace the directory path in the system's temporary directory
@@ -354,6 +366,72 @@ public static function makeTmpDir(string $namespace, string $className): string
     }
 
     /**
+     * Creates a temporary file with support for custom stream wrappers. Same as tempnam(),
+     * but targets the system default temporary directory by default and has a more consistent
+     * name with tmpDir.
+     *
+     * For example:
+     *
+     *  ```php
+     *  tmpFile('build')
+     *
+     *  // on OSX
+     *  => '/var/folders/p3/lkw0cgjj2fq0656q_9rd0mk80000gn/T/build8d9e0f1a'
+     *  // on Windows
+     *  => C:\Windows\Temp\build8d9e0f1a.tmp
+     *  ```
+     *
+     * @param string $prefix          The prefix of the generated temporary file name.
+     * @param string $suffix          The suffix of the generated temporary file name.
+     * @param string $targetDirectory The directory where to create the temporary directory.
+     *                                Defaults to the system default temporary directory.
+     *
+     * @throws IOException
+     * @return string      The new temporary file pathname.
+     *
+     * @see tempnam()
+     * @see SymfonyFileSystem::tempnam()
+     * @see self::tmpDir()
+     */
+    public function tmpFile(string $prefix, string $suffix = '', ?string $targetDirectory = null): string
+    {
+        return self::getInstance()->tmpFile(...func_get_args());
+    }
+
+    /**
+     * Creates a temporary directory with support for custom stream wrappers. Similar to tempnam()
+     * but creates a directory instead of a file.
+     *
+     * For example:
+     *
+     * ```php
+     * tmpDir('build')
+     *
+     * // on OSX
+     * => '/var/folders/p3/lkw0cgjj2fq0656q_9rd0mk80000gn/T/build8d9e0f1a'
+     * // on Windows
+     * => C:\Windows\Temp\build8d9e0f1a.tmp
+     * ```
+     *
+     * @param string|null $prefix          The prefix of the generated temporary directory name.
+     * @param string      $targetDirectory The directory where to create the temporary directory.
+     *                                     Defaults to the system default temporary directory.
+     *
+     * @throws IOException
+     *
+     * @return string The new temporary directory pathname.
+     *
+     * @see tempnam()
+     */
+    public function tmpDir(string $prefix, ?string $targetDirectory = null): string
+    {
+        return self::getInstance()->tmpDir(...func_get_args());
+    }
+
+    /**
+     * @deprecated Deprecated since 2.0. Use `Path::isRelative()` instead. Will be removed in 3.0.
+     *             Using a namespaced dir is an antipattern with parallel testing.
+     *
      * Gets a namespaced temporary directory.
      *
      * @param string $namespace the directory path in the system's temporary directory

src/FakeFileSystem.php

@@ -199,4 +199,17 @@ public function normalizedRealPath(string $file): string
     {
         throw new DomainException('Unexpected call.');
     }
+
+    public function tmpFile(
+        string $prefix,
+        string $suffix = '',
+        ?string $targetDirectory = null,
+    ): string {
+        throw new DomainException('Unexpected call.');
+    }
+
+    public function tmpDir(string $prefix, ?string $targetDirectory = null): string
+    {
+        throw new DomainException('Unexpected call.');
+    }
 }

src/FileSystem.php

@@ -48,6 +48,7 @@
 
 use Symfony\Component\Filesystem\Exception\IOException;
 use Symfony\Component\Finder\Finder;
+use function tempnam;
 
 interface FileSystem extends SymfonyFileSystem
 {
@@ -57,6 +58,12 @@ interface FileSystem extends SymfonyFileSystem
      */
     public function isRelativePath(string $path): bool;
 
+    /**
+     * Replaces the path directory separator with the system one.
+     *
+     * For example, on Windows:
+     * 'C:/path/to/file' => 'C:\path\to\file',
+     */
     public function escapePath(string $path): string;
 
     /**
@@ -92,6 +99,9 @@ public function normalizedRealPath(string $file): string;
     public function getFileContents(string $file): string;
 
     /**
+     * @deprecated Use the `::tmpDir()` method. Deprecated since 2.0 and it will be removed in 3.0.
+     * @see self::tmpDir()
+     *
      * Creates a temporary directory.
      *
      * @param string $namespace the directory path in the system's temporary directory
@@ -102,6 +112,66 @@ public function getFileContents(string $file): string;
     public function makeTmpDir(string $namespace, string $className): string;
 
     /**
+     * Creates a temporary file with support for custom stream wrappers. Same as tempnam(),
+     * but targets the system default temporary directory by default and has a more consistent
+     * name with tmpDir.
+     *
+     * For example:
+     *
+     *  ```php
+     *  tmpFile('build')
+     *
+     *  // on OSX
+     *  => '/var/folders/p3/lkw0cgjj2fq0656q_9rd0mk80000gn/T/build8d9e0f1a'
+     *  // on Windows
+     *  => C:\Windows\Temp\build8d9e0f1a.tmp
+     *  ```
+     *
+     * @param string $prefix          The prefix of the generated temporary file name.
+     * @param string $suffix          The suffix of the generated temporary file name.
+     * @param string $targetDirectory The directory where to create the temporary directory.
+     *                                Defaults to the system default temporary directory.
+     *
+     * @throws IOException
+     * @return string      The new temporary file pathname.
+     *
+     * @see tempnam()
+     * @see SymfonyFileSystem::tempnam()
+     * @see self::tmpDir()
+     */
+    public function tmpFile(string $prefix, string $suffix = '', ?string $targetDirectory = null): string;
+
+    /**
+     * Creates a temporary directory with support for custom stream wrappers. Similar to tempnam()
+     * but creates a directory instead of a file.
+     *
+     * For example:
+     *
+     * ```php
+     * tmpDir('build')
+     *
+     * // on OSX
+     * => '/var/folders/p3/lkw0cgjj2fq0656q_9rd0mk80000gn/T/build8d9e0f1a'
+     * // on Windows
+     * => C:\Windows\Temp\build8d9e0f1a.tmp
+     * ```
+     *
+     * @param string|null $prefix          The prefix of the generated temporary directory name.
+     * @param string      $targetDirectory The directory where to create the temporary directory.
+     *                                     Defaults to the system default temporary directory.
+     *
+     * @throws IOException
+     *
+     * @return string The new temporary directory pathname.
+     *
+     * @see tempnam()
+     */
+    public function tmpDir(string $prefix, ?string $targetDirectory = null): string;
+
+    /**
+     * @deprecated Deprecated since 2.0. Use `Path::isRelative()` instead. Will be removed in 3.0.
+     *             Using a namespaced dir is an antipattern with parallel testing.
+     *
      * Gets a namespaced temporary directory.
      *
      * @param string $namespace the directory path in the system's temporary directory