vendor/symfony/filesystem/Filesystem.php line 513

  1. <?php
  3. /*
  4.  * This file is part of the Symfony package.
  5.  *
  6.  * (c) Fabien Potencier <fabien@symfony.com>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. namespace Symfony\Component\Filesystem;
  14. use Symfony\Component\Filesystem\Exception\FileNotFoundException;
  15. use Symfony\Component\Filesystem\Exception\InvalidArgumentException;
  16. use Symfony\Component\Filesystem\Exception\IOException;
  18. /**
  19.  * Provides basic utility to manipulate the file system.
  20.  *
  21.  * @author Fabien Potencier <fabien@symfony.com>
  22.  */
  23. class Filesystem
  24. {
  25.     private static $lastError;
  27.     /**
  28.      * Copies a file.
  29.      *
  30.      * If the target file is older than the origin file, it's always overwritten.
  31.      * If the target file is newer, it is overwritten only when the
  32.      * $overwriteNewerFiles option is set to true.
  33.      *
  34.      * @throws FileNotFoundException When originFile doesn't exist
  35.      * @throws IOException           When copy fails
  36.      */
  37.     public function copy(string $originFile, string $targetFile, bool $overwriteNewerFiles = false)
  38.     {
  39.         $originIsLocal = stream_is_local($originFile) || 0 === stripos($originFile, 'file://');
  40.         if ($originIsLocal && !is_file($originFile)) {
  41.             throw new FileNotFoundException(sprintf('Failed to copy "%s" because file does not exist.', $originFile), 0, null, $originFile);
  42.         }
  44.         $this->mkdir(\dirname($targetFile));
  46.         $doCopy = true;
  47.         if (!$overwriteNewerFiles && null === parse_url($originFile, \PHP_URL_HOST) && is_file($targetFile)) {
  48.             $doCopy = filemtime($originFile) > filemtime($targetFile);
  49.         }
  51.         if ($doCopy) {
  52.             // https://bugs.php.net/64634
  53.             if (!$source = self::box('fopen', $originFile, 'r')) {
  54.                 throw new IOException(sprintf('Failed to copy "%s" to "%s" because source file could not be opened for reading: ', $originFile, $targetFile).self::$lastError, 0, null, $originFile);
  55.             }
  57.             // Stream context created to allow files overwrite when using FTP stream wrapper - disabled by default
  58.             if (!$target = self::box('fopen', $targetFile, 'w', false, stream_context_create(['ftp' => ['overwrite' => true]]))) {
  59.                 throw new IOException(sprintf('Failed to copy "%s" to "%s" because target file could not be opened for writing: ', $originFile, $targetFile).self::$lastError, 0, null, $originFile);
  60.             }
  62.             $bytesCopied = stream_copy_to_stream($source, $target);
  63.             fclose($source);
  64.             fclose($target);
  65.             unset($source, $target);
  67.             if (!is_file($targetFile)) {
  68.                 throw new IOException(sprintf('Failed to copy "%s" to "%s".', $originFile, $targetFile), 0, null, $originFile);
  69.             }
  71.             if ($originIsLocal) {
  72.                 // Like `cp`, preserve executable permission bits
  73.                 self::box('chmod', $targetFile, fileperms($targetFile) | (fileperms($originFile) & 0111));
  75.                 if ($bytesCopied !== $bytesOrigin = filesize($originFile)) {
  76.                     throw new IOException(sprintf('Failed to copy the whole content of "%s" to "%s" (%g of %g bytes copied).', $originFile, $targetFile, $bytesCopied, $bytesOrigin), 0, null, $originFile);
  77.                 }
  78.             }
  79.         }
  80.     }
  82.     /**
  83.      * Creates a directory recursively.
  84.      *
  85.      * @throws IOException On any directory creation failure
  86.      */
  87.     public function mkdir(string|iterable $dirs, int $mode = 0777)
  88.     {
  89.         foreach ($this->toIterable($dirs) as $dir) {
  90.             if (is_dir($dir)) {
  91.                 continue;
  92.             }
  94.             if (!self::box('mkdir', $dir, $mode, true) && !is_dir($dir)) {
  95.                 throw new IOException(sprintf('Failed to create "%s": ', $dir).self::$lastError, 0, null, $dir);
  96.             }
  97.         }
  98.     }
  100.     /**
  101.      * Checks the existence of files or directories.
  102.      */
  103.     public function exists(string|iterable $files): bool
  104.     {
  105.         $maxPathLength = \PHP_MAXPATHLEN - 2;
  107.         foreach ($this->toIterable($files) as $file) {
  108.             if (\strlen($file) > $maxPathLength) {
  109.                 throw new IOException(sprintf('Could not check if file exist because path length exceeds %d characters.', $maxPathLength), 0, null, $file);
  110.             }
  112.             if (!file_exists($file)) {
  113.                 return false;
  114.             }
  115.         }
  117.         return true;
  118.     }
  120.     /**
  121.      * Sets access and modification time of file.
  122.      *
  123.      * @param int|null $time  The touch time as a Unix timestamp, if not supplied the current system time is used
  124.      * @param int|null $atime The access time as a Unix timestamp, if not supplied the current system time is used
  125.      *
  126.      * @throws IOException When touch fails
  127.      */
  128.     public function touch(string|iterable $files, int $time = null, int $atime = null)
  129.     {
  130.         foreach ($this->toIterable($files) as $file) {
  131.             if (!($time ? self::box('touch', $file, $time, $atime) : self::box('touch', $file))) {
  132.                 throw new IOException(sprintf('Failed to touch "%s": ', $file).self::$lastError, 0, null, $file);
  133.             }
  134.         }
  135.     }
  137.     /**
  138.      * Removes files or directories.
  139.      *
  140.      * @throws IOException When removal fails
  141.      */
  142.     public function remove(string|iterable $files)
  143.     {
  144.         if ($files instanceof \Traversable) {
  145.             $files = iterator_to_array($files, false);
  146.         } elseif (!\is_array($files)) {
  147.             $files = [$files];
  148.         }
  150.         self::doRemove($files, false);
  151.     }
  153.     private static function doRemove(array $files, bool $isRecursive): void
  154.     {
  155.         $files = array_reverse($files);
  156.         foreach ($files as $file) {
  157.             if (is_link($file)) {
  158.                 // See https://bugs.php.net/52176
  159.                 if (!(self::box('unlink', $file) || '\\' !== \DIRECTORY_SEPARATOR || self::box('rmdir', $file)) && file_exists($file)) {
  160.                     throw new IOException(sprintf('Failed to remove symlink "%s": ', $file).self::$lastError);
  161.                 }
  162.             } elseif (is_dir($file)) {
  163.                 if (!$isRecursive) {
  164.                     $tmpName = \dirname(realpath($file)).'/.'.strrev(strtr(base64_encode(random_bytes(2)), '/=', '-.'));
  166.                     if (file_exists($tmpName)) {
  167.                         try {
  168.                             self::doRemove([$tmpName], true);
  169.                         } catch (IOException) {
  170.                         }
  171.                     }
  173.                     if (!file_exists($tmpName) && self::box('rename', $file, $tmpName)) {
  174.                         $origFile = $file;
  175.                         $file = $tmpName;
  176.                     } else {
  177.                         $origFile = null;
  178.                     }
  179.                 }
  181.                 $filesystemIterator = new \FilesystemIterator($file, \FilesystemIterator::CURRENT_AS_PATHNAME | \FilesystemIterator::SKIP_DOTS);
  182.                 self::doRemove(iterator_to_array($filesystemIterator, true), true);
  184.                 if (!self::box('rmdir', $file) && file_exists($file) && !$isRecursive) {
  185.                     $lastError = self::$lastError;
  187.                     if (null !== $origFile && self::box('rename', $file, $origFile)) {
  188.                         $file = $origFile;
  189.                     }
  191.                     throw new IOException(sprintf('Failed to remove directory "%s": ', $file).$lastError);
  192.                 }
  193.             } elseif (!self::box('unlink', $file) && (str_contains(self::$lastError, 'Permission denied') || file_exists($file))) {
  194.                 throw new IOException(sprintf('Failed to remove file "%s": ', $file).self::$lastError);
  195.             }
  196.         }
  197.     }
  199.     /**
  200.      * Change mode for an array of files or directories.
  201.      *
  202.      * @param int  $mode      The new mode (octal)
  203.      * @param int  $umask     The mode mask (octal)
  204.      * @param bool $recursive Whether change the mod recursively or not
  205.      *
  206.      * @throws IOException When the change fails
  207.      */
  208.     public function chmod(string|iterable $files, int $mode, int $umask = 0000, bool $recursive = false)
  209.     {
  210.         foreach ($this->toIterable($files) as $file) {
  211.             if (\is_int($mode) && !self::box('chmod', $file, $mode & ~$umask)) {
  212.                 throw new IOException(sprintf('Failed to chmod file "%s": ', $file).self::$lastError, 0, null, $file);
  213.             }
  214.             if ($recursive && is_dir($file) && !is_link($file)) {
  215.                 $this->chmod(new \FilesystemIterator($file), $mode, $umask, true);
  216.             }
  217.         }
  218.     }
  220.     /**
  221.      * Change the owner of an array of files or directories.
  222.      *
  223.      * @param string|int $user      A user name or number
  224.      * @param bool       $recursive Whether change the owner recursively or not
  225.      *
  226.      * @throws IOException When the change fails
  227.      */
  228.     public function chown(string|iterable $files, string|int $user, bool $recursive = false)
  229.     {
  230.         foreach ($this->toIterable($files) as $file) {
  231.             if ($recursive && is_dir($file) && !is_link($file)) {
  232.                 $this->chown(new \FilesystemIterator($file), $user, true);
  233.             }
  234.             if (is_link($file) && \function_exists('lchown')) {
  235.                 if (!self::box('lchown', $file, $user)) {
  236.                     throw new IOException(sprintf('Failed to chown file "%s": ', $file).self::$lastError, 0, null, $file);
  237.                 }
  238.             } else {
  239.                 if (!self::box('chown', $file, $user)) {
  240.                     throw new IOException(sprintf('Failed to chown file "%s": ', $file).self::$lastError, 0, null, $file);
  241.                 }
  242.             }
  243.         }
  244.     }
  246.     /**
  247.      * Change the group of an array of files or directories.
  248.      *
  249.      * @param string|int $group     A group name or number
  250.      * @param bool       $recursive Whether change the group recursively or not
  251.      *
  252.      * @throws IOException When the change fails
  253.      */
  254.     public function chgrp(string|iterable $files, string|int $group, bool $recursive = false)
  255.     {
  256.         foreach ($this->toIterable($files) as $file) {
  257.             if ($recursive && is_dir($file) && !is_link($file)) {
  258.                 $this->chgrp(new \FilesystemIterator($file), $group, true);
  259.             }
  260.             if (is_link($file) && \function_exists('lchgrp')) {
  261.                 if (!self::box('lchgrp', $file, $group)) {
  262.                     throw new IOException(sprintf('Failed to chgrp file "%s": ', $file).self::$lastError, 0, null, $file);
  263.                 }
  264.             } else {
  265.                 if (!self::box('chgrp', $file, $group)) {
  266.                     throw new IOException(sprintf('Failed to chgrp file "%s": ', $file).self::$lastError, 0, null, $file);
  267.                 }
  268.             }
  269.         }
  270.     }
  272.     /**
  273.      * Renames a file or a directory.
  274.      *
  275.      * @throws IOException When target file or directory already exists
  276.      * @throws IOException When origin cannot be renamed
  277.      */
  278.     public function rename(string $origin, string $target, bool $overwrite = false)
  279.     {
  280.         // we check that target does not exist
  281.         if (!$overwrite && $this->isReadable($target)) {
  282.             throw new IOException(sprintf('Cannot rename because the target "%s" already exists.', $target), 0, null, $target);
  283.         }
  285.         if (!self::box('rename', $origin, $target)) {
  286.             if (is_dir($origin)) {
  287.                 // See https://bugs.php.net/54097 & https://php.net/rename#113943
  288.                 $this->mirror($origin, $target, null, ['override' => $overwrite, 'delete' => $overwrite]);
  289.                 $this->remove($origin);
  291.                 return;
  292.             }
  293.             throw new IOException(sprintf('Cannot rename "%s" to "%s": ', $origin, $target).self::$lastError, 0, null, $target);
  294.         }
  295.     }
  297.     /**
  298.      * Tells whether a file exists and is readable.
  299.      *
  300.      * @throws IOException When windows path is longer than 258 characters
  301.      */
  302.     private function isReadable(string $filename): bool
  303.     {
  304.         $maxPathLength = \PHP_MAXPATHLEN - 2;
  306.         if (\strlen($filename) > $maxPathLength) {
  307.             throw new IOException(sprintf('Could not check if file is readable because path length exceeds %d characters.', $maxPathLength), 0, null, $filename);
  308.         }
  310.         return is_readable($filename);
  311.     }
  313.     /**
  314.      * Creates a symbolic link or copy a directory.
  315.      *
  316.      * @throws IOException When symlink fails
  317.      */
  318.     public function symlink(string $originDir, string $targetDir, bool $copyOnWindows = false)
  319.     {
  320.         self::assertFunctionExists('symlink');
  322.         if ('\\' === \DIRECTORY_SEPARATOR) {
  323.             $originDir = strtr($originDir, '/', '\\');
  324.             $targetDir = strtr($targetDir, '/', '\\');
  326.             if ($copyOnWindows) {
  327.                 $this->mirror($originDir, $targetDir);
  329.                 return;
  330.             }
  331.         }
  333.         $this->mkdir(\dirname($targetDir));
  335.         if (is_link($targetDir)) {
  336.             if (readlink($targetDir) === $originDir) {
  337.                 return;
  338.             }
  339.             $this->remove($targetDir);
  340.         }
  342.         if (!self::box('symlink', $originDir, $targetDir)) {
  343.             $this->linkException($originDir, $targetDir, 'symbolic');
  344.         }
  345.     }
  347.     /**
  348.      * Creates a hard link, or several hard links to a file.
  349.      *
  350.      * @param string|string[] $targetFiles The target file(s)
  351.      *
  352.      * @throws FileNotFoundException When original file is missing or not a file
  353.      * @throws IOException           When link fails, including if link already exists
  354.      */
  355.     public function hardlink(string $originFile, string|iterable $targetFiles)
  356.     {
  357.         self::assertFunctionExists('link');
  359.         if (!$this->exists($originFile)) {
  360.             throw new FileNotFoundException(null, 0, null, $originFile);
  361.         }
  363.         if (!is_file($originFile)) {
  364.             throw new FileNotFoundException(sprintf('Origin file "%s" is not a file.', $originFile));
  365.         }
  367.         foreach ($this->toIterable($targetFiles) as $targetFile) {
  368.             if (is_file($targetFile)) {
  369.                 if (fileinode($originFile) === fileinode($targetFile)) {
  370.                     continue;
  371.                 }
  372.                 $this->remove($targetFile);
  373.             }
  375.             if (!self::box('link', $originFile, $targetFile)) {
  376.                 $this->linkException($originFile, $targetFile, 'hard');
  377.             }
  378.         }
  379.     }
  381.     /**
  382.      * @param string $linkType Name of the link type, typically 'symbolic' or 'hard'
  383.      */
  384.     private function linkException(string $origin, string $target, string $linkType)
  385.     {
  386.         if (self::$lastError) {
  387.             if ('\\' === \DIRECTORY_SEPARATOR && str_contains(self::$lastError, 'error code(1314)')) {
  388.                 throw new IOException(sprintf('Unable to create "%s" link due to error code 1314: \'A required privilege is not held by the client\'. Do you have the required Administrator-rights?', $linkType), 0, null, $target);
  389.             }
  390.         }
  391.         throw new IOException(sprintf('Failed to create "%s" link from "%s" to "%s": ', $linkType, $origin, $target).self::$lastError, 0, null, $target);
  392.     }
  394.     /**
  395.      * Resolves links in paths.
  396.      *
  397.      * With $canonicalize = false (default)
  398.      *      - if $path does not exist or is not a link, returns null
  399.      *      - if $path is a link, returns the next direct target of the link without considering the existence of the target
  400.      *
  401.      * With $canonicalize = true
  402.      *      - if $path does not exist, returns null
  403.      *      - if $path exists, returns its absolute fully resolved final version
  404.      */
  405.     public function readlink(string $path, bool $canonicalize = false): ?string
  406.     {
  407.         if (!$canonicalize && !is_link($path)) {
  408.             return null;
  409.         }
  411.         if ($canonicalize) {
  412.             if (!$this->exists($path)) {
  413.                 return null;
  414.             }
  416.             return realpath($path);
  417.         }
  419.         return readlink($path);
  420.     }
  422.     /**
  423.      * Given an existing path, convert it to a path relative to a given starting path.
  424.      */
  425.     public function makePathRelative(string $endPath, string $startPath): string
  426.     {
  427.         if (!$this->isAbsolutePath($startPath)) {
  428.             throw new InvalidArgumentException(sprintf('The start path "%s" is not absolute.', $startPath));
  429.         }
  431.         if (!$this->isAbsolutePath($endPath)) {
  432.             throw new InvalidArgumentException(sprintf('The end path "%s" is not absolute.', $endPath));
  433.         }
  435.         // Normalize separators on Windows
  436.         if ('\\' === \DIRECTORY_SEPARATOR) {
  437.             $endPath = str_replace('\\', '/', $endPath);
  438.             $startPath = str_replace('\\', '/', $startPath);
  439.         }
  441.         $splitDriveLetter = function ($path) {
  442.             return (\strlen($path) > 2 && ':' === $path[1] && '/' === $path[2] && ctype_alpha($path[0]))
  443.                 ? [substr($path, 2), strtoupper($path[0])]
  444.                 : [$path, null];
  445.         };
  447.         $splitPath = function ($path) {
  448.             $result = [];
  450.             foreach (explode('/', trim($path, '/')) as $segment) {
  451.                 if ('..' === $segment) {
  452.                     array_pop($result);
  453.                 } elseif ('.' !== $segment && '' !== $segment) {
  454.                     $result[] = $segment;
  455.                 }
  456.             }
  458.             return $result;
  459.         };
  461.         [$endPath, $endDriveLetter] = $splitDriveLetter($endPath);
  462.         [$startPath, $startDriveLetter] = $splitDriveLetter($startPath);
  464.         $startPathArr = $splitPath($startPath);
  465.         $endPathArr = $splitPath($endPath);
  467.         if ($endDriveLetter && $startDriveLetter && $endDriveLetter != $startDriveLetter) {
  468.             // End path is on another drive, so no relative path exists
  469.             return $endDriveLetter.':/'.($endPathArr ? implode('/', $endPathArr).'/' : '');
  470.         }
  472.         // Find for which directory the common path stops
  473.         $index = 0;
  474.         while (isset($startPathArr[$index]) && isset($endPathArr[$index]) && $startPathArr[$index] === $endPathArr[$index]) {
  475.             ++$index;
  476.         }
  478.         // Determine how deep the start path is relative to the common path (ie, "web/bundles" = 2 levels)
  479.         if (1 === \count($startPathArr) && '' === $startPathArr[0]) {
  480.             $depth = 0;
  481.         } else {
  482.             $depth = \count($startPathArr) - $index;
  483.         }
  485.         // Repeated "../" for each level need to reach the common path
  486.         $traverser = str_repeat('../', $depth);
  488.         $endPathRemainder = implode('/', \array_slice($endPathArr, $index));
  490.         // Construct $endPath from traversing to the common path, then to the remaining $endPath
  491.         $relativePath = $traverser.('' !== $endPathRemainder ? $endPathRemainder.'/' : '');
  493.         return '' === $relativePath ? './' : $relativePath;
  494.     }
  496.     /**
  497.      * Mirrors a directory to another.
  498.      *
  499.      * Copies files and directories from the origin directory into the target directory. By default:
  500.      *
  501.      *  - existing files in the target directory will be overwritten, except if they are newer (see the `override` option)
  502.      *  - files in the target directory that do not exist in the source directory will not be deleted (see the `delete` option)
  503.      *
  504.      * @param \Traversable|null $iterator Iterator that filters which files and directories to copy, if null a recursive iterator is created
  505.      * @param array             $options  An array of boolean options
  506.      *                                    Valid options are:
  507.      *                                    - $options['override'] If true, target files newer than origin files are overwritten (see copy(), defaults to false)
  508.      *                                    - $options['copy_on_windows'] Whether to copy files instead of links on Windows (see symlink(), defaults to false)
  509.      *                                    - $options['delete'] Whether to delete files that are not in the source directory (defaults to false)
  510.      *
  511.      * @throws IOException When file type is unknown
  512.      */
  513.     public function mirror(string $originDir, string $targetDir, \Traversable $iterator = null, array $options = [])
  514.     {
  515.         $targetDir = rtrim($targetDir, '/\\');
  516.         $originDir = rtrim($originDir, '/\\');
  517.         $originDirLen = \strlen($originDir);
  519.         if (!$this->exists($originDir)) {
  520.             throw new IOException(sprintf('The origin directory specified "%s" was not found.', $originDir), 0, null, $originDir);
  521.         }
  523.         // Iterate in destination folder to remove obsolete entries
  524.         if ($this->exists($targetDir) && isset($options['delete']) && $options['delete']) {
  525.             $deleteIterator = $iterator;
  526.             if (null === $deleteIterator) {
  527.                 $flags = \FilesystemIterator::SKIP_DOTS;
  528.                 $deleteIterator = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($targetDir, $flags), \RecursiveIteratorIterator::CHILD_FIRST);
  529.             }
  530.             $targetDirLen = \strlen($targetDir);
  531.             foreach ($deleteIterator as $file) {
  532.                 $origin = $originDir.substr($file->getPathname(), $targetDirLen);
  533.                 if (!$this->exists($origin)) {
  534.                     $this->remove($file);
  535.                 }
  536.             }
  537.         }
  539.         $copyOnWindows = $options['copy_on_windows'] ?? false;
  541.         if (null === $iterator) {
  542.             $flags = $copyOnWindows ? \FilesystemIterator::SKIP_DOTS | \FilesystemIterator::FOLLOW_SYMLINKS : \FilesystemIterator::SKIP_DOTS;
  543.             $iterator = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($originDir, $flags), \RecursiveIteratorIterator::SELF_FIRST);
  544.         }
  546.         $this->mkdir($targetDir);
  547.         $filesCreatedWhileMirroring = [];
  549.         foreach ($iterator as $file) {
  550.             if ($file->getPathname() === $targetDir || $file->getRealPath() === $targetDir || isset($filesCreatedWhileMirroring[$file->getRealPath()])) {
  551.                 continue;
  552.             }
  554.             $target = $targetDir.substr($file->getPathname(), $originDirLen);
  555.             $filesCreatedWhileMirroring[$target] = true;
  557.             if (!$copyOnWindows && is_link($file)) {
  558.                 $this->symlink($file->getLinkTarget(), $target);
  559.             } elseif (is_dir($file)) {
  560.                 $this->mkdir($target);
  561.             } elseif (is_file($file)) {
  562.                 $this->copy($file, $target, $options['override'] ?? false);
  563.             } else {
  564.                 throw new IOException(sprintf('Unable to guess "%s" file type.', $file), 0, null, $file);
  565.             }
  566.         }
  567.     }
  569.     /**
  570.      * Returns whether the file path is an absolute path.
  571.      */
  572.     public function isAbsolutePath(string $file): bool
  573.     {
  574.         return '' !== $file && (strspn($file, '/\\', 0, 1)
  575.             || (\strlen($file) > 3 && ctype_alpha($file[0])
  576.                 && ':' === $file[1]
  577.                 && strspn($file, '/\\', 2, 1)
  578.             )
  579.             || null !== parse_url($file, \PHP_URL_SCHEME)
  580.         );
  581.     }
  583.     /**
  584.      * Creates a temporary file with support for custom stream wrappers.
  585.      *
  586.      * @param string $prefix The prefix of the generated temporary filename
  587.      *                       Note: Windows uses only the first three characters of prefix
  588.      * @param string $suffix The suffix of the generated temporary filename
  589.      *
  590.      * @return string The new temporary filename (with path), or throw an exception on failure
  591.      */
  592.     public function tempnam(string $dir, string $prefix, string $suffix = ''): string
  593.     {
  594.         [$scheme, $hierarchy] = $this->getSchemeAndHierarchy($dir);
  596.         // If no scheme or scheme is "file" or "gs" (Google Cloud) create temp file in local filesystem
  597.         if ((null === $scheme || 'file' === $scheme || 'gs' === $scheme) && '' === $suffix) {
  598.             // If tempnam failed or no scheme return the filename otherwise prepend the scheme
  599.             if ($tmpFile = self::box('tempnam', $hierarchy, $prefix)) {
  600.                 if (null !== $scheme && 'gs' !== $scheme) {
  601.                     return $scheme.'://'.$tmpFile;
  602.                 }
  604.                 return $tmpFile;
  605.             }
  607.             throw new IOException('A temporary file could not be created: '.self::$lastError);
  608.         }
  610.         // Loop until we create a valid temp file or have reached 10 attempts
  611.         for ($i = 0; $i < 10; ++$i) {
  612.             // Create a unique filename
  613.             $tmpFile = $dir.'/'.$prefix.uniqid(mt_rand(), true).$suffix;
  615.             // Use fopen instead of file_exists as some streams do not support stat
  616.             // Use mode 'x+' to atomically check existence and create to avoid a TOCTOU vulnerability
  617.             if (!$handle = self::box('fopen', $tmpFile, 'x+')) {
  618.                 continue;
  619.             }
  621.             // Close the file if it was successfully opened
  622.             self::box('fclose', $handle);
  624.             return $tmpFile;
  625.         }
  627.         throw new IOException('A temporary file could not be created: '.self::$lastError);
  628.     }
  630.     /**
  631.      * Atomically dumps content into a file.
  632.      *
  633.      * @param string|resource $content The data to write into the file
  634.      *
  635.      * @throws IOException if the file cannot be written to
  636.      */
  637.     public function dumpFile(string $filename, $content)
  638.     {
  639.         if (\is_array($content)) {
  640.             throw new \TypeError(sprintf('Argument 2 passed to "%s()" must be string or resource, array given.', __METHOD__));
  641.         }
  643.         $dir = \dirname($filename);
  645.         if (!is_dir($dir)) {
  646.             $this->mkdir($dir);
  647.         }
  649.         // Will create a temp file with 0600 access rights
  650.         // when the filesystem supports chmod.
  651.         $tmpFile = $this->tempnam($dir, basename($filename));
  653.         try {
  654.             if (false === self::box('file_put_contents', $tmpFile, $content)) {
  655.                 throw new IOException(sprintf('Failed to write file "%s": ', $filename).self::$lastError, 0, null, $filename);
  656.             }
  658.             self::box('chmod', $tmpFile, file_exists($filename) ? fileperms($filename) : 0666 & ~umask());
  660.             $this->rename($tmpFile, $filename, true);
  661.         } finally {
  662.             if (file_exists($tmpFile)) {
  663.                 self::box('unlink', $tmpFile);
  664.             }
  665.         }
  666.     }
  668.     /**
  669.      * Appends content to an existing file.
  670.      *
  671.      * @param string|resource $content The content to append
  672.      * @param bool            $lock    Whether the file should be locked when writing to it
  673.      *
  674.      * @throws IOException If the file is not writable
  675.      */
  676.     public function appendToFile(string $filename, $content/* , bool $lock = false */)
  677.     {
  678.         if (\is_array($content)) {
  679.             throw new \TypeError(sprintf('Argument 2 passed to "%s()" must be string or resource, array given.', __METHOD__));
  680.         }
  682.         $dir = \dirname($filename);
  684.         if (!is_dir($dir)) {
  685.             $this->mkdir($dir);
  686.         }
  688.         $lock = \func_num_args() > 2 && func_get_arg(2);
  690.         if (false === self::box('file_put_contents', $filename, $content, \FILE_APPEND | ($lock ? \LOCK_EX : 0))) {
  691.             throw new IOException(sprintf('Failed to write file "%s": ', $filename).self::$lastError, 0, null, $filename);
  692.         }
  693.     }
  695.     private function toIterable(string|iterable $files): iterable
  696.     {
  697.         return is_iterable($files) ? $files : [$files];
  698.     }
  700.     /**
  701.      * Gets a 2-tuple of scheme (may be null) and hierarchical part of a filename (e.g. file:///tmp -> [file, tmp]).
  702.      */
  703.     private function getSchemeAndHierarchy(string $filename): array
  704.     {
  705.         $components = explode('://', $filename, 2);
  707.         return 2 === \count($components) ? [$components[0], $components[1]] : [null, $components[0]];
  708.     }
  710.     private static function assertFunctionExists(string $func): void
  711.     {
  712.         if (!\function_exists($func)) {
  713.             throw new IOException(sprintf('Unable to perform filesystem operation because the "%s()" function has been disabled.', $func));
  714.         }
  715.     }
  717.     private static function box(string $func, mixed ...$args): mixed
  718.     {
  719.         self::assertFunctionExists($func);
  721.         self::$lastError = null;
  722.         set_error_handler(__CLASS__.'::handleError');
  723.         try {
  724.             return $func(...$args);
  725.         } finally {
  726.             restore_error_handler();
  727.         }
  728.     }
  730.     /**
  731.      * @internal
  732.      */
  733.     public static function handleError(int $type, string $msg)
  734.     {
  735.         self::$lastError = $msg;
  736.     }
  737. }