Fix GH-10964: Improve man page about the built-in server

Closes GH-11857.

Author: alexandre-daubois

NEWS

@@ -5,6 +5,8 @@ PHP                                                                        NEWS
 - CLI:
   . Fixed bug GH-11716 (cli server crashes on SIGINT when compiled with
     ZEND_RC_DEBUG=1). (nielsdos)
+  . Fixed bug GH-10964 (Improve man page about the built-in server).
+    (Alexandre Daubois)
 
 - DOM:
   . Fix DOMEntity field getter bugs. (nielsdos)

sapi/cli/php.1.in

@@ -92,6 +92,15 @@ point to a local address and port PHP will listen to HTTP requests on that addre
 .B docroot
 passed by the \-t option.
 .LP
+If a PHP file is provided to the command line when the
+built-in web server is used, it will be used as the router script. This script
+will be started at each HTTP request. The script output is returned to the
+browser, unless the router script returns the
+.B false
+value. If so, the built-in server falls back to the default behaviour, returning
+the requested resource as-is by looking up the files relative to the document
+root specified by the \-t option, if provided.
+.LP
 If none of \-r \-f \-B \-R \-F \-E or \-S is present but a single parameter is given
 then this parameter is taken as the filename to parse and execute (same as
 with \-f). If no parameter is present then the standard input is read and