Skip to content

Commit 7c034fc

Browse files
coisacoisa
committed
docs: Add PHPDoc to filesystem classes
1 parent 324b2b8 commit 7c034fc

2 files changed

Lines changed: 124 additions & 54 deletions

File tree

‎src/Filesystem/Filesystem.php‎

Lines changed: 62 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,44 @@
11
<?php
22

3+
declare(strict_types=1);
4+
5+
/**
6+
* This file is part of fast-forward/dev-tools.
7+
*
8+
* This source file is subject to the license bundled
9+
* with this source code in the file LICENSE.
10+
*
11+
* @copyright Copyright (c) 2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
12+
* @license https://opensource.org/licenses/MIT MIT License
13+
*
14+
* @see https://github.com/php-fast-forward/dev-tools
15+
* @see https://github.com/php-fast-forward
16+
* @see https://datatracker.ietf.org/doc/html/rfc2119
17+
*/
18+
319
namespace FastForward\DevTools\Filesystem;
420

521
use Override;
622
use function Safe\getcwd;
723
use Symfony\Component\Filesystem\Filesystem as SymfonyFilesystem;
824
use Symfony\Component\Filesystem\Path;
925

26+
/**
27+
* Concrete implementation of the standard filesystem interface.
28+
*
29+
* This class wraps over the Symfony Filesystem component, automatically
30+
* converting provided paths to absolute representations when a base path is supplied or
31+
* dynamically inferred from the generic working directory.
32+
*/
1033
final class Filesystem extends SymfonyFilesystem implements FilesystemInterface
1134
{
1235
/**
13-
* @param string|iterable $files
14-
* @param string|null $basePath
36+
* Checks whether a file or directory exists.
1537
*
16-
* @return bool
38+
* @param iterable<string>|string $files the file(s) or directory(ies) to check
39+
* @param string|null $basePath the base path used to resolve relative paths
40+
*
41+
* @return bool true if the path exists, false otherwise
1742
*/
1843
#[Override]
1944
public function exists(string|iterable $files, ?string $basePath = null): bool
@@ -22,10 +47,12 @@ public function exists(string|iterable $files, ?string $basePath = null): bool
2247
}
2348

2449
/**
25-
* @param string $filename
26-
* @param string|null $path
50+
* Reads the entire content of a file.
51+
*
52+
* @param string $filename the target filename to read
53+
* @param string|null $path the optional base path to resolve the filename against
2754
*
28-
* @return string
55+
* @return string the content of the file
2956
*/
3057
#[Override]
3158
public function readFile(string $filename, ?string $path = null): string
@@ -34,23 +61,25 @@ public function readFile(string $filename, ?string $path = null): string
3461
}
3562

3663
/**
37-
* @param string $filename
38-
* @param mixed $content
39-
* @param string|null $path
64+
* Writes content to a file, overriding it if it already exists.
4065
*
41-
* @return void
66+
* @param string $filename the filename to write to
67+
* @param mixed $content the content to write
68+
* @param string|null $path the optional base path to resolve the filename against
4269
*/
4370
#[Override]
44-
public function dumpFile(string $filename, $content, ?string $path = null): void
71+
public function dumpFile(string $filename, mixed $content, ?string $path = null): void
4572
{
4673
parent::dumpFile($this->getAbsolutePath($filename, $path), $content);
4774
}
4875

4976
/**
50-
* @param string|iterable $files
51-
* @param string|null $basePath
77+
* Resolves a path or iterable of paths into their absolute path representation.
5278
*
53-
* @return string|iterable
79+
* @param iterable<string>|string $files the path(s) to resolve
80+
* @param string|null $basePath the base path for relative path resolution
81+
*
82+
* @return iterable<string>|string the resolved absolute path(s)
5483
*/
5584
public function getAbsolutePath(string|iterable $files, ?string $basePath = null): string|iterable
5685
{
@@ -68,11 +97,11 @@ public function getAbsolutePath(string|iterable $files, ?string $basePath = null
6897
}
6998

7099
/**
71-
* @param string|iterable $dirs
72-
* @param int $mode
73-
* @param string|null $basePath
100+
* Creates a directory recursively.
74101
*
75-
* @return void
102+
* @param iterable<string>|string $dirs the directory path(s) to create
103+
* @param int $mode the permissions mode (defaults to 0777)
104+
* @param string|null $basePath the base path for relative path resolution
76105
*/
77106
#[Override]
78107
public function mkdir(string|iterable $dirs, int $mode = 0777, ?string $basePath = null): void
@@ -81,10 +110,12 @@ public function mkdir(string|iterable $dirs, int $mode = 0777, ?string $basePath
81110
}
82111

83112
/**
84-
* @param string $path
85-
* @param string|null $basePath
113+
* Computes the relative path from the base path to the target path.
114+
*
115+
* @param string $path the target absolute or relative path
116+
* @param string|null $basePath the origin point; defaults to the current working directory
86117
*
87-
* @return string
118+
* @return string the computed relative path
88119
*/
89120
#[Override]
90121
public function makePathRelative(string $path, ?string $basePath = null): string
@@ -96,21 +127,25 @@ public function makePathRelative(string $path, ?string $basePath = null): string
96127
}
97128

98129
/**
99-
* @param string $path
100-
* @param string $suffix
130+
* Returns the trailing name component of a path.
101131
*
102-
* @return string
132+
* @param string $path the path to process
133+
* @param string $suffix an optional suffix to strip from the returned basename
134+
*
135+
* @return string the base name of the given path
103136
*/
104137
public function basename(string $path, string $suffix = ''): string
105138
{
106139
return \basename($path, $suffix);
107140
}
108141

109142
/**
110-
* @param string $path
111-
* @param int $levels
143+
* Returns a parent directory's path.
144+
*
145+
* @param string $path the path to evaluate
146+
* @param int $levels the number of parent directories to go up
112147
*
113-
* @return string
148+
* @return string the parent path name
114149
*/
115150
public function dirname(string $path, int $levels = 1): string
116151
{

‎src/Filesystem/FilesystemInterface.php‎

Lines changed: 62 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,73 +2,108 @@
22

33
declare(strict_types=1);
44

5+
/**
6+
* This file is part of fast-forward/dev-tools.
7+
*
8+
* This source file is subject to the license bundled
9+
* with this source code in the file LICENSE.
10+
*
11+
* @copyright Copyright (c) 2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
12+
* @license https://opensource.org/licenses/MIT MIT License
13+
*
14+
* @see https://github.com/php-fast-forward/dev-tools
15+
* @see https://github.com/php-fast-forward
16+
* @see https://datatracker.ietf.org/doc/html/rfc2119
17+
*/
18+
519
namespace FastForward\DevTools\Filesystem;
620

21+
/**
22+
* Defines a standard file system interface with enhanced path resolution.
23+
*
24+
* This interface extends common filesystem operations by ensuring paths
25+
* can be deterministically resolved to absolute paths before interaction.
26+
*/
727
interface FilesystemInterface
828
{
929
/**
10-
* @param string|iterable $files
11-
* @param string|null $basePath
30+
* Checks whether a file or directory exists.
31+
*
32+
* @param iterable<string>|string $files the file(s) or directory(ies) to check
33+
* @param string|null $basePath the base path used to resolve relative paths
1234
*
13-
* @return bool
35+
* @return bool true if the path exists, false otherwise
1436
*/
1537
public function exists(string|iterable $files, ?string $basePath = null): bool;
1638

1739
/**
18-
* @param string $filename
19-
* @param string|null $path
40+
* Reads the entire content of a file.
2041
*
21-
* @return string
42+
* @param string $filename the target filename to read
43+
* @param string|null $path the optional base path to resolve the filename against
44+
*
45+
* @return string the content of the file
2246
*/
2347
public function readFile(string $filename, ?string $path = null): string;
2448

2549
/**
26-
* @param string $filename
27-
* @param mixed $content
28-
* @param string|null $path
50+
* Writes content to a file, overriding it if it already exists.
2951
*
30-
* @return void
52+
* @param string $filename the filename to write to
53+
* @param mixed $content the content to write
54+
* @param string|null $path the optional base path to resolve the filename against
3155
*/
32-
public function dumpFile(string $filename, $content, ?string $path = null): void;
56+
public function dumpFile(string $filename, mixed $content, ?string $path = null): void;
3357

3458
/**
35-
* @param string|iterable $files
36-
* @param string|null $basePath
59+
* Resolves a path or iterable of paths into their absolute path representation.
60+
*
61+
* If a relative path is provided, it SHALL be evaluated against the current
62+
* working directory or the provided $basePath if one is supplied.
3763
*
38-
* @return string|iterable
64+
* @param iterable<string>|string $files the path(s) to resolve
65+
* @param string|null $basePath the base path for relative path resolution
66+
*
67+
* @return iterable<string>|string the resolved absolute path(s)
3968
*/
4069
public function getAbsolutePath(string|iterable $files, ?string $basePath = null): string|iterable;
4170

4271
/**
43-
* @param string|iterable $dirs
44-
* @param int $mode
45-
* @param string|null $basePath
72+
* Creates a directory recursively.
4673
*
47-
* @return void
74+
* @param iterable<string>|string $dirs the directory path(s) to create
75+
* @param int $mode the permissions mode (defaults to 0777)
76+
* @param string|null $basePath the base path for relative path resolution
4877
*/
4978
public function mkdir(string|iterable $dirs, int $mode = 0777, ?string $basePath = null): void;
5079

5180
/**
52-
* @param string $path
53-
* @param string|null $basePath
81+
* Computes the relative path from the base path to the target path.
82+
*
83+
* @param string $path the target absolute or relative path
84+
* @param string|null $basePath the origin point; defaults to the current working directory
5485
*
55-
* @return string
86+
* @return string the computed relative path
5687
*/
5788
public function makePathRelative(string $path, ?string $basePath = null): string;
5889

5990
/**
60-
* @param string $path
61-
* @param string $suffix
91+
* Returns the trailing name component of a path.
6292
*
63-
* @return string
93+
* @param string $path the path to process
94+
* @param string $suffix an optional suffix to strip from the returned basename
95+
*
96+
* @return string the base name of the given path
6497
*/
6598
public function basename(string $path, string $suffix = ''): string;
6699

67100
/**
68-
* @param string $path
69-
* @param int $levels
101+
* Returns a parent directory's path.
102+
*
103+
* @param string $path the path to evaluate
104+
* @param int $levels the number of parent directories to go up
70105
*
71-
* @return string
106+
* @return string the parent path name
72107
*/
73108
public function dirname(string $path, int $levels = 1): string;
74109
}

0 commit comments

Comments
 (0)