vendor/symfony/filesystem/Filesystem.php line 694

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