1	<?php
2
3	declare(strict_types=1);
4
5	/**
6	* Fast Forward Development Tools for PHP projects.
7	*
8	* This file is part of fast-forward/dev-tools project.
9	*
10	* @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
11	* @license  https://opensource.org/licenses/MIT MIT License
12	*
13	* @see      https://github.com/php-fast-forward/
14	* @see      https://github.com/php-fast-forward/dev-tools
15	* @see      https://github.com/php-fast-forward/dev-tools/issues
16	* @see      https://php-fast-forward.github.io/dev-tools/
17	* @see      https://datatracker.ietf.org/doc/html/rfc2119
18	*/
19
20	namespace FastForward\DevTools\Filesystem;
21
22	/**
23	* Defines a standard file system interface with enhanced path resolution.
24	*
25	* This interface extends common filesystem operations by ensuring paths
26	* can be deterministically resolved to absolute paths before interaction.
27	*/
28	interface FilesystemInterface
29	{
30	/**
31	* Checks whether a file or directory exists.
32	*
33	* @param iterable<string>|string $files the file(s) or directory(ies) to check
34	* @param string|null $basePath the base path used to resolve relative paths
35	*
36	* @return bool true if the path exists, false otherwise
37	*/
38	public function exists(string|iterable $files, ?string $basePath = null): bool;
39
40	/**
41	* Reads the entire content of a file.
42	*
43	* @param string $filename the target filename to read
44	* @param string|null $path the optional base path to resolve the filename against
45	*
46	* @return string the content of the file
47	*/
48	public function readFile(string $filename, ?string $path = null): string;
49
50	/**
51	* Writes content to a file, overriding it if it already exists.
52	*
53	* @param string $filename the filename to write to
54	* @param mixed $content the content to write
55	* @param string|null $path the optional base path to resolve the filename against
56	*/
57	public function dumpFile(string $filename, mixed $content, ?string $path = null): void;
58
59	/**
60	* Copies a file to a target path.
61	*
62	* @param string $originFile the source file path to copy
63	* @param string $targetFile the target file path to create
64	* @param bool $overwriteNewerFiles whether newer target files MAY be overwritten
65	*/
66	public function copy(string $originFile, string $targetFile, bool $overwriteNewerFiles = false): void;
67
68	/**
69	* Changes the permission mode for one or more files.
70	*
71	* @param iterable<string>|string $files the target file paths
72	* @param int $mode the permission mode to apply
73	* @param int $umask the umask to apply
74	* @param bool $recursive whether permissions SHOULD be applied recursively
75	*/
76	public function chmod(string|iterable $files, int $mode, int $umask = 0o000, bool $recursive = false): void;
77
78	/**
79	* Removes files, symbolic links, or directories.
80	*
81	* @param iterable<string>|string $files the file(s), link(s), or directory(ies) to remove
82	*/
83	public function remove(string|iterable $files): void;
84
85	/**
86	* Creates a symbolic link.
87	*
88	* @param string $originDir the origin path the link MUST point to
89	* @param string $targetDir the link path to create
90	* @param bool $copyOnWindows whether directories SHOULD be copied on Windows instead of linked
91	*/
92	public function symlink(string $originDir, string $targetDir, bool $copyOnWindows = false): void;
93
94	/**
95	* Reads a symbolic link target.
96	*
97	* @param string $path the symbolic link path
98	* @param bool $canonicalize whether the returned path SHOULD be canonicalized
99	*
100	* @return string|null the link target, or null when the path is not a symbolic link
101	*/
102	public function readlink(string $path, bool $canonicalize = false): ?string;
103
104	/**
105	* Resolves a path or iterable of paths into their absolute path representation.
106	*
107	* If a relative path is provided, it SHALL be evaluated against the current
108	* working directory or the provided $basePath if one is supplied.
109	*
110	* @param iterable<string>|string $files the path(s) to resolve
111	* @param string|null $basePath the base path for relative path resolution
112	*
113	* @return iterable<string>|string the resolved absolute path(s)
114	*/
115	public function getAbsolutePath(string|iterable $files, ?string $basePath = null): string|iterable;
116
117	/**
118	* Creates a directory recursively.
119	*
120	* @param iterable<string>|string $dirs the directory path(s) to create
121	* @param int $mode the permissions mode (defaults to 0777)
122	* @param string|null $basePath the base path for relative path resolution
123	*/
124	public function mkdir(string|iterable $dirs, int $mode = 0o777, ?string $basePath = null): void;
125
126	/**
127	* Computes the relative path from the base path to the target path.
128	*
129	* @param string $path the target absolute or relative path
130	* @param string|null $basePath the origin point; defaults to the current working directory
131	*
132	* @return string the computed relative path
133	*/
134	public function makePathRelative(string $path, ?string $basePath = null): string;
135
136	/**
137	* Returns the trailing name component of a path.
138	*
139	* @param string $path the path to process
140	* @param string $suffix an optional suffix to strip from the returned basename
141	*
142	* @return string the base name of the given path
143	*/
144	public function basename(string $path, string $suffix = ''): string;
145
146	/**
147	* Returns a parent directory's path.
148	*
149	* @param string $path the path to evaluate
150	* @param int $levels the number of parent directories to go up
151	*
152	* @return string the parent path name
153	*/
154	public function dirname(string $path, int $levels = 1): string;
155	}