feature #6956 [Filesystem] Add documentation for the readlink method (tgalopin)

xabbuh · xabbuh · commit 218235313515 · 2016-09-21T14:49:26.000+02:00
This PR was merged into the master branch. Discussion ---------- [Filesystem] Add documentation for the readlink method Following the merge of symfony/symfony#17498, this PR introduces documentation for the new methd `readlink`. Commits ------- 3572a3d [Filesystem] Add documentation for the readlink method
diff --git a/components/filesystem.rst b/components/filesystem.rst
@@ -195,6 +195,40 @@ support symbolic links, a third boolean argument is available::
     // does not support symbolic links
     $fs->symlink('/path/to/source', '/path/to/destination', true);
 
+readlink
+~~~~~~~~
+
+.. versionadded:: 3.2
+    The :method:`Symfony\\Component\\Filesystem\\Filesystem::readlink` method was introduced in Symfony 3.2.
+
+:method:`Symfony\\Component\\Filesystem\\Filesystem::readlink` read links targets.
+
+PHP's ``readlink()`` function returns the target of a symbolic link. However, its behavior
+is completely different under Windows and Unix. On Windows systems, ``readlink()``
+resolves recursively the children links of a link until a final target is found. On
+Unix-based systems ``readlink()`` only resolves the next link.
+
+The :method:`Symfony\\Component\\Filesystem\\Filesystem::readlink` method provided
+by the Filesystem component always behaves in the same way::
+
+    // returns the next direct target of the link without considering the existence of the target
+    $fs->readlink('/path/to/link');
+
+    // returns its absolute fully resolved final version of the target (if there are nested links, they are resolved)
+    $fs->readlink('/path/to/link', true);
+
+Its behavior is the following::
+
+    public function readlink($path, $canonicalize = false)
+
+* When ``$canonicalize`` is ``false``:
+    * if ``$path`` does not exist or is not a link, it returns ``null``.
+    * if ``$path`` is a link, it returns the next direct target of the link without considering the existence of the target.
+
+* When ``$canonicalize`` is ``true``:
+    * if ``$path`` does not exist, it returns null.
+    * if ``$path`` exists, it returns its absolute fully resolved final version.
+
 makePathRelative
 ~~~~~~~~~~~~~~~~
 
