diff --git a/src/Symfony/Bundle/WebServerBundle/Resources/doc/index.rst b/src/Symfony/Bundle/WebServerBundle/Resources/doc/index.rst new file mode 100644 index 0000000000000..06f61c8695a27 --- /dev/null +++ b/src/Symfony/Bundle/WebServerBundle/Resources/doc/index.rst @@ -0,0 +1,190 @@ +WebServerBundle +=============== + +This bundle provides commands for running applications using the PHP built-in +web server. It simplifies your local development setup because you don't have to +configure a proper web server such as Apache or Nginx to run your application. + +Installation +------------ + +Step 1: Download the Bundle +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Open a command console, enter your project directory and execute the +following command to download the latest stable version of this bundle: + +.. code-block:: bash + + $ composer require symfony/web-server-bundle + +Step 2: Enable the Bundle +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Then, enable the bundle by adding it to the list of registered bundles for the +``dev`` environment in the ``app/AppKernel.php`` file of your project:: + + // app/AppKernel.php + + // ... + class AppKernel extends Kernel + { + public function registerBundles() + { + if (in_array($this->getEnvironment(), array('dev', 'test'))) { + $bundles[] = new Symfony\Bundle\WebServerBundle\WebServerBundle(); + // ... + } + + // ... + } + + // ... + } + +List of Available Commands +-------------------------- + +After installing the bundle, the following commands are added to your Symfony +application under the ``server:`` namespace. + +``server:run`` +~~~~~~~~~~~~~~ + +It runs a local web server so you can browse your applications while developing +them. By default, the server listens on ``127.0.0.1`` address and the port +number is automatically selected as the first free port starting from ``8000``: + +.. code-block:: terminal + + $ ./bin/console server:run + + [OK] Server listening on http://127.0.0.1:8000 + // Quit the server with CONTROL-C. + +.. note:: + + This command blocks the command console. If you want to run other commands, + you must stop it by pressing ``Control`` + ``C`` or use the non-blocking + ``server:start`` command instead. + +Arguments and Options +..................... + +``addressport`` + The address to listen to. It can be address:port (``192.168.0.1:3000``), + address (``::1``), or port (``8080``). + + .. code-block:: terminal + + $ ./bin/console server:run 192.168.0.1:3000 + +``--docroot`` + Defines the document root directory, which is usually the directory where + your front controllers are stored (.e.g ``web/``). + +``--router`` + Defines the custom router script to use with the PHP web server (e.g. + ``Resources/router.php``). + +``server:start`` +~~~~~~~~~~~~~~~~ + +It's similar to ``server:run``, but executing it doesn't block the command +console. The server is run in the background and you can keep executing other +commands: + +.. code-block:: terminal + + $ ./bin/console server:start + + [OK] Server listening on http://127.0.0.1:8000 + +Arguments and Options +..................... + +The ``addressport`` argument and the ``--docroot`` and ``--router`` options are +the same as explained for the ``server:run`` command. In addition, it defines +another option: + +``--pidfile`` + Defines the path of the file to store the address and port used by the web + server. The contents of this file are needed by other commands to know where + the server is listening to. + +``server:stop`` +~~~~~~~~~~~~~~~ + +It stops the web server whose PID file is given as an option: + +.. code-block:: terminal + + $ ./bin/console server:stop + + [OK] Stopped the web server. + +Arguments and Options +..................... + +``--pidfile`` + Defines the path of the file that stores the address and port used by the + web server. The contents of this file are created by the ``server:start`` + command. + +``server:status`` +~~~~~~~~~~~~~~~~~ + +It shows the details of the given local web server, such as the address and port +where is listening to: + +.. code-block:: terminal + + $ ./bin/console server:status + + [OK] Web server still listening on http://127.0.0.1:8000 + +Arguments and Options +..................... + +``--pidfile`` + Defines the path of the file that stores the address and port used by the + web server. The contents of this file are created by the ``server:start`` + command. + +``--filter`` + Returns the given value (``port``, ``host`` or ``address``) in a machine + readable format. This allows to return a value that can be used as the + input of other commands and scripts. + +``server:log`` +~~~~~~~~~~~~~~ + +It starts a log server to display in real time the log messages generated by +your Symfony application: + +.. code-block:: terminal + + $ ./bin/console server:log + + DEBUG event Notified event ... + INFO app Created user ... + # ... + +Arguments and Options +..................... + +``--host`` + The address and port where the log server listens to (e.g. ``127.0.0.1:8888``). + +``--format`` + The line format applied to every log message before displaying it (e.g. + ``ConsoleFormatter::SIMPLE_FORMAT``). + +``--date-format`` + The format applied to the date of the log message (e.g. ``ConsoleFormatter::SIMPLE_DATE``). + +``--filter`` + Any `ExpressionLanguage`_ compatible expression used to filter the log + messages before displaying them (e.g. ``"level > 200 or channel in [\'app\', \'doctrine\']"``). + +.. _`ExpressionLanguage`: https://symfony.com/components/ExpressionLanguage