File Toolkit/Utility/File.php | salient/toolkit API

1:	<?php declare(strict_types=1);
2:
3:	namespace Salient\Utility;
4:
5:	use Salient\Core\Process;
6:	use Salient\Iterator\FileIterator;
7:	use Salient\Utility\Exception\FilesystemErrorException;
8:	use Salient\Utility\Exception\InvalidRuntimeConfigurationException;
9:	use Salient\Utility\Exception\UnreadDataException;
10:	use Salient\Utility\Exception\UnwrittenDataException;
11:	use Salient\Utility\Internal\IndentationGuesser;
12:	use Salient\Utility\Support\Indentation;
13:	use InvalidArgumentException;
14:	use Stringable;
15:
16:	/**
17:	* Work with files, streams and paths
18:	*
19:	* Methods with an optional `$uri` parameter allow the default resource URI
20:	* reported on failure to be overridden.
21:	*
22:	* @api
23:	*/
24:	final class File extends AbstractUtility
25:	{
26:	/**
27:	* Check if a path is absolute without accessing the filesystem
28:	*
29:	* Returns `true` if `$path` starts with `/`, `\\`, `<letter>:\`,
30:	* `<letter>:/` or a URI scheme with two or more characters.
31:	*/
32:	public static function isAbsolute(string $path): bool
33:	{
34:	return (bool) Regex::match(
35:	'@^(?:/\|\\\\\\\\\|[a-z]:[/\\\\]\|[a-z][-a-z0-9+.]+:)@i',
36:	$path,
37:	);
38:	}
39:
40:	/**
41:	* Resolve "/./" and "/../" segments in a path without accessing the
42:	* filesystem
43:	*
44:	* If `$withUriSegments` is `true`, `"/../"` segments after empty segments
45:	* (e.g. `"/dir1/dir2//../"`) are resolved by removing an empty segment,
46:	* otherwise consecutive directory separators are treated as one separator.
47:	*/
48:	public static function resolvePath(string $path, bool $withUriSegments = false): string
49:	{
50:	$path = str_replace('\\', '/', $path);
51:
52:	// Remove "/./" segments
53:	$path = Regex::replace('@(?<=/\|^)\.(?:/\|$)@', '', $path);
54:
55:	// Remove "/../" segments
56:	$regex = $withUriSegments ? '/' : '/+';
57:	$regex = "@(?:^\|(?<=^/)\|(?<=/\|^(?!/))(?!\.\.(?:/\|\$))[^/]*{$regex})\.\.(?:/\|\$)@";
58:	do {
59:	$path = Regex::replace($regex, '', $path, -1, $count);
60:	} while ($count);
61:
62:	return $path;
63:	}
64:
65:	/**
66:	* Sanitise the path to a directory without accessing the filesystem
67:	*
68:	* Returns `"."` if `$directory` is an empty string, otherwise removes
69:	* trailing directory separators.
70:	*/
71:	public static function sanitiseDir(string $directory): string
72:	{
73:	return $directory === ''
74:	? '.'
75:	: Str::coalesce(
76:	rtrim($directory, \DIRECTORY_SEPARATOR === '/' ? '/' : '\/'),
77:	\DIRECTORY_SEPARATOR,
78:	);
79:	}
80:
81:	/**
82:	* Change the current directory
83:	*/
84:	public static function chdir(string $directory): void
85:	{
86:	self::check(@chdir($directory), 'chdir', $directory);
87:	}
88:
89:	/**
90:	* Create a directory
91:	*/
92:	public static function mkdir(
93:	string $directory,
94:	int $permissions = 0777,
95:	bool $recursive = false
96:	): void {
97:	self::check(@mkdir($directory, $permissions, $recursive), 'mkdir', $directory);
98:	}
99:
100:	/**
101:	* Change file permissions
102:	*/
103:	public static function chmod(string $filename, int $permissions): void
104:	{
105:	self::check(@chmod($filename, $permissions), 'chmod', $filename);
106:	}
107:
108:	/**
109:	* Rename a file or directory
110:	*/
111:	public static function rename(string $from, string $to): void
112:	{
113:	self::check(@rename($from, $to), 'rename', null, null, $from, $to);
114:	}
115:
116:	/**
117:	* Create a symbolic link to a target with a given name
118:	*/
119:	public static function symlink(string $target, string $link): void
120:	{
121:	self::check(@symlink($target, $link), 'symlink', null, null, $target, $link);
122:	}
123:
124:	/**
125:	* Set file access and modification times
126:	*/
127:	public static function touch(
128:	string $filename,
129:	?int $mtime = null,
130:	?int $atime = null
131:	): void {
132:	$mtime ??= time();
133:	$atime ??= $mtime;
134:	self::check(@touch($filename, $mtime, $atime), 'touch', $filename);
135:	}
136:
137:	/**
138:	* Get a path or its closest parent that exists
139:	*
140:	* Returns `null` if the leftmost segment of `$path` doesn't exist, or if
141:	* the closest parent that exists is not a directory.
142:	*/
143:	public static function getClosestPath(string $path): ?string
144:	{
145:	$pathIsParent = false;
146:	while (!file_exists($path)) {
147:	$parent = dirname($path);
148:	if ($parent === $path) {
149:	// @codeCoverageIgnoreStart
150:	return null;
151:	// @codeCoverageIgnoreEnd
152:	}
153:	$path = $parent;
154:	$pathIsParent = true;
155:	}
156:
157:	if ($pathIsParent && !is_dir($path)) {
158:	return null;
159:	}
160:
161:	return $path;
162:	}
163:
164:	/**
165:	* Safely create a file if it doesn't exist
166:	*
167:	* @param int $permissions Applied if `$filename` is created.
168:	* @param int $dirPermissions Applied if `$filename`'s directory is created.
169:	* Parent directories, if any, are created with file mode `0777 & ~umask()`,
170:	* or `0755` if `$umaskApplies` is `false`.
171:	*/
172:	public static function create(
173:	string $filename,
174:	int $permissions = 0777,
175:	int $dirPermissions = 0777,
176:	bool $umaskApplies = true
177:	): void {
178:	if (is_file($filename)) {
179:	return;
180:	}
181:	self::createDir(dirname($filename), $dirPermissions, $umaskApplies);
182:	$umask = umask();
183:	if ($umaskApplies) {
184:	$permissions &= ~$umask;
185:	}
186:	try {
187:	// Create the file without group or other permissions to prevent
188:	// access by a bad actor before permissions are set
189:	umask(077);
190:	$handle = self::open($filename, 'x');
191:	self::chmod($filename, $permissions);
192:	self::close($handle, $filename);
193:	} finally {
194:	umask($umask);
195:	}
196:	}
197:
198:	/**
199:	* Safely create a directory if it doesn't exist
200:	*
201:	* @param int $permissions Applied if `$directory` is created. Parent
202:	* directories, if any, are created with file mode `0777 & ~umask()`, or
203:	* `0755` if `$umaskApplies` is `false`.
204:	*/
205:	public static function createDir(
206:	string $directory,
207:	int $permissions = 0777,
208:	bool $umaskApplies = true
209:	): void {
210:	if (is_dir($directory)) {
211:	return;
212:	}
213:	$parent = dirname($directory);
214:	$umask = umask();
215:	if ($umaskApplies) {
216:	$permissions &= ~$umask;
217:	}
218:	try {
219:	if (!is_dir($parent)) {
220:	umask(0);
221:	$parentPerms = $umaskApplies
222:	? 0777 & ~$umask
223:	: 0755;
224:	self::mkdir($parent, $parentPerms, true);
225:	}
226:	umask(077);
227:	self::mkdir($directory);
228:	self::chmod($directory, $permissions);
229:	} finally {
230:	umask($umask);
231:	}
232:	}
233:
234:	/**
235:	* Create a temporary file with mode 0600
236:	*
237:	* @param string\|null $directory If `null`, the directory returned by
238:	* `sys_get_temp_dir()` is used.
239:	* @param string\|null $prefix If `null`, the basename of the file used to
240:	* run the script is used.
241:	*/
242:	public static function createTemp(
243:	?string $directory = null,
244:	?string $prefix = null
245:	): string {
246:	if ($directory !== null) {
247:	$directory = self::sanitiseDir($directory);
248:	if (!is_dir($directory) \|\| !is_writable($directory)) {
249:	throw new FilesystemErrorException(sprintf(
250:	'Not a writable directory: %s',
251:	$directory,
252:	));
253:	}
254:	}
255:	return self::check(@tempnam(
256:	$directory ?? Sys::getTempDir(),
257:	$prefix ?? Sys::getProgramBasename(),
258:	), 'tempnam');
259:	}
260:
261:	/**
262:	* Create a temporary directory with file mode 0700
263:	*
264:	* @param string\|null $directory If `null`, the directory returned by
265:	* `sys_get_temp_dir()` is used.
266:	* @param string\|null $prefix If `null`, the basename of the file used to
267:	* run the script is used.
268:	*/
269:	public static function createTempDir(
270:	?string $directory = null,
271:	?string $prefix = null
272:	): string {
273:	if ($directory !== null) {
274:	$directory = self::sanitiseDir($directory);
275:	}
276:	$directory ??= Sys::getTempDir();
277:	$prefix ??= Sys::getProgramBasename();
278:	$failed = false;
279:	do {
280:	if ($failed) {
281:	clearstatcache();
282:	if (!is_dir($directory) \|\| !is_writable($directory)) {
283:	throw new FilesystemErrorException(sprintf(
284:	'Not a writable directory: %s',
285:	$directory,
286:	));
287:	}
288:	usleep(10000);
289:	}
290:	$dir = sprintf(
291:	'%s/%s%s.tmp',
292:	$directory,
293:	$prefix,
294:	Get::randomText(8),
295:	);
296:	$failed = !@mkdir($dir, 0700);
297:	} while ($failed);
298:	self::chmod($dir, 0700);
299:	return $dir;
300:	}
301:
302:	/**
303:	* Delete a file if it exists
304:	*/
305:	public static function delete(string $filename): void
306:	{
307:	if (!file_exists($filename)) {
308:	return;
309:	}
310:	if (!is_file($filename)) {
311:	throw new FilesystemErrorException(
312:	sprintf('Not a file: %s', $filename),
313:	);
314:	}
315:	self::check(@unlink($filename), 'unlink', $filename);
316:	}
317:
318:	/**
319:	* Delete a directory if it exists
320:	*/
321:	public static function deleteDir(string $directory): void
322:	{
323:	if (!file_exists($directory)) {
324:	return;
325:	}
326:	if (!is_dir($directory)) {
327:	throw new FilesystemErrorException(
328:	sprintf('Not a directory: %s', $directory),
329:	);
330:	}
331:	self::check(@rmdir($directory), 'rmdir', $directory);
332:	}
333:
334:	/**
335:	* Iterate over filesystem entries
336:	*/
337:	public static function find(): FileIterator
338:	{
339:	return new FileIterator();
340:	}
341:
342:	/**
343:	* Get the current working directory without resolving symbolic links
344:	*/
345:	public static function getcwd(): string
346:	{
347:	$command = Sys::isWindows() ? 'cd' : 'pwd';
348:	if (class_exists(Process::class)) {
349:	$process = Process::withShellCommand($command);
350:	if ($process->run() === 0) {
351:	return $process->getOutputAsText();
352:	}
353:	} else {
354:	// @codeCoverageIgnoreStart
355:	$pipe = self::openPipe($command, 'r');
356:	$dir = self::getContents($pipe);
357:	if (self::closePipe($pipe, $command) === 0) {
358:	return Str::trimNativeEol($dir);
359:	}
360:	// @codeCoverageIgnoreEnd
361:	}
362:	error_clear_last();
363:	return self::check(@getcwd(), 'getcwd');
364:	}
365:
366:	/**
367:	* Check if a path exists and is writable, or doesn't exist but descends
368:	* from a writable directory
369:	*/
370:	public static function isCreatable(string $path): bool
371:	{
372:	$path = self::getClosestPath($path);
373:	return $path !== null && is_writable($path);
374:	}
375:
376:	/**
377:	* Recursively delete the contents of a directory before optionally deleting
378:	* the directory itself
379:	*
380:	* If `$setPermissions` is `true`, file modes in `$directory` are changed if
381:	* necessary for deletion to succeed.
382:	*/
383:	public static function pruneDir(string $directory, bool $delete = false, bool $setPermissions = false): void
384:	{
385:	$files = (new FileIterator())->in($directory);
386:
387:	if ($setPermissions) {
388:	clearstatcache();
389:	// With exceptions `chmod()` can't address:
390:	// - On *nix, filesystem entries can be deleted if their parent
391:	// directory is writable
392:	// - On Windows, they can be deleted if they are writable, whether
393:	// their parent directory is writable or not
394:	if (!Sys::isWindows()) {
395:	foreach ($files->directories() as $dir) {
396:	if (
397:	$dir->isReadable()
398:	&& $dir->isWritable()
399:	&& $dir->isExecutable()
400:	) {
401:	continue;
402:	}
403:	$perms = @$dir->getPerms();
404:	if ($perms === false) {
405:	// @codeCoverageIgnoreStart
406:	$perms = 0;
407:	// @codeCoverageIgnoreEnd
408:	}
409:	self::chmod((string) $dir, $perms \| 0700);
410:	}
411:	$setPermissions = false;
412:	}
413:	}
414:
415:	foreach ($files->directoriesLast() as $file) {
416:	$filename = (string) $file;
417:	if ($setPermissions && !$file->isWritable()) {
418:	// This will only ever run on Windows
419:	self::chmod($filename, $file->isDir() ? 0700 : 0600);
420:	}
421:	if ($file->isDir()) {
422:	self::check(@rmdir($filename), 'rmdir', $filename);
423:	} else {
424:	self::check(@unlink($filename), 'unlink', $filename);
425:	}
426:	}
427:
428:	if ($delete) {
429:	self::check(@rmdir($directory), 'rmdir', $directory);
430:	}
431:	}
432:
433:	/**
434:	* Resolve symbolic links and relative references in a path or Phar URI
435:	*
436:	* An exception is thrown if `$path` does not exist.
437:	*/
438:	public static function realpath(string $path): string
439:	{
440:	if (Str::lower(substr($path, 0, 7)) === 'phar://' && file_exists($path)) {
441:	return self::resolvePath($path, true);
442:	}
443:	error_clear_last();
444:	return self::check(@realpath($path), 'realpath', $path);
445:	}
446:
447:	/**
448:	* Get a path relative to a parent directory
449:	*
450:	* Returns `$default` if `$path` does not belong to `$parentDirectory`.
451:	*
452:	* An exception is thrown if `$path` or `$parentDirectory` do not exist.
453:	*
454:	* @template TDefault of string\|null
455:	*
456:	* @param TDefault $default
457:	* @return string\|TDefault
458:	*/
459:	public static function getRelativePath(
460:	string $path,
461:	string $parentDirectory,
462:	?string $default = null
463:	): ?string {
464:	$path = self::realpath($path);
465:	$basePath = self::realpath($parentDirectory);
466:	if (strpos($path, $basePath) === 0) {
467:	return substr($path, strlen($basePath) + 1);
468:	}
469:	return $default;
470:	}
471:
472:	/**
473:	* Check if two paths refer to the same filesystem entry
474:	*/
475:	public static function same(string $filename1, string $filename2): bool
476:	{
477:	if (!file_exists($filename1)) {
478:	return false;
479:	}
480:	if ($filename1 === $filename2) {
481:	return true;
482:	}
483:	if (!file_exists($filename2)) {
484:	return false;
485:	}
486:	$stat1 = self::stat($filename1);
487:	$stat2 = self::stat($filename2);
488:	return $stat1['dev'] === $stat2['dev']
489:	&& $stat1['ino'] === $stat2['ino'];
490:	}
491:
492:	/**
493:	* Get a unique identifier for a file from its device and inode numbers
494:	*/
495:	public static function getIdentifier(string $filename): string
496:	{
497:	$stat = self::stat($filename);
498:	return sprintf('%d:%d', $stat['dev'], $stat['ino']);
499:	}
500:
501:	/**
502:	* Get the size of a file
503:	*/
504:	public static function size(string $filename): int
505:	{
506:	return self::check(@filesize($filename), 'filesize', $filename);
507:	}
508:
509:	/**
510:	* Get the type of a file
511:	*
512:	* @return ("fifo"\|"char"\|"dir"\|"block"\|"link"\|"file"\|"socket"\|"unknown")
513:	*/
514:	public static function type(string $filename): string
515:	{
516:	/** @var ("fifo"\|"char"\|"dir"\|"block"\|"link"\|"file"\|"socket"\|"unknown") */
517:	return self::check(@filetype($filename), 'filetype', $filename);
518:	}
519:
520:	/**
521:	* Write data to a file
522:	*
523:	* @param resource\|array<int\|float\|string\|bool\|Stringable\|null>\|string $data
524:	* @param int-mask-of<\FILE_USE_INCLUDE_PATH\|\FILE_APPEND\|\LOCK_EX> $flags
525:	*/
526:	public static function writeContents(string $filename, $data, int $flags = 0): int
527:	{
528:	return self::check(@file_put_contents($filename, $data, $flags), 'file_put_contents', $filename);
529:	}
530:
531:	/**
532:	* Check for errors after fgets(), fgetcsv(), etc. return false
533:	*
534:	* @param resource $stream
535:	* @param Stringable\|string\|null $uri
536:	*/
537:	public static function checkEof($stream, $uri = null): void
538:	{
539:	$error = error_get_last();
540:	if (self::eof($stream, true)) {
541:	return;
542:	}
543:	if ($error) {
544:	throw new FilesystemErrorException($error['message']);
545:	}
546:	throw new FilesystemErrorException(sprintf(
547:	'Error reading from %s',
548:	self::getStreamName($uri, $stream),
549:	));
550:	}
551:
552:	/**
553:	* Close an open stream
554:	*
555:	* @param resource $stream
556:	* @param Stringable\|string\|null $uri
557:	*/
558:	public static function close($stream, $uri = null): void
559:	{
560:	$uri = self::getStreamName($uri, $stream);
561:	self::check(@fclose($stream), 'fclose', $uri);
562:	}
563:
564:	/**
565:	* Close a pipe to a process and return its exit status
566:	*
567:	* @param resource $pipe
568:	*/
569:	public static function closePipe($pipe, ?string $command = null): int
570:	{
571:	$result = @pclose($pipe);
572:	if ($result === -1) {
573:	self::check(false, 'pclose', $command ?? '<pipe>');
574:	}
575:	return $result;
576:	}
577:
578:	/**
579:	* Check if a stream is at end-of-file
580:	*
581:	* @param resource $stream
582:	*/
583:	public static function eof($stream, bool $returnFalseOnError = false): bool
584:	{
585:	error_clear_last();
586:	$result = @feof($stream);
587:	if ($error = error_get_last()) {
588:	if ($returnFalseOnError) {
589:	return false;
590:	}
591:	throw new FilesystemErrorException($error['message']);
592:	}
593:	return $result;
594:	}
595:
596:	/**
597:	* If a stream is not seekable, copy it to a temporary stream that is and
598:	* close it
599:	*
600:	* @param resource $stream
601:	* @param Stringable\|string\|null $uri
602:	* @return resource
603:	*/
604:	public static function getSeekableStream($stream, $uri = null)
605:	{
606:	if (self::isSeekableStream($stream)) {
607:	return $stream;
608:	}
609:	$seekable = self::open('php://temp', 'r+');
610:	self::copy($stream, $seekable, $uri);
611:	self::close($stream, $uri);
612:	self::rewind($seekable);
613:	return $seekable;
614:	}
615:
616:	/**
617:	* Get the URI associated with a stream
618:	*
619:	* @param resource $stream
620:	* @return string\|null `null` if `$stream` is closed or does not have a URI.
621:	*/
622:	public static function getStreamUri($stream): ?string
623:	{
624:	if (self::isStream($stream)) {
625:	return stream_get_meta_data($stream)['uri'] ?? null;
626:	}
627:	return null;
628:	}
629:
630:	/**
631:	* Check if a value is a seekable stream resource
632:	*
633:	* @param mixed $value
634:	* @phpstan-assert-if-true =resource $value
635:	*/
636:	public static function isSeekableStream($value): bool
637:	{
638:	return self::isStream($value)
639:	// @phpstan-ignore nullCoalesce.offset
640:	&& (stream_get_meta_data($value)['seekable'] ?? false);
641:	}
642:
643:	/**
644:	* Check if a value is a stream resource
645:	*
646:	* @param mixed $value
647:	* @phpstan-assert-if-true =resource $value
648:	*/
649:	public static function isStream($value): bool
650:	{
651:	return is_resource($value) && get_resource_type($value) === 'stream';
652:	}
653:
654:	/**
655:	* Open a file or URI
656:	*
657:	* @return resource
658:	*/
659:	public static function open(string $filename, string $mode)
660:	{
661:	return self::check(@fopen($filename, $mode), 'fopen', $filename);
662:	}
663:
664:	/**
665:	* Open a resource if it is not already open
666:	*
667:	* @template TUri of Stringable\|string\|null
668:	*
669:	* @param Stringable\|string\|resource $resource
670:	* @param TUri $uri
671:	* @param-out bool $close
672:	* @param-out ($resource is resource ? (TUri is null ? string\|null : TUri) : string) $uri
673:	* @return resource
674:	*/
675:	public static function maybeOpen($resource, string $mode, ?bool &$close, &$uri)
676:	{
677:	$close = false;
678:	if (is_resource($resource)) {
679:	if ($uri === null) {
680:	$uri = self::getStreamUri($resource);
681:	}
682:	return $resource;
683:	}
684:	$uri = (string) $resource;
685:	$close = true;
686:	return self::open($uri, $mode);
687:	}
688:
689:	/**
690:	* Open a pipe to a process
691:	*
692:	* @return resource
693:	*/
694:	public static function openPipe(string $command, string $mode)
695:	{
696:	return self::check(@popen($command, $mode), 'popen', $command);
697:	}
698:
699:	/**
700:	* Read from an open stream
701:	*
702:	* @param resource $stream
703:	* @param int<1,max> $length
704:	* @param Stringable\|string\|null $uri
705:	*/
706:	public static function read($stream, int $length, $uri = null): string
707:	{
708:	return self::check(@fread($stream, $length), 'fread', $uri, $stream);
709:	}
710:
711:	/**
712:	* Read from an open stream until data of the expected length is read
713:	*
714:	* @param resource $stream
715:	* @param int<0,max> $length
716:	* @param Stringable\|string\|null $uri
717:	* @throws UnreadDataException if fewer bytes are read than expected and the
718:	* stream is at end-of-file.
719:	*/
720:	public static function readAll($stream, int $length, $uri = null): string
721:	{
722:	if ($length === 0) {
723:	return '';
724:	}
725:	$data = '';
726:	$dataLength = 0;
727:	do {
728:	/** @var int<1,max> */
729:	$unread = $length - $dataLength;
730:	$result = self::read($stream, $unread, $uri);
731:	if ($result === '') {
732:	if (self::eof($stream)) {
733:	break;
734:	}
735:	usleep(10000);
736:	continue;
737:	}
738:	$data .= $result;
739:	$dataLength += strlen($result);
740:	if ($dataLength === $length) {
741:	return $data;
742:	}
743:	// Minimise CPU usage, e.g. when reading from non-blocking streams
744:	usleep(10000);
745:	} while (true);
746:
747:	throw new UnreadDataException(Inflect::format(
748:	$unread,
749:	'Error reading from stream: expected {{#}} more {{#:byte}} from %s',
750:	self::getStreamName($uri, $stream),
751:	));
752:	}
753:
754:	/**
755:	* Read a line from an open stream
756:	*
757:	* @param resource $stream
758:	* @param Stringable\|string\|null $uri
759:	*/
760:	public static function readLine($stream, $uri = null): string
761:	{
762:	$line = @fgets($stream);
763:	if ($line !== false) {
764:	return $line;
765:	}
766:	self::checkEof($stream, $uri);
767:	return '';
768:	}
769:
770:	/**
771:	* Rewind to the beginning of a stream
772:	*
773:	* @param resource $stream
774:	* @param Stringable\|string\|null $uri
775:	*/
776:	public static function rewind($stream, $uri = null): void
777:	{
778:	self::check(rewind($stream), 'rewind', $uri, $stream);
779:	}
780:
781:	/**
782:	* Rewind to the beginning of a stream if it is seekable
783:	*
784:	* @param resource $stream
785:	* @param Stringable\|string\|null $uri
786:	*/
787:	public static function maybeRewind($stream, $uri = null): void
788:	{
789:	if (self::isSeekableStream($stream)) {
790:	self::rewind($stream, $uri);
791:	}
792:	}
793:
794:	/**
795:	* Set the file position indicator for a stream
796:	*
797:	* @param resource $stream
798:	* @param \SEEK_SET\|\SEEK_CUR\|\SEEK_END $whence
799:	* @param Stringable\|string\|null $uri
800:	*/
801:	public static function seek($stream, int $offset, int $whence = \SEEK_SET, $uri = null): void
802:	{
803:	/** @disregard P1006 */
804:	if (@fseek($stream, $offset, $whence) === -1) {
805:	self::check(false, 'fseek', $uri, $stream);
806:	}
807:	}
808:
809:	/**
810:	* Set the file position indicator for a stream if it is seekable
811:	*
812:	* @param resource $stream
813:	* @param \SEEK_SET\|\SEEK_CUR\|\SEEK_END $whence
814:	* @param Stringable\|string\|null $uri
815:	*/
816:	public static function maybeSeek($stream, int $offset, int $whence = \SEEK_SET, $uri = null): void
817:	{
818:	if (self::isSeekableStream($stream)) {
819:	/** @disregard P1006 */
820:	self::seek($stream, $offset, $whence, $uri);
821:	}
822:	}
823:
824:	/**
825:	* Wait for the given streams to change status
826:	*
827:	* @template TRead of resource[]\|null
828:	* @template TWrite of resource[]\|null
829:	* @template TExcept of resource[]\|null
830:	*
831:	* @param TRead $read
832:	* @param TWrite $write
833:	* @param TExcept $except
834:	*/
835:	public static function select(?array &$read, ?array &$write, ?array &$except, ?int $seconds, ?int $microseconds = null): int
836:	{
837:	return self::check(@stream_select(
838:	$read,
839:	$write,
840:	$except,
841:	$seconds,
842:	// `$microseconds` is not nullable until PHP 8.1
843:	$microseconds ?? 0,
844:	), 'stream_select');
845:	}
846:
847:	/**
848:	* Get the file position indicator for a stream
849:	*
850:	* @param resource $stream
851:	* @param Stringable\|string\|null $uri
852:	*/
853:	public static function tell($stream, $uri = null): int
854:	{
855:	return self::check(@ftell($stream), 'ftell', $uri, $stream);
856:	}
857:
858:	/**
859:	* Rewind to the beginning of a stream and truncate it
860:	*
861:	* @param resource $stream
862:	* @param int<0,max> $size
863:	* @param Stringable\|string\|null $uri
864:	*/
865:	public static function truncate($stream, int $size = 0, $uri = null): void
866:	{
867:	self::seek($stream, 0, \SEEK_SET, $uri);
868:	self::check(@ftruncate($stream, $size), 'ftruncate', $uri, $stream);
869:	}
870:
871:	/**
872:	* Write to an open stream
873:	*
874:	* @param resource $stream
875:	* @param int<0,max>\|null $length
876:	* @param Stringable\|string\|null $uri
877:	* @throws UnwrittenDataException if fewer bytes are written than expected.
878:	*/
879:	public static function write($stream, string $data, ?int $length = null, $uri = null): int
880:	{
881:	$result = self::doWrite($stream, $data, $length, $unwritten, $uri);
882:	if ($unwritten > 0) {
883:	throw new UnwrittenDataException(Inflect::format(
884:	$unwritten,
885:	'Error writing to stream: {{#}} {{#:byte}} not written to %s',
886:	self::getStreamName($uri, $stream),
887:	));
888:	}
889:	return $result;
890:	}
891:
892:	/**
893:	* Write to an open stream until there is no unwritten data
894:	*
895:	* @param resource $stream
896:	* @param int<0,max>\|null $length
897:	* @param Stringable\|string\|null $uri
898:	*/
899:	public static function writeAll($stream, string $data, ?int $length = null, $uri = null): int
900:	{
901:	if ($length !== null) {
902:	$data = substr($data, 0, $length);
903:	}
904:	if ($data === '') {
905:	return 0;
906:	}
907:	$result = 0;
908:	do {
909:	$result += self::maybeWrite($stream, $data, $data, null, $uri);
910:	if ($data === '') {
911:	return $result;
912:	}
913:	// Minimise CPU usage, e.g. when writing to non-blocking streams
914:	// @codeCoverageIgnoreStart
915:	usleep(10000);
916:	// @codeCoverageIgnoreEnd
917:	} while (true);
918:	}
919:
920:	/**
921:	* Write to an open stream and apply any unwritten data to a buffer
922:	*
923:	* @param resource $stream
924:	* @param int<0,max>\|null $length
925:	* @param Stringable\|string\|null $uri
926:	* @param-out string $buffer
927:	*/
928:	public static function maybeWrite($stream, string $data, ?string &$buffer, ?int $length = null, $uri = null): int
929:	{
930:	$result = self::doWrite($stream, $data, $length, $unwritten, $uri);
931:	$buffer = (string) substr($data, $result);
932:	return $result;
933:	}
934:
935:	/**
936:	* @param resource $stream
937:	* @param int<0,max>\|null $length
938:	* @param Stringable\|string\|null $uri
939:	* @param-out int $unwritten
940:	*/
941:	private static function doWrite($stream, string $data, ?int $length, ?int &$unwritten, $uri): int
942:	{
943:	// $length can't be null in PHP 7.4
944:	if ($length === null) {
945:	$length = strlen($data);
946:	$expected = $length;
947:	} else {
948:	$expected = min($length, strlen($data));
949:	}
950:	$result = @fwrite($stream, $data, $length);
951:	self::check($result, 'fwrite', $uri, $stream);
952:	/** @var int<0,max> */
953:	$unwritten = $expected - $result;
954:	return $result;
955:	}
956:
957:	/**
958:	* Write a line of comma-separated values to an open stream
959:	*
960:	* A shim for {@see fputcsv()} with `$eol` (added in PHP 8.1) and without
961:	* `$escape` (which should never have been added).
962:	*
963:	* @param resource $stream
964:	* @param (int\|float\|string\|bool\|null)[] $fields
965:	* @param Stringable\|string\|null $uri
966:	*/
967:	public static function writeCsvLine(
968:	$stream,
969:	array $fields,
970:	string $separator = ',',
971:	string $enclosure = '"',
972:	string $eol = "\n",
973:	$uri = null
974:	): int {
975:	$special = $separator . $enclosure . "\n\r\t ";
976:	foreach ($fields as &$field) {
977:	if (strpbrk((string) $field, $special) !== false) {
978:	$field = $enclosure
979:	. str_replace($enclosure, $enclosure . $enclosure, (string) $field)
980:	. $enclosure;
981:	}
982:	}
983:	$line = implode($separator, $fields) . $eol;
984:	return self::write($stream, $line, null, $uri);
985:	}
986:
987:	/**
988:	* Copy a file or stream to another file or stream
989:	*
990:	* @param Stringable\|string\|resource $from
991:	* @param Stringable\|string\|resource $to
992:	* @param Stringable\|string\|null $fromUri
993:	* @param Stringable\|string\|null $toUri
994:	*/
995:	public static function copy($from, $to, $fromUri = null, $toUri = null): void
996:	{
997:	if (is_resource($from) && is_resource($to)) {
998:	$result = @stream_copy_to_stream($from, $to);
999:	$from = self::getStreamName($fromUri, $from);
1000:	$to = self::getStreamName($toUri, $to);
1001:	self::check($result, 'stream_copy_to_stream', null, null, $from, $to);
1002:	} elseif (Test::isStringable($from) && Test::isStringable($to)) {
1003:	$from = (string) $from;
1004:	$to = (string) $to;
1005:	self::check(@copy($from, $to), 'copy', null, null, $from, $to);
1006:	} else {
1007:	throw new InvalidArgumentException('$from and $to must both be Stringable\|string or resource');
1008:	}
1009:	}
1010:
1011:	/**
1012:	* Get the contents of a file or stream
1013:	*
1014:	* @param Stringable\|string\|resource $resource
1015:	* @param Stringable\|string\|null $uri
1016:	*/
1017:	public static function getContents($resource, ?int $offset = null, $uri = null): string
1018:	{
1019:	if (is_resource($resource)) {
1020:	return self::check(@stream_get_contents($resource, -1, $offset ?? -1), 'stream_get_contents', $uri, $resource);
1021:	}
1022:	$resource = (string) $resource;
1023:	return self::check(@file_get_contents($resource, false, null, $offset ?? 0), 'file_get_contents', $resource);
1024:	}
1025:
1026:	/**
1027:	* Get CSV-formatted data from a file or stream
1028:	*
1029:	* @param Stringable\|string\|resource $resource
1030:	* @param Stringable\|string\|null $uri
1031:	* @return list<array{null}\|list<string>>
1032:	*/
1033:	public static function getCsv($resource, $uri = null): array
1034:	{
1035:	$handle = self::maybeOpen($resource, 'rb', $close, $uri);
1036:	while (($row = @fgetcsv($handle, 0, ',', '"', '')) !== false) {
1037:	/** @var array{null}\|list<string> $row */
1038:	$data[] = $row;
1039:	}
1040:	self::checkEof($handle, $uri);
1041:	if ($close) {
1042:	self::close($handle, $uri);
1043:	}
1044:	return $data ?? [];
1045:	}
1046:
1047:	/**
1048:	* Guess the end-of-line sequence used in a file or stream
1049:	*
1050:	* Recognised line endings are LF (`"\n"`), CRLF (`"\r\n"`) and CR (`"\r"`).
1051:	*
1052:	* @see Get::eol()
1053:	* @see Str::setEol()
1054:	*
1055:	* @param Stringable\|string\|resource $resource
1056:	* @param Stringable\|string\|null $uri
1057:	* @return non-empty-string\|null `null` if there are no recognised newline
1058:	* characters in the file.
1059:	*/
1060:	public static function getEol($resource, $uri = null): ?string
1061:	{
1062:	$handle = self::maybeOpen($resource, 'r', $close, $uri);
1063:	$line = self::readLine($handle, $uri);
1064:	if ($close) {
1065:	self::close($handle, $uri);
1066:	}
1067:	if ($line === '') {
1068:	return null;
1069:	}
1070:	foreach (["\r\n", "\n", "\r"] as $eol) {
1071:	if (substr($line, -strlen($eol)) === $eol) {
1072:	return $eol;
1073:	}
1074:	}
1075:	if (strpos($line, "\r") !== false) {
1076:	return "\r";
1077:	}
1078:	return null;
1079:	}
1080:
1081:	/**
1082:	* Guess the indentation used in a file or stream
1083:	*
1084:	* Returns `$default` if `$resource` appears to use the default indentation.
1085:	*
1086:	* @param Stringable\|string\|resource $resource
1087:	* @param Stringable\|string\|null $uri
1088:	*/
1089:	public static function getIndentation(
1090:	$resource,
1091:	?Indentation $default = null,
1092:	bool $alwaysGuessTabSize = false,
1093:	$uri = null
1094:	): Indentation {
1095:	return (new IndentationGuesser($default, $alwaysGuessTabSize))
1096:	->guess($resource, $uri);
1097:	}
1098:
1099:	/**
1100:	* Get lines from a file or stream
1101:	*
1102:	* @param Stringable\|string\|resource $resource
1103:	* @param Stringable\|string\|null $uri
1104:	* @return string[]
1105:	*/
1106:	public static function getLines($resource, $uri = null): array
1107:	{
1108:	if (is_resource($resource)) {
1109:	while (($line = @fgets($resource)) !== false) {
1110:	$lines[] = $line;
1111:	}
1112:	self::checkEof($resource, $uri);
1113:	return $lines ?? [];
1114:	}
1115:	$resource = (string) $resource;
1116:	return self::check(@file($resource), 'file', $resource);
1117:	}
1118:
1119:	/**
1120:	* Check if a file or stream appears to contain PHP code
1121:	*
1122:	* Returns `true` if `$resource` has a PHP open tag (`<?php`) at the start
1123:	* of the first line that is not a shebang (`#!`).
1124:	*
1125:	* @param Stringable\|string\|resource $resource
1126:	* @param Stringable\|string\|null $uri
1127:	*/
1128:	public static function hasPhp($resource, $uri = null): bool
1129:	{
1130:	$handle = self::maybeOpen($resource, 'r', $close, $uri);
1131:	$line = self::readLine($handle, $uri);
1132:	if ($line !== '' && substr($line, 0, 2) === '#!') {
1133:	$line = self::readLine($handle, $uri);
1134:	}
1135:	if ($close) {
1136:	self::close($handle, $uri);
1137:	}
1138:	if ($line === '') {
1139:	return false;
1140:	}
1141:	return (bool) Regex::match('/^<\?(php\s\|(?!php\|xml\s))/', $line);
1142:	}
1143:
1144:	/**
1145:	* Get the status of a file or stream
1146:	*
1147:	* @param Stringable\|string\|resource $resource
1148:	* @param Stringable\|string\|null $uri
1149:	* @return int[]
1150:	*/
1151:	public static function stat($resource, $uri = null): array
1152:	{
1153:	if (is_resource($resource)) {
1154:	return self::check(@fstat($resource), 'fstat', $uri, $resource);
1155:	}
1156:	$resource = (string) $resource;
1157:	return self::check(@stat($resource), 'stat', $resource);
1158:	}
1159:
1160:	/**
1161:	* Write CSV-formatted data to a file or stream
1162:	*
1163:	* For maximum interoperability with Excel across all platforms, output is
1164:	* written in UTF-16LE with a BOM (byte order mark) by default.
1165:	*
1166:	* @template TValue
1167:	*
1168:	* @param Stringable\|string\|resource $resource
1169:	* @param iterable<TValue> $data
1170:	* @param bool $headerRow Write the first entry's keys before the first row
1171:	* of data?
1172:	* @param int\|float\|string\|bool\|null $null Replace `null` values in `$data`.
1173:	* @param (callable(TValue, int $index): mixed[])\|null $callback Apply a
1174:	* callback to each entry before it is written.
1175:	* @param int\|null $count Receives the number of entries written.
1176:	* @param Stringable\|string\|null $uri
1177:	* @param-out int $count
1178:	*/
1179:	public static function writeCsv(
1180:	$resource,
1181:	iterable $data,
1182:	bool $headerRow = true,
1183:	$null = null,
1184:	?callable $callback = null,
1185:	?int &$count = null,
1186:	string $eol = "\r\n",
1187:	bool $utf16le = true,
1188:	bool $bom = true,
1189:	$uri = null
1190:	): void {
1191:	$handle = self::maybeOpen($resource, 'wb', $close, $uri);
1192:	if ($utf16le) {
1193:	if (!extension_loaded('iconv')) {
1194:	// @codeCoverageIgnoreStart
1195:	throw new InvalidRuntimeConfigurationException(
1196:	"'iconv' extension required for UTF-16LE encoding"
1197:	);
1198:	// @codeCoverageIgnoreEnd
1199:	}
1200:	$result = @stream_filter_append($handle, 'convert.iconv.UTF-8.UTF-16LE', \STREAM_FILTER_WRITE);
1201:	$filter = self::check($result, 'stream_filter_append', $uri, $handle);
1202:	}
1203:	if ($bom) {
1204:	self::write($handle, "\u{FEFF}", null, $uri);
1205:	}
1206:	$count = 0;
1207:	foreach ($data as $entry) {
1208:	if ($callback) {
1209:	$entry = $callback($entry, $count);
1210:	}
1211:	/** @var (int\|float\|string\|bool\|mixed[]\|object\|null)[] $entry */
1212:	$row = Arr::toScalars($entry, $null);
1213:	if (!$count && $headerRow) {
1214:	self::writeCsvLine($handle, array_keys($row), ',', '"', $eol, $uri);
1215:	}
1216:	self::writeCsvLine($handle, $row, ',', '"', $eol, $uri);
1217:	$count++;
1218:	}
1219:	if ($close) {
1220:	self::close($handle, $uri);
1221:	} elseif ($utf16le) {
1222:	self::check(@stream_filter_remove($filter), 'stream_filter_remove', $uri, $handle);
1223:	}
1224:	}
1225:
1226:	/**
1227:	* @template T
1228:	*
1229:	* @param T\|false $result
1230:	* @param Stringable\|string\|null $uri
1231:	* @param resource\|null $stream
1232:	* @return ($result is false ? never : T)
1233:	*/
1234:	private static function check($result, string $function, $uri = null, $stream = null, string ...$args)
1235:	{
1236:	if ($result !== false) {
1237:	return $result;
1238:	}
1239:	$error = error_get_last();
1240:	if ($error) {
1241:	throw new FilesystemErrorException($error['message']);
1242:	}
1243:	if (func_num_args() < 3) {
1244:	throw new FilesystemErrorException(sprintf(
1245:	'Error calling %s()',
1246:	$function,
1247:	));
1248:	}
1249:	throw new FilesystemErrorException(sprintf(
1250:	'Error calling %s() with %s',
1251:	$function,
1252:	$args
1253:	? implode(', ', $args)
1254:	: self::getStreamName($uri, $stream),
1255:	));
1256:	}
1257:
1258:	/**
1259:	* @param Stringable\|string\|null $uri
1260:	* @param resource\|null $stream
1261:	*/
1262:	private static function getStreamName($uri, $stream): string
1263:	{
1264:	if ($uri !== null) {
1265:	return (string) $uri;
1266:	}
1267:	if ($stream !== null) {
1268:	$uri = self::getStreamUri($stream);
1269:	}
1270:	return $uri ?? '<stream>';
1271:	}
1272:	}
1273:

Namespaces

Classes