vendor/symfony/filesystem/Filesystem.php line 135

Open in your IDE?
  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.      * @param string|iterable $dirs The directory path
  86.      *
  87.      * @throws IOException On any directory creation failure
  88.      */
  89.     public function mkdir($dirs, int $mode = 0777)
  90.     {
  91.         foreach ($this->toIterable($dirs) as $dir) {
  92.             if (is_dir($dir)) {
  93.                 continue;
  94.             }
  96.             if (!self::box('mkdir', $dir, $mode, true) && !is_dir($dir)) {
  97.                 throw new IOException(sprintf('Failed to create "%s": ', $dir).self::$lastError, 0, null, $dir);
  98.             }
  99.         }
  100.     }
  102.     /**
  103.      * Checks the existence of files or directories.
  104.      *
  105.      * @param string|iterable $files A filename, an array of files, or a \Traversable instance to check
  106.      *
  107.      * @return bool
  108.      */
  109.     public function exists($files)
  110.     {
  111.         $maxPathLength = \PHP_MAXPATHLEN - 2;
  113.         foreach ($this->toIterable($files) as $file) {
  114.             if (\strlen($file) > $maxPathLength) {
  115.                 throw new IOException(sprintf('Could not check if file exist because path length exceeds %d characters.', $maxPathLength), 0, null, $file);
  116.             }
  118.             if (!file_exists($file)) {
  119.                 return false;
  120.             }
  121.         }
  123.         return true;
  124.     }
  126.     /**
  127.      * Sets access and modification time of file.
  128.      *
  129.      * @param string|iterable $files A filename, an array of files, or a \Traversable instance to create
  130.      * @param int|null        $time  The touch time as a Unix timestamp, if not supplied the current system time is used
  131.      * @param int|null        $atime The access time as a Unix timestamp, if not supplied the current system time is used
  132.      *
  133.      * @throws IOException When touch fails
  134.      */
  135.     public function touch($files, int $time = null, int $atime = null)
  136.     {
  137.         foreach ($this->toIterable($files) as $file) {
  138.             if (!($time ? self::box('touch', $file, $time, $atime) : self::box('touch', $file))) {
  139.                 throw new IOException(sprintf('Failed to touch "%s": ', $file).self::$lastError, 0, null, $file);
  140.             }
  141.         }
  142.     }
  144.     /**
  145.      * Removes files or directories.
  146.      *
  147.      * @param string|iterable $files A filename, an array of files, or a \Traversable instance to remove
  148.      *
  149.      * @throws IOException When removal fails
  150.      */
  151.     public function remove($files)
  152.     {
  153.         if ($files instanceof \Traversable) {
  154.             $files = iterator_to_array($files, false);
  155.         } elseif (!\is_array($files)) {
  156.             $files = [$files];
  157.         }
  159.         self::doRemove($files, false);
  160.     }
  162.     private static function doRemove(array $files, bool $isRecursive): void
  163.     {
  164.         $files = array_reverse($files);
  165.         foreach ($files as $file) {
  166.             if (is_link($file)) {
  167.                 // See https://bugs.php.net/52176
  168.                 if (!(self::box('unlink', $file) || '\\' !== \DIRECTORY_SEPARATOR || self::box('rmdir', $file)) && file_exists($file)) {
  169.                     throw new IOException(sprintf('Failed to remove symlink "%s": ', $file).self::$lastError);
  170.                 }
  171.             } elseif (is_dir($file)) {
  172.                 if (!$isRecursive) {
  173.                     $tmpName = \dirname(realpath($file)).'/.'.strrev(strtr(base64_encode(random_bytes(2)), '/=', '-.'));
  175.                     if (file_exists($tmpName)) {
  176.                         try {
  177.                             self::doRemove([$tmpName], true);
  178.                         } catch (IOException $e) {
  179.                         }
  180.                     }
  182.                     if (!file_exists($tmpName) && self::box('rename', $file, $tmpName)) {
  183.                         $origFile = $file;
  184.                         $file = $tmpName;
  185.                     } else {
  186.                         $origFile = null;
  187.                     }
  188.                 }
  190.                 $files = new \FilesystemIterator($file, \FilesystemIterator::CURRENT_AS_PATHNAME | \FilesystemIterator::SKIP_DOTS);
  191.                 self::doRemove(iterator_to_array($files, true), true);
  193.                 if (!self::box('rmdir', $file) && file_exists($file) && !$isRecursive) {
  194.                     $lastError = self::$lastError;
  196.                     if (null !== $origFile && self::box('rename', $file, $origFile)) {
  197.                         $file = $origFile;
  198.                     }
  200.                     throw new IOException(sprintf('Failed to remove directory "%s": ', $file).$lastError);
  201.                 }
  202.             } elseif (!self::box('unlink', $file) && (str_contains(self::$lastError, 'Permission denied') || file_exists($file))) {
  203.                 throw new IOException(sprintf('Failed to remove file "%s": ', $file).self::$lastError);
  204.             }
  205.         }
  206.     }
  208.     /**
  209.      * Change mode for an array of files or directories.
  210.      *
  211.      * @param string|iterable $files     A filename, an array of files, or a \Traversable instance to change mode
  212.      * @param int             $mode      The new mode (octal)
  213.      * @param int             $umask     The mode mask (octal)
  214.      * @param bool            $recursive Whether change the mod recursively or not
  215.      *
  216.      * @throws IOException When the change fails
  217.      */
  218.     public function chmod($files, int $mode, int $umask = 0000, bool $recursive = false)
  219.     {
  220.         foreach ($this->toIterable($files) as $file) {
  221.             if ((\PHP_VERSION_ID < 80000 || \is_int($mode)) && !self::box('chmod', $file, $mode & ~$umask)) {
  222.                 throw new IOException(sprintf('Failed to chmod file "%s": ', $file).self::$lastError, 0, null, $file);
  223.             }
  224.             if ($recursive && is_dir($file) && !is_link($file)) {
  225.                 $this->chmod(new \FilesystemIterator($file), $mode, $umask, true);
  226.             }
  227.         }
  228.     }
  230.     /**
  231.      * Change the owner of an array of files or directories.
  232.      *
  233.      * @param string|iterable $files     A filename, an array of files, or a \Traversable instance to change owner
  234.      * @param string|int      $user      A user name or number
  235.      * @param bool            $recursive Whether change the owner recursively or not
  236.      *
  237.      * @throws IOException When the change fails
  238.      */
  239.     public function chown($files, $user, bool $recursive = false)
  240.     {
  241.         foreach ($this->toIterable($files) as $file) {
  242.             if ($recursive && is_dir($file) && !is_link($file)) {
  243.                 $this->chown(new \FilesystemIterator($file), $user, true);
  244.             }
  245.             if (is_link($file) && \function_exists('lchown')) {
  246.                 if (!self::box('lchown', $file, $user)) {
  247.                     throw new IOException(sprintf('Failed to chown file "%s": ', $file).self::$lastError, 0, null, $file);
  248.                 }
  249.             } else {
  250.                 if (!self::box('chown', $file, $user)) {
  251.                     throw new IOException(sprintf('Failed to chown file "%s": ', $file).self::$lastError, 0, null, $file);
  252.                 }
  253.             }
  254.         }
  255.     }
  257.     /**
  258.      * Change the group of an array of files or directories.
  259.      *
  260.      * @param string|iterable $files     A filename, an array of files, or a \Traversable instance to change group
  261.      * @param string|int      $group     A group name or number
  262.      * @param bool            $recursive Whether change the group recursively or not
  263.      *
  264.      * @throws IOException When the change fails
  265.      */
  266.     public function chgrp($files, $group, bool $recursive = false)
  267.     {
  268.         foreach ($this->toIterable($files) as $file) {
  269.             if ($recursive && is_dir($file) && !is_link($file)) {
  270.                 $this->chgrp(new \FilesystemIterator($file), $group, true);
  271.             }
  272.             if (is_link($file) && \function_exists('lchgrp')) {
  273.                 if (!self::box('lchgrp', $file, $group)) {
  274.                     throw new IOException(sprintf('Failed to chgrp file "%s": ', $file).self::$lastError, 0, null, $file);
  275.                 }
  276.             } else {
  277.                 if (!self::box('chgrp', $file, $group)) {
  278.                     throw new IOException(sprintf('Failed to chgrp file "%s": ', $file).self::$lastError, 0, null, $file);
  279.                 }
  280.             }
  281.         }
  282.     }
  284.     /**
  285.      * Renames a file or a directory.
  286.      *
  287.      * @throws IOException When target file or directory already exists
  288.      * @throws IOException When origin cannot be renamed
  289.      */
  290.     public function rename(string $origin, string $target, bool $overwrite = false)
  291.     {
  292.         // we check that target does not exist
  293.         if (!$overwrite && $this->isReadable($target)) {
  294.             throw new IOException(sprintf('Cannot rename because the target "%s" already exists.', $target), 0, null, $target);
  295.         }
  297.         if (!self::box('rename', $origin, $target)) {
  298.             if (is_dir($origin)) {
  299.                 // See https://bugs.php.net/54097 & https://php.net/rename#113943
  300.                 $this->mirror($origin, $target, null, ['override' => $overwrite, 'delete' => $overwrite]);
  301.                 $this->remove($origin);
  303.                 return;
  304.             }
  305.             throw new IOException(sprintf('Cannot rename "%s" to "%s": ', $origin, $target).self::$lastError, 0, null, $target);
  306.         }
  307.     }
  309.     /**
  310.      * Tells whether a file exists and is readable.
  311.      *
  312.      * @throws IOException When windows path is longer than 258 characters
  313.      */
  314.     private function isReadable(string $filename): bool
  315.     {
  316.         $maxPathLength = \PHP_MAXPATHLEN - 2;
  318.         if (\strlen($filename) > $maxPathLength) {
  319.             throw new IOException(sprintf('Could not check if file is readable because path length exceeds %d characters.', $maxPathLength), 0, null, $filename);
  320.         }
  322.         return is_readable($filename);
  323.     }
  325.     /**
  326.      * Creates a symbolic link or copy a directory.
  327.      *
  328.      * @throws IOException When symlink fails
  329.      */
  330.     public function symlink(string $originDir, string $targetDir, bool $copyOnWindows = false)
  331.     {
  332.         self::assertFunctionExists('symlink');
  334.         if ('\\' === \DIRECTORY_SEPARATOR) {
  335.             $originDir = strtr($originDir, '/', '\\');
  336.             $targetDir = strtr($targetDir, '/', '\\');
  338.             if ($copyOnWindows) {
  339.                 $this->mirror($originDir, $targetDir);
  341.                 return;
  342.             }
  343.         }
  345.         $this->mkdir(\dirname($targetDir));
  347.         if (is_link($targetDir)) {
  348.             if (readlink($targetDir) === $originDir) {
  349.                 return;
  350.             }
  351.             $this->remove($targetDir);
  352.         }
  354.         if (!self::box('symlink', $originDir, $targetDir)) {
  355.             $this->linkException($originDir, $targetDir, 'symbolic');
  356.         }
  357.     }
  359.     /**
  360.      * Creates a hard link, or several hard links to a file.
  361.      *
  362.      * @param string|string[] $targetFiles The target file(s)
  363.      *
  364.      * @throws FileNotFoundException When original file is missing or not a file
  365.      * @throws IOException           When link fails, including if link already exists
  366.      */
  367.     public function hardlink(string $originFile, $targetFiles)
  368.     {
  369.         self::assertFunctionExists('link');
  371.         if (!$this->exists($originFile)) {
  372.             throw new FileNotFoundException(null, 0, null, $originFile);
  373.         }
  375.         if (!is_file($originFile)) {
  376.             throw new FileNotFoundException(sprintf('Origin file "%s" is not a file.', $originFile));
  377.         }
  379.         foreach ($this->toIterable($targetFiles) as $targetFile) {
  380.             if (is_file($targetFile)) {
  381.                 if (fileinode($originFile) === fileinode($targetFile)) {
  382.                     continue;
  383.                 }
  384.                 $this->remove($targetFile);
  385.             }
  387.             if (!self::box('link', $originFile, $targetFile)) {
  388.                 $this->linkException($originFile, $targetFile, 'hard');
  389.             }
  390.         }
  391.     }
  393.     /**
  394.      * @param string $linkType Name of the link type, typically 'symbolic' or 'hard'
  395.      */
  396.     private function linkException(string $origin, string $target, string $linkType)
  397.     {
  398.         if (self::$lastError) {
  399.             if ('\\' === \DIRECTORY_SEPARATOR && str_contains(self::$lastError, 'error code(1314)')) {
  400.                 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);
  401.             }
  402.         }
  403.         throw new IOException(sprintf('Failed to create "%s" link from "%s" to "%s": ', $linkType, $origin, $target).self::$lastError, 0, null, $target);
  404.     }
  406.     /**
  407.      * Resolves links in paths.
  408.      *
  409.      * With $canonicalize = false (default)
  410.      *      - if $path does not exist or is not a link, returns null
  411.      *      - if $path is a link, returns the next direct target of the link without considering the existence of the target
  412.      *
  413.      * With $canonicalize = true
  414.      *      - if $path does not exist, returns null
  415.      *      - if $path exists, returns its absolute fully resolved final version
  416.      *
  417.      * @return string|null
  418.      */
  419.     public function readlink(string $path, bool $canonicalize = false)
  420.     {
  421.         if (!$canonicalize && !is_link($path)) {
  422.             return null;
  423.         }
  425.         if ($canonicalize) {
  426.             if (!$this->exists($path)) {
  427.                 return null;
  428.             }
  430.             if ('\\' === \DIRECTORY_SEPARATOR && \PHP_VERSION_ID < 70410) {
  431.                 $path = readlink($path);
  432.             }
  434.             return realpath($path);
  435.         }
  437.         if ('\\' === \DIRECTORY_SEPARATOR && \PHP_VERSION_ID < 70400) {
  438.             return realpath($path);
  439.         }
  441.         return readlink($path);
  442.     }
  444.     /**
  445.      * Given an existing path, convert it to a path relative to a given starting path.
  446.      *
  447.      * @return string
  448.      */
  449.     public function makePathRelative(string $endPath, string $startPath)
  450.     {
  451.         if (!$this->isAbsolutePath($startPath)) {
  452.             throw new InvalidArgumentException(sprintf('The start path "%s" is not absolute.', $startPath));
  453.         }
  455.         if (!$this->isAbsolutePath($endPath)) {
  456.             throw new InvalidArgumentException(sprintf('The end path "%s" is not absolute.', $endPath));
  457.         }
  459.         // Normalize separators on Windows
  460.         if ('\\' === \DIRECTORY_SEPARATOR) {
  461.             $endPath = str_replace('\\', '/', $endPath);
  462.             $startPath = str_replace('\\', '/', $startPath);
  463.         }
  465.         $splitDriveLetter = function ($path) {
  466.             return (\strlen($path) > 2 && ':' === $path[1] && '/' === $path[2] && ctype_alpha($path[0]))
  467.                 ? [substr($path, 2), strtoupper($path[0])]
  468.                 : [$path, null];
  469.         };
  471.         $splitPath = function ($path) {
  472.             $result = [];
  474.             foreach (explode('/', trim($path, '/')) as $segment) {
  475.                 if ('..' === $segment) {
  476.                     array_pop($result);
  477.                 } elseif ('.' !== $segment && '' !== $segment) {
  478.                     $result[] = $segment;
  479.                 }
  480.             }
  482.             return $result;
  483.         };
  485.         [$endPath, $endDriveLetter] = $splitDriveLetter($endPath);
  486.         [$startPath, $startDriveLetter] = $splitDriveLetter($startPath);
  488.         $startPathArr = $splitPath($startPath);
  489.         $endPathArr = $splitPath($endPath);
  491.         if ($endDriveLetter && $startDriveLetter && $endDriveLetter != $startDriveLetter) {
  492.             // End path is on another drive, so no relative path exists
  493.             return $endDriveLetter.':/'.($endPathArr ? implode('/', $endPathArr).'/' : '');
  494.         }
  496.         // Find for which directory the common path stops
  497.         $index = 0;
  498.         while (isset($startPathArr[$index]) && isset($endPathArr[$index]) && $startPathArr[$index] === $endPathArr[$index]) {
  499.             ++$index;
  500.         }
  502.         // Determine how deep the start path is relative to the common path (ie, "web/bundles" = 2 levels)
  503.         if (1 === \count($startPathArr) && '' === $startPathArr[0]) {
  504.             $depth = 0;
  505.         } else {
  506.             $depth = \count($startPathArr) - $index;
  507.         }
  509.         // Repeated "../" for each level need to reach the common path
  510.         $traverser = str_repeat('../', $depth);
  512.         $endPathRemainder = implode('/', \array_slice($endPathArr, $index));
  514.         // Construct $endPath from traversing to the common path, then to the remaining $endPath
  515.         $relativePath = $traverser.('' !== $endPathRemainder ? $endPathRemainder.'/' : '');
  517.         return '' === $relativePath ? './' : $relativePath;
  518.     }
  520.     /**
  521.      * Mirrors a directory to another.
  522.      *
  523.      * Copies files and directories from the origin directory into the target directory. By default:
  524.      *
  525.      *  - existing files in the target directory will be overwritten, except if they are newer (see the `override` option)
  526.      *  - files in the target directory that do not exist in the source directory will not be deleted (see the `delete` option)
  527.      *
  528.      * @param \Traversable|null $iterator Iterator that filters which files and directories to copy, if null a recursive iterator is created
  529.      * @param array             $options  An array of boolean options
  530.      *                                    Valid options are:
  531.      *                                    - $options['override'] If true, target files newer than origin files are overwritten (see copy(), defaults to false)
  532.      *                                    - $options['copy_on_windows'] Whether to copy files instead of links on Windows (see symlink(), defaults to false)
  533.      *                                    - $options['delete'] Whether to delete files that are not in the source directory (defaults to false)
  534.      *
  535.      * @throws IOException When file type is unknown
  536.      */
  537.     public function mirror(string $originDir, string $targetDir, \Traversable $iterator = null, array $options = [])
  538.     {
  539.         $targetDir = rtrim($targetDir, '/\\');
  540.         $originDir = rtrim($originDir, '/\\');
  541.         $originDirLen = \strlen($originDir);
  543.         if (!$this->exists($originDir)) {
  544.             throw new IOException(sprintf('The origin directory specified "%s" was not found.', $originDir), 0, null, $originDir);
  545.         }
  547.         // Iterate in destination folder to remove obsolete entries
  548.         if ($this->exists($targetDir) && isset($options['delete']) && $options['delete']) {
  549.             $deleteIterator = $iterator;
  550.             if (null === $deleteIterator) {
  551.                 $flags = \FilesystemIterator::SKIP_DOTS;
  552.                 $deleteIterator = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($targetDir, $flags), \RecursiveIteratorIterator::CHILD_FIRST);
  553.             }
  554.             $targetDirLen = \strlen($targetDir);
  555.             foreach ($deleteIterator as $file) {
  556.                 $origin = $originDir.substr($file->getPathname(), $targetDirLen);
  557.                 if (!$this->exists($origin)) {
  558.                     $this->remove($file);
  559.                 }
  560.             }
  561.         }
  563.         $copyOnWindows = $options['copy_on_windows'] ?? false;
  565.         if (null === $iterator) {
  566.             $flags = $copyOnWindows ? \FilesystemIterator::SKIP_DOTS | \FilesystemIterator::FOLLOW_SYMLINKS : \FilesystemIterator::SKIP_DOTS;
  567.             $iterator = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($originDir, $flags), \RecursiveIteratorIterator::SELF_FIRST);
  568.         }
  570.         $this->mkdir($targetDir);
  571.         $filesCreatedWhileMirroring = [];
  573.         foreach ($iterator as $file) {
  574.             if ($file->getPathname() === $targetDir || $file->getRealPath() === $targetDir || isset($filesCreatedWhileMirroring[$file->getRealPath()])) {
  575.                 continue;
  576.             }
  578.             $target = $targetDir.substr($file->getPathname(), $originDirLen);
  579.             $filesCreatedWhileMirroring[$target] = true;
  581.             if (!$copyOnWindows && is_link($file)) {
  582.                 $this->symlink($file->getLinkTarget(), $target);
  583.             } elseif (is_dir($file)) {
  584.                 $this->mkdir($target);
  585.             } elseif (is_file($file)) {
  586.                 $this->copy($file, $target, $options['override'] ?? false);
  587.             } else {
  588.                 throw new IOException(sprintf('Unable to guess "%s" file type.', $file), 0, null, $file);
  589.             }
  590.         }
  591.     }
  593.     /**
  594.      * Returns whether the file path is an absolute path.
  595.      *
  596.      * @return bool
  597.      */
  598.     public function isAbsolutePath(string $file)
  599.     {
  600.         return '' !== $file && (strspn($file, '/\\', 0, 1)
  601.             || (\strlen($file) > 3 && ctype_alpha($file[0])
  602.                 && ':' === $file[1]
  603.                 && strspn($file, '/\\', 2, 1)
  604.             )
  605.             || null !== parse_url($file, \PHP_URL_SCHEME)
  606.         );
  607.     }
  609.     /**
  610.      * Creates a temporary file with support for custom stream wrappers.
  611.      *
  612.      * @param string $prefix The prefix of the generated temporary filename
  613.      *                       Note: Windows uses only the first three characters of prefix
  614.      * @param string $suffix The suffix of the generated temporary filename
  615.      *
  616.      * @return string The new temporary filename (with path), or throw an exception on failure
  617.      */
  618.     public function tempnam(string $dir, string $prefix/* , string $suffix = '' */)
  619.     {
  620.         $suffix = \func_num_args() > 2 ? func_get_arg(2) : '';
  621.         [$scheme, $hierarchy] = $this->getSchemeAndHierarchy($dir);
  623.         // If no scheme or scheme is "file" or "gs" (Google Cloud) create temp file in local filesystem
  624.         if ((null === $scheme || 'file' === $scheme || 'gs' === $scheme) && '' === $suffix) {
  625.             // If tempnam failed or no scheme return the filename otherwise prepend the scheme
  626.             if ($tmpFile = self::box('tempnam', $hierarchy, $prefix)) {
  627.                 if (null !== $scheme && 'gs' !== $scheme) {
  628.                     return $scheme.'://'.$tmpFile;
  629.                 }
  631.                 return $tmpFile;
  632.             }
  634.             throw new IOException('A temporary file could not be created: '.self::$lastError);
  635.         }
  637.         // Loop until we create a valid temp file or have reached 10 attempts
  638.         for ($i = 0; $i < 10; ++$i) {
  639.             // Create a unique filename
  640.             $tmpFile = $dir.'/'.$prefix.uniqid(mt_rand(), true).$suffix;
  642.             // Use fopen instead of file_exists as some streams do not support stat
  643.             // Use mode 'x+' to atomically check existence and create to avoid a TOCTOU vulnerability
  644.             if (!$handle = self::box('fopen', $tmpFile, 'x+')) {
  645.                 continue;
  646.             }
  648.             // Close the file if it was successfully opened
  649.             self::box('fclose', $handle);
  651.             return $tmpFile;
  652.         }
  654.         throw new IOException('A temporary file could not be created: '.self::$lastError);
  655.     }
  657.     /**
  658.      * Atomically dumps content into a file.
  659.      *
  660.      * @param string|resource $content The data to write into the file
  661.      *
  662.      * @throws IOException if the file cannot be written to
  663.      */
  664.     public function dumpFile(string $filename, $content)
  665.     {
  666.         if (\is_array($content)) {
  667.             throw new \TypeError(sprintf('Argument 2 passed to "%s()" must be string or resource, array given.', __METHOD__));
  668.         }
  670.         $dir = \dirname($filename);
  672.         if (!is_dir($dir)) {
  673.             $this->mkdir($dir);
  674.         }
  676.         // Will create a temp file with 0600 access rights
  677.         // when the filesystem supports chmod.
  678.         $tmpFile = $this->tempnam($dir, basename($filename));
  680.         try {
  681.             if (false === self::box('file_put_contents', $tmpFile, $content)) {
  682.                 throw new IOException(sprintf('Failed to write file "%s": ', $filename).self::$lastError, 0, null, $filename);
  683.             }
  685.             self::box('chmod', $tmpFile, file_exists($filename) ? fileperms($filename) : 0666 & ~umask());
  687.             $this->rename($tmpFile, $filename, true);
  688.         } finally {
  689.             if (file_exists($tmpFile)) {
  690.                 self::box('unlink', $tmpFile);
  691.             }
  692.         }
  693.     }
  695.     /**
  696.      * Appends content to an existing file.
  697.      *
  698.      * @param string|resource $content The content to append
  699.      * @param bool            $lock    Whether the file should be locked when writing to it
  700.      *
  701.      * @throws IOException If the file is not writable
  702.      */
  703.     public function appendToFile(string $filename, $content/* , bool $lock = false */)
  704.     {
  705.         if (\is_array($content)) {
  706.             throw new \TypeError(sprintf('Argument 2 passed to "%s()" must be string or resource, array given.', __METHOD__));
  707.         }
  709.         $dir = \dirname($filename);
  711.         if (!is_dir($dir)) {
  712.             $this->mkdir($dir);
  713.         }
  715.         $lock = \func_num_args() > 2 && func_get_arg(2);
  717.         if (false === self::box('file_put_contents', $filename, $content, \FILE_APPEND | ($lock ? \LOCK_EX : 0))) {
  718.             throw new IOException(sprintf('Failed to write file "%s": ', $filename).self::$lastError, 0, null, $filename);
  719.         }
  720.     }
  722.     private function toIterable($files): iterable
  723.     {
  724.         return is_iterable($files) ? $files : [$files];
  725.     }
  727.     /**
  728.      * Gets a 2-tuple of scheme (may be null) and hierarchical part of a filename (e.g. file:///tmp -> [file, tmp]).
  729.      */
  730.     private function getSchemeAndHierarchy(string $filename): array
  731.     {
  732.         $components = explode('://', $filename, 2);
  734.         return 2 === \count($components) ? [$components[0], $components[1]] : [null, $components[0]];
  735.     }
  737.     private static function assertFunctionExists(string $func): void
  738.     {
  739.         if (!\function_exists($func)) {
  740.             throw new IOException(sprintf('Unable to perform filesystem operation because the "%s()" function has been disabled.', $func));
  741.         }
  742.     }
  744.     /**
  745.      * @param mixed ...$args
  746.      *
  747.      * @return mixed
  748.      */
  749.     private static function box(string $func, ...$args)
  750.     {
  751.         self::assertFunctionExists($func);
  753.         self::$lastError = null;
  754.         set_error_handler(__CLASS__.'::handleError');
  755.         try {
  756.             return $func(...$args);
  757.         } finally {
  758.             restore_error_handler();
  759.         }
  760.     }
  762.     /**
  763.      * @internal
  764.      */
  765.     public static function handleError(int $type, string $msg)
  766.     {
  767.         self::$lastError = $msg;
  768.     }
  769. }