From a6a708f1145e225eeb6f0fd93af57868b03a848c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 22 Mar 2019 16:57:09 +0100 Subject: [PATCH] Documented the local Symfony server --- setup/symfony_server.rst | 299 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 setup/symfony_server.rst diff --git a/setup/symfony_server.rst b/setup/symfony_server.rst new file mode 100644 index 00000000000..5f991b827fa --- /dev/null +++ b/setup/symfony_server.rst @@ -0,0 +1,299 @@ +Symfony Local Web Server +======================== + +You can run Symfony applications with any web server (Apache, nginx, the +internal PHP web server, etc.). However, Symfony provides its own web server to +make you more productive while developing your applications. + +Although this server is not intended for production use, it supports HTTP/2, +TLS/SSL, automatic generation of security certificates, local domains, and many +other features that sooner or later you'll need when developing web projects. +Moreover, the server is not tied to Symfony and you can also use it with any +PHP application and even with HTML/SPA (single page applications). + +Installation +------------ + +The Symfony server is distributed as a free installable binary without any +dependency and support for Linux, macOS and Windows. Go to `symfony.com/download`_ +and follow the instructions for your operating system. + +Getting Started +--------------- + +The Symfony server is started once per project, so you may end up with several +instances (each of them listening to a different port). This is the common +workflow to serve a Symfony project: + +.. code-block:: terminal + + $ cd my-project/ + $ symfony server:start + + [OK] Web server listening on http://127.0.0.1:.... + ... + + # Now, browse the given URL, or run this command: + $ symfony open:local + +Running the server this way makes it display the log messages in the console, so +you won't be able to run other commands at the same time. If you prefer, you can +run the Symfony server in the background: + +.. code-block:: terminal + + $ cd my-project/ + + # start the server in the background + $ symfony server:start -d + + # continue working and running other commands... + + # show the latest log messages + $ symfony server:log + +Enabling TLS +------------ + +Browsing the secure version of your apps locally is important to detect +problems with mixed content early, and to run libraries that only run in HTTPS. +Traditionally this has been painful and complicated to set up, but the Symfony +server automates everything. First, run this command: + +.. code-block:: terminal + + $ symfony server:ca:install + +This command creates a local certificate authority, registers it in your system +trust store, registers it in Firefox (this is required only for that browser) +and creates a default certificate for ``localhost`` and ``127.0.0.1``. In other +words, it does everything for you. + +Before browsing your local application with HTTPS instead of HTTP, restart its +server stopping and starting it again. + +Different PHP Settings Per Project +---------------------------------- + +Selecting a Different PHP Version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you have multiple PHP versions installed on your computer, you can tell +Symfony which one to use creating a file called ``.php-version`` at the project +root directory: + +.. code-block:: terminal + + $ cd my-project/ + + # use a specific PHP version + $ echo "7.2" > .php-version + + # use any PHP 7.x version available + $ echo "7" > .php-version + +.. tip:: + + The Symfony server traverses the directory structure up to the root + directory, so you can create a ``.php-version`` file in some parent + directory to set the same PHP version for a group of projects under that + directory. + +Run command if you don't remember all the PHP versions installed on your +computer: + +.. code-block:: terminal + + $ symfony local:php:list + + # You'll see all supported SAPIs (CGI, FastCGI, etc.) for each version. + # FastCGI (php-fpm) is used when possible; then CGI (which acts as a FastCGI + # server as well), and finally, the server falls back to plain CGI. + +Overriding PHP Config Options Per Project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can change the value of any PHP runtime config option per project by creating a +file called ``php.ini`` at the project root directory. Add only the options you want +to override: + +.. code-block:: terminal + + $ cd my-project/ + + # this project only overrides the default PHP timezone + $ cat php.ini + [Date] + date.timezone = Asia/Tokyo + +Running Commands with Different PHP Versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When running different PHP versions it's useful to use the main ``symfony`` +command as a wrapper for the ``php`` command. This allows you to always select +the most appropriate PHP version according to the project which is running the +commands. It also loads the env vars automatically, which is important when +running non-Symfony commands: + +.. code-block:: terminal + + # runs the command with the default PHP version + $ php -r "..." + + # runs the command with the PHP version selected by the project + # (or the default PHP version if the project didn't select one) + $ symfony php -r "..." + +If you are using this wrapper frequently, consider aliasing the ``php`` command +to it: + +.. code-block:: terminal + + $ cd ~/.symfony/bin + $ cp symfony php + # now you can run "php ..." and the "symfony" command will be executed instead + + # other PHP commands can be wrapped too using this trick + $ cp symfony php-config + $ cp symfony pear + $ cp symfony pecl + +Local Domain Names +------------------ + +By default, projects are accessible at some random port of the ``127.0.0.1`` +local IP. However, sometimes it is preferable to associate a domain name to them: + +* It's more convenient when you work continuously on the same project because + port numbers can change but domains don't; +* The behavior of some applications depend on their domains/subdomains; +* To have stable endpoints, such as the local redirection URL for Oauth2. + +Setting up the Local Proxy +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Local domains are possible thanks to a local proxy provided by the Symfony +server. First, start the proxy: + +.. code-block:: terminal + + $ symfony proxy:start + +If this is the first time you run the proxy, you must follow these additional steps: + +* Open the **network configuration** of your operating system; +* Find the **proxy settings** and select the **"Automatic Proxy Configuration"**; +* Set the following URL as its value: ``https://127.0.0.1:7080/proxy.pac`` + +Defining the Local Domain +~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, Symfony proposes ``.wip`` (for *Work in Progress*) for the local +domains. You can define a local domain for your project as follows: + +.. code-block:: terminal + + $ cd my-project/ + $ symfony proxy:domain:attach my-domain + +If you have installed the local proxy as explained in the previous section, you +can now browse ``https://my-domain.wip`` to access your local project with the +new custom domain. + +.. tip:: + + Browse the https://127.0.0.1:7080 URL to get the full list of local project + directories, their custom domains, and port numbers. + +When running console commands, add the ``HTTPS_PROXY`` env var to make custom +domains work: + +.. code-block:: terminal + + $ HTTPS_PROXY=https://127.0.0.1:7080 curl https://my-domain.wip + +.. tip:: + + If you prefer to use a different TLD, edit the ``~/.symfony/proxy.json`` + file (where ``~`` means the path to your user directory) and change the + value of the ``tld`` option from ``wip`` to any other TLD. + +Long-Running Commands +--------------------- + +Long-running commands, such as the ones that compile front-end web assets, block +the terminal and you can't run other commands at the same time. The Symfony +server provides a ``run`` command to wrap them as follows: + +.. code-block:: terminal + + # compile Webpack assets using Symfony Encore ... but do that in the + # background to not block the terminal + $ symfony run -d yarn encore dev --watch + + # continue working and running other commands... + + # from time to time, check the command logs if you want + $ symfony server:log + + # and you can also check if the command is still running + $ symfony server:status + Web server listening on ... + Command "yarn ..." running with PID ... + + # stop the web server (and all the associated commands) when you are finished + $ symfony server:stop + +Bonus Features +-------------- + +In addition to being a local web server, the Symfony server provides other +useful features: + +Looking for Security Vulnerabilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Instead of installing the :doc:`Symfony Security Checker ` +as a dependency of your projects, you can run the following command: + +.. code-block:: terminal + + $ symfony security:check + +This command uses the same vulnerability database as the Symfony Security +Checker but it does not make HTTP calls to the official API endpoint. Everything +(except cloning the public database) is done locally, which is the best for CI +(*continuous integration*) scenarios. + +Creating Symfony Projects +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to the `different ways of installing Symfony`_, you can use these +commands from the Symfony server: + +.. code-block:: terminal + + # creates a new project based on symfony/skeleton + $ symfony new my_project_name + + # creates a new project based on symfony/website-skeleton + $ symfony new --full my_project_name + + # creates a new project based on the Symfony Demo application + $ symfony new --demo my_project_name + +SymfonyCloud Integration +------------------------ + +The local Symfony server provides full, but optional, integration with +`SymfonyCloud`_, a service optimized to run your Symfony applications on the +cloud. It provides features such as creating environments, backups/snapshots, +and even access to a copy of the production data from your local machine to help +debug any issues. + +`Read SymfonyCloud technical docs`_. + +.. _`symfony.com/download`: https://symfony.com/download +.. _`different ways of installing Symfony`: https://symfony.com/download +.. _`SymfonyCloud`: https://symfony.com/cloud/ +.. _`Read SymfonyCloud technical docs`: https://symfony.com/doc/master/cloud/intro.html