1<?php 2 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 */ 11 12namespace Symfony\Component\Filesystem; 13 14use Symfony\Component\Filesystem\Exception\IOException; 15use Symfony\Component\Filesystem\Exception\FileNotFoundException; 16 17/** 18 * Provides basic utility to manipulate the file system. 19 * 20 * @author Fabien Potencier <fabien@symfony.com> 21 */ 22class Filesystem 23{ 24 /** 25 * Copies a file. 26 * 27 * If the target file is older than the origin file, it's always overwritten. 28 * If the target file is newer, it is overwritten only when the 29 * $overwriteNewerFiles option is set to true. 30 * 31 * @param string $originFile The original filename 32 * @param string $targetFile The target filename 33 * @param bool $overwriteNewerFiles If true, target files newer than origin files are overwritten 34 * 35 * @throws FileNotFoundException When originFile doesn't exist 36 * @throws IOException When copy fails 37 */ 38 public function copy($originFile, $targetFile, $overwriteNewerFiles = false) 39 { 40 $originIsLocal = stream_is_local($originFile) || 0 === stripos($originFile, 'file://'); 41 if ($originIsLocal && !is_file($originFile)) { 42 throw new FileNotFoundException(sprintf('Failed to copy "%s" because file does not exist.', $originFile), 0, null, $originFile); 43 } 44 45 $this->mkdir(dirname($targetFile)); 46 47 $doCopy = true; 48 if (!$overwriteNewerFiles && null === parse_url($originFile, PHP_URL_HOST) && is_file($targetFile)) { 49 $doCopy = filemtime($originFile) > filemtime($targetFile); 50 } 51 52 if ($doCopy) { 53 // https://bugs.php.net/bug.php?id=64634 54 if (false === $source = @fopen($originFile, 'r')) { 55 throw new IOException(sprintf('Failed to copy "%s" to "%s" because source file could not be opened for reading.', $originFile, $targetFile), 0, null, $originFile); 56 } 57 58 // Stream context created to allow files overwrite when using FTP stream wrapper - disabled by default 59 if (false === $target = @fopen($targetFile, 'w', null, stream_context_create(array('ftp' => array('overwrite' => true))))) { 60 throw new IOException(sprintf('Failed to copy "%s" to "%s" because target file could not be opened for writing.', $originFile, $targetFile), 0, null, $originFile); 61 } 62 63 $bytesCopied = stream_copy_to_stream($source, $target); 64 fclose($source); 65 fclose($target); 66 unset($source, $target); 67 68 if (!is_file($targetFile)) { 69 throw new IOException(sprintf('Failed to copy "%s" to "%s".', $originFile, $targetFile), 0, null, $originFile); 70 } 71 72 if ($originIsLocal) { 73 // Like `cp`, preserve executable permission bits 74 @chmod($targetFile, fileperms($targetFile) | (fileperms($originFile) & 0111)); 75 76 if ($bytesCopied !== $bytesOrigin = filesize($originFile)) { 77 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); 78 } 79 } 80 } 81 } 82 83 /** 84 * Creates a directory recursively. 85 * 86 * @param string|iterable $dirs The directory path 87 * @param int $mode The directory mode 88 * 89 * @throws IOException On any directory creation failure 90 */ 91 public function mkdir($dirs, $mode = 0777) 92 { 93 foreach ($this->toIterator($dirs) as $dir) { 94 if (is_dir($dir)) { 95 continue; 96 } 97 98 if (true !== @mkdir($dir, $mode, true)) { 99 $error = error_get_last(); 100 if (!is_dir($dir)) { 101 // The directory was not created by a concurrent process. Let's throw an exception with a developer friendly error message if we have one 102 if ($error) { 103 throw new IOException(sprintf('Failed to create "%s": %s.', $dir, $error['message']), 0, null, $dir); 104 } 105 throw new IOException(sprintf('Failed to create "%s"', $dir), 0, null, $dir); 106 } 107 } 108 } 109 } 110 111 /** 112 * Checks the existence of files or directories. 113 * 114 * @param string|iterable $files A filename, an array of files, or a \Traversable instance to check 115 * 116 * @return bool true if the file exists, false otherwise 117 */ 118 public function exists($files) 119 { 120 $maxPathLength = PHP_MAXPATHLEN - 2; 121 122 foreach ($this->toIterator($files) as $file) { 123 if (strlen($file) > $maxPathLength) { 124 throw new IOException(sprintf('Could not check if file exist because path length exceeds %d characters.', $maxPathLength), 0, null, $file); 125 } 126 127 if (!file_exists($file)) { 128 return false; 129 } 130 } 131 132 return true; 133 } 134 135 /** 136 * Sets access and modification time of file. 137 * 138 * @param string|iterable $files A filename, an array of files, or a \Traversable instance to create 139 * @param int $time The touch time as a Unix timestamp 140 * @param int $atime The access time as a Unix timestamp 141 * 142 * @throws IOException When touch fails 143 */ 144 public function touch($files, $time = null, $atime = null) 145 { 146 foreach ($this->toIterator($files) as $file) { 147 $touch = $time ? @touch($file, $time, $atime) : @touch($file); 148 if (true !== $touch) { 149 throw new IOException(sprintf('Failed to touch "%s".', $file), 0, null, $file); 150 } 151 } 152 } 153 154 /** 155 * Removes files or directories. 156 * 157 * @param string|iterable $files A filename, an array of files, or a \Traversable instance to remove 158 * 159 * @throws IOException When removal fails 160 */ 161 public function remove($files) 162 { 163 if ($files instanceof \Traversable) { 164 $files = iterator_to_array($files, false); 165 } elseif (!is_array($files)) { 166 $files = array($files); 167 } 168 $files = array_reverse($files); 169 foreach ($files as $file) { 170 if (is_link($file)) { 171 // See https://bugs.php.net/52176 172 if (!@(unlink($file) || '\\' !== DIRECTORY_SEPARATOR || rmdir($file)) && file_exists($file)) { 173 $error = error_get_last(); 174 throw new IOException(sprintf('Failed to remove symlink "%s": %s.', $file, $error['message'])); 175 } 176 } elseif (is_dir($file)) { 177 $this->remove(new \FilesystemIterator($file, \FilesystemIterator::CURRENT_AS_PATHNAME | \FilesystemIterator::SKIP_DOTS)); 178 179 if (!@rmdir($file) && file_exists($file)) { 180 $error = error_get_last(); 181 throw new IOException(sprintf('Failed to remove directory "%s": %s.', $file, $error['message'])); 182 } 183 } elseif (!@unlink($file) && file_exists($file)) { 184 $error = error_get_last(); 185 throw new IOException(sprintf('Failed to remove file "%s": %s.', $file, $error['message'])); 186 } 187 } 188 } 189 190 /** 191 * Change mode for an array of files or directories. 192 * 193 * @param string|iterable $files A filename, an array of files, or a \Traversable instance to change mode 194 * @param int $mode The new mode (octal) 195 * @param int $umask The mode mask (octal) 196 * @param bool $recursive Whether change the mod recursively or not 197 * 198 * @throws IOException When the change fail 199 */ 200 public function chmod($files, $mode, $umask = 0000, $recursive = false) 201 { 202 foreach ($this->toIterator($files) as $file) { 203 if (true !== @chmod($file, $mode & ~$umask)) { 204 throw new IOException(sprintf('Failed to chmod file "%s".', $file), 0, null, $file); 205 } 206 if ($recursive && is_dir($file) && !is_link($file)) { 207 $this->chmod(new \FilesystemIterator($file), $mode, $umask, true); 208 } 209 } 210 } 211 212 /** 213 * Change the owner of an array of files or directories. 214 * 215 * @param string|iterable $files A filename, an array of files, or a \Traversable instance to change owner 216 * @param string $user The new owner user name 217 * @param bool $recursive Whether change the owner recursively or not 218 * 219 * @throws IOException When the change fail 220 */ 221 public function chown($files, $user, $recursive = false) 222 { 223 foreach ($this->toIterator($files) as $file) { 224 if ($recursive && is_dir($file) && !is_link($file)) { 225 $this->chown(new \FilesystemIterator($file), $user, true); 226 } 227 if (is_link($file) && function_exists('lchown')) { 228 if (true !== @lchown($file, $user)) { 229 throw new IOException(sprintf('Failed to chown file "%s".', $file), 0, null, $file); 230 } 231 } else { 232 if (true !== @chown($file, $user)) { 233 throw new IOException(sprintf('Failed to chown file "%s".', $file), 0, null, $file); 234 } 235 } 236 } 237 } 238 239 /** 240 * Change the group of an array of files or directories. 241 * 242 * @param string|iterable $files A filename, an array of files, or a \Traversable instance to change group 243 * @param string $group The group name 244 * @param bool $recursive Whether change the group recursively or not 245 * 246 * @throws IOException When the change fail 247 */ 248 public function chgrp($files, $group, $recursive = false) 249 { 250 foreach ($this->toIterator($files) as $file) { 251 if ($recursive && is_dir($file) && !is_link($file)) { 252 $this->chgrp(new \FilesystemIterator($file), $group, true); 253 } 254 if (is_link($file) && function_exists('lchgrp')) { 255 if (true !== @lchgrp($file, $group) || (defined('HHVM_VERSION') && !posix_getgrnam($group))) { 256 throw new IOException(sprintf('Failed to chgrp file "%s".', $file), 0, null, $file); 257 } 258 } else { 259 if (true !== @chgrp($file, $group)) { 260 throw new IOException(sprintf('Failed to chgrp file "%s".', $file), 0, null, $file); 261 } 262 } 263 } 264 } 265 266 /** 267 * Renames a file or a directory. 268 * 269 * @param string $origin The origin filename or directory 270 * @param string $target The new filename or directory 271 * @param bool $overwrite Whether to overwrite the target if it already exists 272 * 273 * @throws IOException When target file or directory already exists 274 * @throws IOException When origin cannot be renamed 275 */ 276 public function rename($origin, $target, $overwrite = false) 277 { 278 // we check that target does not exist 279 if (!$overwrite && $this->isReadable($target)) { 280 throw new IOException(sprintf('Cannot rename because the target "%s" already exists.', $target), 0, null, $target); 281 } 282 283 if (true !== @rename($origin, $target)) { 284 if (is_dir($origin)) { 285 // See https://bugs.php.net/bug.php?id=54097 & http://php.net/manual/en/function.rename.php#113943 286 $this->mirror($origin, $target, null, array('override' => $overwrite, 'delete' => $overwrite)); 287 $this->remove($origin); 288 289 return; 290 } 291 throw new IOException(sprintf('Cannot rename "%s" to "%s".', $origin, $target), 0, null, $target); 292 } 293 } 294 295 /** 296 * Tells whether a file exists and is readable. 297 * 298 * @param string $filename Path to the file 299 * 300 * @return bool 301 * 302 * @throws IOException When windows path is longer than 258 characters 303 */ 304 private function isReadable($filename) 305 { 306 $maxPathLength = PHP_MAXPATHLEN - 2; 307 308 if (strlen($filename) > $maxPathLength) { 309 throw new IOException(sprintf('Could not check if file is readable because path length exceeds %d characters.', $maxPathLength), 0, null, $filename); 310 } 311 312 return is_readable($filename); 313 } 314 315 /** 316 * Creates a symbolic link or copy a directory. 317 * 318 * @param string $originDir The origin directory path 319 * @param string $targetDir The symbolic link name 320 * @param bool $copyOnWindows Whether to copy files if on Windows 321 * 322 * @throws IOException When symlink fails 323 */ 324 public function symlink($originDir, $targetDir, $copyOnWindows = false) 325 { 326 if ('\\' === DIRECTORY_SEPARATOR) { 327 $originDir = strtr($originDir, '/', '\\'); 328 $targetDir = strtr($targetDir, '/', '\\'); 329 330 if ($copyOnWindows) { 331 $this->mirror($originDir, $targetDir); 332 333 return; 334 } 335 } 336 337 $this->mkdir(dirname($targetDir)); 338 339 $ok = false; 340 if (is_link($targetDir)) { 341 if (readlink($targetDir) != $originDir) { 342 $this->remove($targetDir); 343 } else { 344 $ok = true; 345 } 346 } 347 348 if (!$ok && true !== @symlink($originDir, $targetDir)) { 349 $report = error_get_last(); 350 if (is_array($report)) { 351 if ('\\' === DIRECTORY_SEPARATOR && false !== strpos($report['message'], 'error code(1314)')) { 352 throw new IOException('Unable to create symlink due to error code 1314: \'A required privilege is not held by the client\'. Do you have the required Administrator-rights?', 0, null, $targetDir); 353 } 354 } 355 throw new IOException(sprintf('Failed to create symbolic link from "%s" to "%s".', $originDir, $targetDir), 0, null, $targetDir); 356 } 357 } 358 359 /** 360 * Given an existing path, convert it to a path relative to a given starting path. 361 * 362 * @param string $endPath Absolute path of target 363 * @param string $startPath Absolute path where traversal begins 364 * 365 * @return string Path of target relative to starting path 366 */ 367 public function makePathRelative($endPath, $startPath) 368 { 369 // Normalize separators on Windows 370 if ('\\' === DIRECTORY_SEPARATOR) { 371 $endPath = str_replace('\\', '/', $endPath); 372 $startPath = str_replace('\\', '/', $startPath); 373 } 374 375 $stripDriveLetter = function ($path) { 376 if (strlen($path) > 2 && ':' === $path[1] && '/' === $path[2] && ctype_alpha($path[0])) { 377 return substr($path, 2); 378 } 379 380 return $path; 381 }; 382 383 $endPath = $stripDriveLetter($endPath); 384 $startPath = $stripDriveLetter($startPath); 385 386 // Split the paths into arrays 387 $startPathArr = explode('/', trim($startPath, '/')); 388 $endPathArr = explode('/', trim($endPath, '/')); 389 390 $normalizePathArray = function ($pathSegments, $absolute) { 391 $result = array(); 392 393 foreach ($pathSegments as $segment) { 394 if ('..' === $segment && ($absolute || count($result))) { 395 array_pop($result); 396 } elseif ('.' !== $segment) { 397 $result[] = $segment; 398 } 399 } 400 401 return $result; 402 }; 403 404 $startPathArr = $normalizePathArray($startPathArr, static::isAbsolutePath($startPath)); 405 $endPathArr = $normalizePathArray($endPathArr, static::isAbsolutePath($endPath)); 406 407 // Find for which directory the common path stops 408 $index = 0; 409 while (isset($startPathArr[$index]) && isset($endPathArr[$index]) && $startPathArr[$index] === $endPathArr[$index]) { 410 ++$index; 411 } 412 413 // Determine how deep the start path is relative to the common path (ie, "web/bundles" = 2 levels) 414 if (1 === count($startPathArr) && '' === $startPathArr[0]) { 415 $depth = 0; 416 } else { 417 $depth = count($startPathArr) - $index; 418 } 419 420 // Repeated "../" for each level need to reach the common path 421 $traverser = str_repeat('../', $depth); 422 423 $endPathRemainder = implode('/', array_slice($endPathArr, $index)); 424 425 // Construct $endPath from traversing to the common path, then to the remaining $endPath 426 $relativePath = $traverser.('' !== $endPathRemainder ? $endPathRemainder.'/' : ''); 427 428 return '' === $relativePath ? './' : $relativePath; 429 } 430 431 /** 432 * Mirrors a directory to another. 433 * 434 * Copies files and directories from the origin directory into the target directory. By default: 435 * 436 * - existing files in the target directory will be overwritten, except if they are newer (see the `override` option) 437 * - files in the target directory that do not exist in the source directory will not be deleted (see the `delete` option) 438 * 439 * @param string $originDir The origin directory 440 * @param string $targetDir The target directory 441 * @param \Traversable $iterator Iterator that filters which files and directories to copy 442 * @param array $options An array of boolean options 443 * Valid options are: 444 * - $options['override'] If true, target files newer than origin files are overwritten (see copy(), defaults to false) 445 * - $options['copy_on_windows'] Whether to copy files instead of links on Windows (see symlink(), defaults to false) 446 * - $options['delete'] Whether to delete files that are not in the source directory (defaults to false) 447 * 448 * @throws IOException When file type is unknown 449 */ 450 public function mirror($originDir, $targetDir, \Traversable $iterator = null, $options = array()) 451 { 452 $targetDir = rtrim($targetDir, '/\\'); 453 $originDir = rtrim($originDir, '/\\'); 454 $originDirLen = strlen($originDir); 455 456 // Iterate in destination folder to remove obsolete entries 457 if ($this->exists($targetDir) && isset($options['delete']) && $options['delete']) { 458 $deleteIterator = $iterator; 459 if (null === $deleteIterator) { 460 $flags = \FilesystemIterator::SKIP_DOTS; 461 $deleteIterator = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($targetDir, $flags), \RecursiveIteratorIterator::CHILD_FIRST); 462 } 463 $targetDirLen = strlen($targetDir); 464 foreach ($deleteIterator as $file) { 465 $origin = $originDir.substr($file->getPathname(), $targetDirLen); 466 if (!$this->exists($origin)) { 467 $this->remove($file); 468 } 469 } 470 } 471 472 $copyOnWindows = false; 473 if (isset($options['copy_on_windows'])) { 474 $copyOnWindows = $options['copy_on_windows']; 475 } 476 477 if (null === $iterator) { 478 $flags = $copyOnWindows ? \FilesystemIterator::SKIP_DOTS | \FilesystemIterator::FOLLOW_SYMLINKS : \FilesystemIterator::SKIP_DOTS; 479 $iterator = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($originDir, $flags), \RecursiveIteratorIterator::SELF_FIRST); 480 } 481 482 if ($this->exists($originDir)) { 483 $this->mkdir($targetDir); 484 } 485 486 foreach ($iterator as $file) { 487 $target = $targetDir.substr($file->getPathname(), $originDirLen); 488 489 if ($copyOnWindows) { 490 if (is_file($file)) { 491 $this->copy($file, $target, isset($options['override']) ? $options['override'] : false); 492 } elseif (is_dir($file)) { 493 $this->mkdir($target); 494 } else { 495 throw new IOException(sprintf('Unable to guess "%s" file type.', $file), 0, null, $file); 496 } 497 } else { 498 if (is_link($file)) { 499 $this->symlink($file->getLinkTarget(), $target); 500 } elseif (is_dir($file)) { 501 $this->mkdir($target); 502 } elseif (is_file($file)) { 503 $this->copy($file, $target, isset($options['override']) ? $options['override'] : false); 504 } else { 505 throw new IOException(sprintf('Unable to guess "%s" file type.', $file), 0, null, $file); 506 } 507 } 508 } 509 } 510 511 /** 512 * Returns whether the file path is an absolute path. 513 * 514 * @param string $file A file path 515 * 516 * @return bool 517 */ 518 public function isAbsolutePath($file) 519 { 520 return strspn($file, '/\\', 0, 1) 521 || (strlen($file) > 3 && ctype_alpha($file[0]) 522 && ':' === substr($file, 1, 1) 523 && strspn($file, '/\\', 2, 1) 524 ) 525 || null !== parse_url($file, PHP_URL_SCHEME) 526 ; 527 } 528 529 /** 530 * Creates a temporary file with support for custom stream wrappers. 531 * 532 * @param string $dir The directory where the temporary filename will be created 533 * @param string $prefix The prefix of the generated temporary filename 534 * Note: Windows uses only the first three characters of prefix 535 * 536 * @return string The new temporary filename (with path), or throw an exception on failure 537 */ 538 public function tempnam($dir, $prefix) 539 { 540 list($scheme, $hierarchy) = $this->getSchemeAndHierarchy($dir); 541 542 // If no scheme or scheme is "file" or "gs" (Google Cloud) create temp file in local filesystem 543 if (null === $scheme || 'file' === $scheme || 'gs' === $scheme) { 544 $tmpFile = @tempnam($hierarchy, $prefix); 545 546 // If tempnam failed or no scheme return the filename otherwise prepend the scheme 547 if (false !== $tmpFile) { 548 if (null !== $scheme && 'gs' !== $scheme) { 549 return $scheme.'://'.$tmpFile; 550 } 551 552 return $tmpFile; 553 } 554 555 throw new IOException('A temporary file could not be created.'); 556 } 557 558 // Loop until we create a valid temp file or have reached 10 attempts 559 for ($i = 0; $i < 10; ++$i) { 560 // Create a unique filename 561 $tmpFile = $dir.'/'.$prefix.uniqid(mt_rand(), true); 562 563 // Use fopen instead of file_exists as some streams do not support stat 564 // Use mode 'x+' to atomically check existence and create to avoid a TOCTOU vulnerability 565 $handle = @fopen($tmpFile, 'x+'); 566 567 // If unsuccessful restart the loop 568 if (false === $handle) { 569 continue; 570 } 571 572 // Close the file if it was successfully opened 573 @fclose($handle); 574 575 return $tmpFile; 576 } 577 578 throw new IOException('A temporary file could not be created.'); 579 } 580 581 /** 582 * Atomically dumps content into a file. 583 * 584 * @param string $filename The file to be written to 585 * @param string $content The data to write into the file 586 * @param null|int $mode The file mode (octal). If null, file permissions are not modified 587 * Deprecated since version 2.3.12, to be removed in 3.0. 588 * 589 * @throws IOException if the file cannot be written to 590 */ 591 public function dumpFile($filename, $content, $mode = 0666) 592 { 593 $dir = dirname($filename); 594 595 if (!is_dir($dir)) { 596 $this->mkdir($dir); 597 } 598 599 if (!is_writable($dir)) { 600 throw new IOException(sprintf('Unable to write to the "%s" directory.', $dir), 0, null, $dir); 601 } 602 603 $tmpFile = $this->tempnam($dir, basename($filename)); 604 605 if (false === @file_put_contents($tmpFile, $content)) { 606 throw new IOException(sprintf('Failed to write file "%s".', $filename), 0, null, $filename); 607 } 608 609 if (null !== $mode) { 610 if (func_num_args() > 2) { 611 @trigger_error('Support for modifying file permissions is deprecated since Symfony 2.3.12 and will be removed in 3.0.', E_USER_DEPRECATED); 612 } 613 614 $this->chmod($tmpFile, $mode); 615 } elseif (file_exists($filename)) { 616 @chmod($tmpFile, fileperms($filename)); 617 } 618 619 $this->rename($tmpFile, $filename, true); 620 } 621 622 /** 623 * @param mixed $files 624 * 625 * @return \Traversable 626 */ 627 private function toIterator($files) 628 { 629 if (!$files instanceof \Traversable) { 630 $files = new \ArrayObject(is_array($files) ? $files : array($files)); 631 } 632 633 return $files; 634 } 635 636 /** 637 * Gets a 2-tuple of scheme (may be null) and hierarchical part of a filename (e.g. file:///tmp -> array(file, tmp)). 638 * 639 * @param string $filename The filename to be parsed 640 * 641 * @return array The filename scheme and hierarchical part 642 */ 643 private function getSchemeAndHierarchy($filename) 644 { 645 $components = explode('://', $filename, 2); 646 647 return 2 === count($components) ? array($components[0], $components[1]) : array(null, $components[0]); 648 } 649} 650