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

@@ -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,15 +23,14 @@ 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 will
+serve 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:
@@ -36,8 +39,30 @@ 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
 
+.. 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

@@ -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::