From 67ca0d930c95a85ea49aff456409409f6ae06c1b Mon Sep 17 00:00:00 2001
From: Juliette <663378+jrfnl@users.noreply.github.com>
Date: Mon, 8 Nov 2021 13:20:57 +0100
Subject: [PATCH] dirname(): add warning about risk of infinite loop

Co-authored-by: jrfnl <jrfnl@users.noreply.github.com>

Closes GH-1005.
---
 reference/filesystem/functions/dirname.xml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/reference/filesystem/functions/dirname.xml b/reference/filesystem/functions/dirname.xml
index 05fd795222..0d5cfd261b 100644
--- a/reference/filesystem/functions/dirname.xml
+++ b/reference/filesystem/functions/dirname.xml
@@ -82,6 +82,25 @@
    <parameter>path</parameter> with any trailing
    <literal>/component</literal> removed.
   </para>
+
+  <caution>
+   <para>
+    Be careful when using this function in a loop that can reach the
+    top-level directory as this can result in an infinite loop.
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+dirname('.');    // Will return '.'.
+dirname('/');    // Will return `\` on Windows and '/' on *nix systems.
+dirname('\\');   // Will return `\` on Windows and '.' on *nix systems.
+dirname('C:\\'); // Will return 'C:\' on Windows and '.' on *nix systems.
+?>
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+  </caution>
  </refsect1>
 
  <refsect1 role="changelog">