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

Author: xabbuh

book/installation.rst

@@ -274,14 +274,24 @@ 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**
-
-    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
-    issues when setting up new projects. This can be done by editing your web server
-    configuration (e.g. commonly httpd.conf or apache2.conf for Apache) and setting
-    its user to be the same as your CLI user (e.g. for Apache, update the User
-    and Group values).
+    **4. Use the built-in web server in development environments**
+
+    In development environments, the easiest way to test your application,
+    is to use PHP's built-in web server:
+
+    .. code-block:: bash
+
+        $ php app/console server:start
+
+    When you are finished, stop it using the ``server:stop`` command:
+
+    .. code-block:: bash
+
+        $ php app/console server:stop
+
+    .. seealso::
+
+        Read more about the internal server :doc:`in the cookbook </cookbook/web_server/built_in>`.
 
 When everything is fine, click on "Go to the Welcome page" to request your
 first "real" Symfony webpage:

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

quick_tour/the_big_picture.rst

@@ -70,7 +70,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::