feature symfony#4005 [Cookbook][Web server] description for running PHP's built-in web server in the background (xabbuh)

This PR was merged into the master branch.

Discussion
----------

[Cookbook][Web server] description for running PHP's built-in web server in the background

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#11311)
| Applies to    | 2.6+
| Fixed tickets |

Commits
-------

3caec21 description for running PHP's built-in web server in the background

Author: weaverryan

book/installation.rst

@@ -280,7 +280,21 @@ If there are any issues, correct them now before moving on.
     Note that using the ACL is recommended when you have access to them
     on your server because changing the umask is not thread-safe.
 
-    **4. Use the same user for the CLI and the web server**
+    **4. Use the built-in web server in development environments**
+
+    The built-in PHP web server - which can be used during development - allows
+    your web server user and CLI user to be the same. This removes any permissions
+    issues:
+
+    .. code-block:: bash
+
+        $ php app/console server:start
+
+    .. seealso::
+
+        Read more about the internal server :doc:`in the cookbook </cookbook/web_server/built_in>`.
+
+    **5. Use the same user for the CLI and the web server**
 
     In development environments, it is a common practice to use the same unix
     user for the CLI and the web server because it avoids any of these permissions

cookbook/web_server/built_in.rst

@@ -4,6 +4,10 @@
 How to Use PHP's built-in Web Server
 ====================================
 
+.. versionadded:: 2.6
+    The ability to run the server as a background process was introduced
+    in Symfony 2.6.
+
 Since PHP 5.4 the CLI SAPI comes with a `built-in web server`_. It can be used
 to run your PHP applications locally during development, for testing or for
 application demonstrations. This way, you don't have to bother configuring
@@ -19,25 +23,46 @@ Starting the Web Server
 -----------------------
 
 Running a Symfony application using PHP's built-in web server is as easy as
-executing the ``server:run`` command:
+executing the ``server:start`` command:
 
 .. code-block:: bash
 
-    $ php app/console server:run
+    $ php app/console server:start
 
-This starts a server at ``localhost:8000`` that executes your Symfony application.
-The command will wait and will respond to incoming HTTP requests until you
-terminate it (this is usually done by pressing Ctrl and C).
+This starts the web server at ``localhost:8000`` in the background that serves
+your Symfony application.
 
 By default, the web server listens on port 8000 on the loopback device. You
-can change the socket passing an ip address and a port as a command-line argument:
+can change the socket passing an IP address and a port as a command-line argument:
 
 .. code-block:: bash
 
     $ php app/console server:run 192.168.0.1:8080
 
+.. note::
+
+    You can use the ``server:status`` command to check if a web server is
+    listening on a certain socket:
+
+    .. code-block:: bash
+
+        $ php app/console server:status
+
+        $ php app/console server:status 192.168.0.1:8080
+
+    The first command shows if your Symfony application will be server through
+    ``localhost:8000``, the second one does the same for ``192.168.0.1:8080``.
+
+.. note::
+
+    Before Symfony 2.6, the ``server:run`` command was used to start the built-in
+    web server. This command is still available and behaves slightly different.
+    Instead of starting the server in the background, it will block the current
+    terminal until you terminate it (this is usually done by pressing Ctrl
+    and C).
+
 Command Options
----------------
+~~~~~~~~~~~~~~~
 
 The built-in web server expects a "router" script (read about the "router"
 script on `php.net`_) as an argument. Symfony already passes such a router
@@ -47,14 +72,32 @@ script:
 
 .. code-block:: bash
 
-    $ php app/console server:run --env=test --router=app/config/router_test.php
+    $ php app/console server:start --env=test --router=app/config/router_test.php
 
 If your application's document root differs from the standard directory layout,
 you have to pass the correct location using the ``--docroot`` option:
 
 .. code-block:: bash
 
-    $ php app/console server:run --docroot=public_html
+    $ php app/console server:start --docroot=public_html
+
+Stopping the Server
+-------------------
+
+When you are finished, you can simply stop the web server using the ``server:stop``
+command:
+
+.. code-block:: bash
+
+    $ php app/console server:stop
+
+Like with the start command, if you omit the socket information, Symfony will
+stop the web server bound to ``localhost:8000``. Just pass the socket information
+when the web server listens to another IP address or to another port:
+
+.. code-block:: bash
+
+    $ php app/console server:stop 192.168.0.1:8080
 
 .. _`built-in web server`: http://www.php.net/manual/en/features.commandline.webserver.php
 .. _`php.net`: http://php.net/manual/en/features.commandline.webserver.php#example-401

quick_tour/the_big_picture.rst

@@ -76,7 +76,13 @@ to run Symfony:
 
 .. code-block:: bash
 
-    $ php app/console server:run
+    $ php app/console server:start
+
+When you are finished, you can stop it with the ``server:stop`` command:
+
+.. code-block:: bash
+
+    $ php app/console server:stop
 
 .. seealso::