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

Author: xabbuh

cookbook/web_server/built_in.rst

@@ -15,8 +15,11 @@ a full-featured web server such as
     The built-in web server is meant to be run in a controlled environment.
     It is not designed to be used on public networks.
 
+Running the Server in the Foreground
+------------------------------------
+
 Starting the Web Server
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Running a Symfony application using PHP's built-in web server is as easy as
 executing the ``server:run`` command:
@@ -37,7 +40,7 @@ can change the socket passing an ip address and a port as a command-line argumen
     $ php app/console server:run 192.168.0.1:8080
 
 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
@@ -58,3 +61,61 @@ you have to pass the correct location using the ``--docroot`` option:
 
 .. _`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
+
+Moving the Process to the Background
+------------------------------------
+
+.. versionadded:: 2.6
+    The ability to run the server as a background process was introduced
+    in Symfony 2.6.
+
+The ``server:run`` command runs the web server in the foreground blocking
+the current terminal window. You can also run the server in a background process:
+
+.. code-block:: bash
+
+    $ php app/console server:start
+
+The ``server:start`` command accepts the same options and arguments as the
+``server:run`` command. For example, the following command will tell the server
+to listen on port 8080 on the network interface with the 192.168.0.1 ip address
+assigned to:
+
+.. code-block:: bash
+
+    $ php app/console server:start 192.168.0.1:8080
+
+This way, you can start several server processes listening on different sockets
+without bothering with a clutter of terminal windows.
+
+Stopping the Server
+~~~~~~~~~~~~~~~~~~~
+
+To stop a server running in the background, you simply call the ``server:stop``
+command passing it the socket the server is listening on.
+
+.. code-block:: bash
+
+    $ php app/console server:stop 127.0.0.1:8080
+
+Similar to the commands that are used to start the web server, omitting the
+socket argument for the ``server:stop`` command stops the server listening
+on port 8000 on the loopback device.
+
+Monitoring the Server Status
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can check status of the web server for a particular socket using the ``server:status``
+command (127.0.0.1:8000 being the default socket again):
+
+.. code-block:: bash
+
+    $ php app/console server:status 127.0.0.1:8080
+
+.. caution::
+
+    The information shown by the ``server:status`` command would not be reliable
+    if you didn't terminate the server using the ``server:stop`` command (by
+    using the UNIX ``kill`` command or the Windows task manager, for example).
+
+.. _`built-in web server`: http://www.php.net/manual/en/features.commandline.webserver.php