[Filesystem] Add documentation for the Path class #15759
Conversation
|
This is a first iteration of the documentation. I'm not very familiar with the documentation workflow/process neither with its conventions regarding the doc organisation or choice of vocabulary so I have no doubt that a few changes will be needed there |
|
/cc @chalasr |
| The component contains two classes: | ||
|
|
||
| - The :class:`Symfony\\Component\\Filesystem\\Filesystem` which provides utilities | ||
| for filesystem write operations. |
| @@ -236,6 +247,11 @@ Its behavior is the following:: | |||
| * if ``$path`` does not exist, it returns null. | |||
| * if ``$path`` exists, it returns its absolute fully resolved final version. | |||
|
|
|||
| .. note:: | |||
|
|
|||
| If you wish to canonicalize the path without checking its existence, you can | |||
There was a problem hiding this comment.
Reading this might be confusing if you don't know what "canonicalize the path" exactly means.
|
|
||
| - "." segments are removed; | ||
| - ".." segments are resolved; | ||
| - backslashes ("\") are converted into forward slashes ("/"); |
There was a problem hiding this comment.
Is this "backslash to forward-slash" transform applied unconditionally? Even on Windows?
There was a problem hiding this comment.
IIRC yes, the idea being you should compare normalized paths (there is a Path::normalize()) method as otherwise you are always susceptible to surprises (e.g. to expect a certain hard-coded unix style path but you are on Windows hence the path you are comparing to is invalid)
99769c8 to
8a928d8
Compare
8a928d8 to
165244e
Compare
|
Thanks Théo for contributing not only this feature but its docs as well 🙏 |
Closes #15621