From 32f84dbfa9d35a5de44cd005924401a483436769 Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Fri, 22 Mar 2019 16:57:09 +0100
Subject: [PATCH 1/4] Documented the local Symfony server

---
 setup/symfony_server.rst | 271 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 271 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..4fb4380ae2f
--- /dev/null
+++ b/setup/symfony_server.rst
@@ -0,0 +1,271 @@
+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 apps.
+
+This server is not intended for production use and 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.
+
+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 web 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 in your browser, or run this command:
+    $ symfony open:local
+
+Running the server this way makes it display the log messages in the console, so
+you can't run other commands. 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 early detect
+problems with mixed content 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. You can now browse your local app using
+HTTPS instead of HTTP.
+
+Different PHP Settings Per Project
+----------------------------------
+
+Selecting a Different PHP Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have multiple PHP versions installed in your computer, you can tell
+Symfony which one to use creating a file called ``.php-version`` at the project
+root dir:
+
+.. 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
+
+This other command is useful if you don't remember all the PHP versions
+installed in your computer:
+
+.. code-block:: terminal
+
+    $ symfony local:php:list
+
+Overriding PHP Config Options Per Project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can change the value of any PHP runtime config option per project creating a
+file called ``php.ini`` at the project root dir. 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 of the ``php`` command to always select the most
+appropriate PHP version according to the project which is running the 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
+
+Local Domain Names
+------------------
+
+By default, projects are accessible at some random port of the ``12.7.0.0.1``
+local IP. However, sometimes 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 apps depend on their domains/subdomains;
+* To have stable endpoints, such as the local redirection URL of 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*) as the local
+domains (but you can choose any other domain and TLD you like). Define a local
+domain for a project as follows:
+
+.. code-block:: terminal
+
+    $ cd my-project/
+    $ symfony proxy:domain:attach my-domain.wip
+
+If you have installed the local proxy as explained in the previous section, you
+can now browse ``https://my-domain.wip`` to access to 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
+
+Long-Running Commands
+---------------------
+
+Long-running commands, such as the ones related to compiling front-end web
+assets, block the terminal and you can't run other commands. 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 command (and the whole server) when you are finished
+    $ symfony server:stop
+
+Bonus Features
+--------------
+
+The Symfony server is much more than a local web server and it includes other
+useful features.
+
+Looking for Security Vulnerabilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Instead of installing the :doc:`Symfony Security Checker </security/security_checker>`
+as a dependency of your projects, you can use this command from the Symfony server:
+
+.. code-block:: terminal
+
+    $ symfony security:check
+
+This command uses the same vulnerability database as the Symfony Security
+Checker but it also caches that information to keep checking security when
+it's not possible to access to that public database.
+
+Creating Symfony Projects
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to the `different ways to install Symfony`_, you can use this
+command from the Symfony server:
+
+.. code-block:: terminal
+
+    # creates a new project based on the Symfony Skeleton
+    $ symfony new my_project_name
+
+    # creates a new project based on the 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 apps on the cloud.
+It provides features such as creating environments, backups/snapshots, and
+even access to a copy of the production data in your local machine to help
+you debug any issues.
+
+`Read SymfonyCloud technical docs`_.
+
+.. _`symfony.com/download`: https://symfony.com/download
+.. _`different ways to install Symfony`: https://symfony.com/download
+.. _`SymfonyCloud`: https://symfony.com/cloud/
+.. _`Read SymfonyCloud technical docs`: https://symfony.com/doc/master/cloud/intro.html

From 78089182cbebd832450043b7658c41adef72cf5b Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Mon, 25 Mar 2019 12:46:27 +0100
Subject: [PATCH 2/4] Lots of minor fixes

---
 setup/symfony_server.rst | 110 ++++++++++++++++++++++-----------------
 1 file changed, 62 insertions(+), 48 deletions(-)

diff --git a/setup/symfony_server.rst b/setup/symfony_server.rst
index 4fb4380ae2f..98d525f49d6 100644
--- a/setup/symfony_server.rst
+++ b/setup/symfony_server.rst
@@ -2,12 +2,14 @@ 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 apps.
+internal PHP web server, etc.). However, Symfony provides its own web server to
+make you more productive while developing your applications.
 
-This server is not intended for production use and 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.
+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
 ------------
@@ -31,11 +33,11 @@ common workflow to serve a Symfony project:
       [OK] Web server listening on http://127.0.0.1:....
       ...
 
-    # Now, browse the given URL in your browser, or run this command:
+    # 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 can't run other commands. If you prefer, you can run the Symfony server in
+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
@@ -53,8 +55,8 @@ the background:
 Enabling TLS
 ------------
 
-Browsing the secure version of your apps locally is important to early detect
-problems with mixed content and to run libraries that only run in HTTPS.
+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:
 
@@ -65,8 +67,10 @@ server automates everything. First, run this command:
 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. You can now browse your local app using
-HTTPS instead of HTTP.
+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
 ----------------------------------
@@ -74,9 +78,9 @@ Different PHP Settings Per Project
 Selecting a Different PHP Version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you have multiple PHP versions installed in your computer, you can tell
+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 dir:
+root directory:
 
 .. code-block:: terminal
 
@@ -88,8 +92,15 @@ root dir:
     # use any PHP 7.x version available
     $ echo "7" > .php-version
 
-This other command is useful if you don't remember all the PHP versions
-installed in your computer:
+.. 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.
+
+This command is useful if you don't remember all the PHP versions installed on
+your computer:
 
 .. code-block:: terminal
 
@@ -98,8 +109,8 @@ installed in your computer:
 Overriding PHP Config Options Per Project
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can change the value of any PHP runtime config option per project creating a
-file called ``php.ini`` at the project root dir. Add only the options you want
+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
@@ -114,9 +125,11 @@ to override:
 Running Commands with Different PHP Versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When running different PHP versions, it's useful to use the main ``symfony``
-command as a wrapper of the ``php`` command to always select the most
-appropriate PHP version according to the project which is running the commands:
+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
 
@@ -139,13 +152,13 @@ to it:
 Local Domain Names
 ------------------
 
-By default, projects are accessible at some random port of the ``12.7.0.0.1``
-local IP. However, sometimes is preferable to associate a domain name to them:
+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 apps depend on their domains/subdomains;
-* To have stable endpoints, such as the local redirection URL of Oauth2.
+* 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -166,18 +179,18 @@ If this is the first time you run the proxy, you must follow these additional st
 Defining the Local Domain
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-By default, Symfony proposes ``.wip`` (for *Work in Progress*) as the local
-domains (but you can choose any other domain and TLD you like). Define a local
-domain for a project as follows:
+By default, Symfony proposes ``.wip`` (for *Work in Progress*) for the local
+domains (but you can choose any other TLD you like). Define a local domain for a
+project as follows:
 
 .. code-block:: terminal
 
     $ cd my-project/
-    $ symfony proxy:domain:attach my-domain.wip
+    $ 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 to your local project with
-the new custom domain.
+can now browse ``https://my-domain.wip`` to access your local project with the
+new custom domain.
 
 .. tip::
 
@@ -194,9 +207,9 @@ domains work:
 Long-Running Commands
 ---------------------
 
-Long-running commands, such as the ones related to compiling front-end web
-assets, block the terminal and you can't run other commands. The Symfony server
-provides a ``run`` command to wrap them as follows:
+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
 
@@ -214,41 +227,42 @@ provides a ``run`` command to wrap them as follows:
     Web server listening on ...
     Command "yarn ..." running with PID ...
 
-    # stop the command (and the whole server) when you are finished
+    # stop the web server (and all the associated commands) when you are finished
     $ symfony server:stop
 
 Bonus Features
 --------------
 
-The Symfony server is much more than a local web server and it includes other
-useful 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 </security/security_checker>`
-as a dependency of your projects, you can use this command from the Symfony server:
+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 also caches that information to keep checking security when
-it's not possible to access to that public database.
+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 to install Symfony`_, you can use this
-command from the Symfony server:
+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 the Symfony Skeleton
+    # creates a new project based on symfony/skeleton
     $ symfony new my_project_name
 
-    # creates a new project based on the Symfony Website Skeleton
+    # 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
@@ -258,14 +272,14 @@ SymfonyCloud Integration
 ------------------------
 
 The local Symfony server provides full, but optional, integration with
-`SymfonyCloud`_, a service optimized to run your Symfony apps on the cloud.
-It provides features such as creating environments, backups/snapshots, and
-even access to a copy of the production data in your local machine to help
-you debug any issues.
+`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 to install Symfony`: 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

From b24c4af1b6c8bf2b0a193ebf75c91d44a431e45c Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Wed, 27 Mar 2019 11:20:39 +0100
Subject: [PATCH 3/4] More improvements suggested by reviewers

---
 setup/symfony_server.rst | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/setup/symfony_server.rst b/setup/symfony_server.rst
index 98d525f49d6..d245a32b289 100644
--- a/setup/symfony_server.rst
+++ b/setup/symfony_server.rst
@@ -21,9 +21,9 @@ and follow the instructions for your operating system.
 Getting Started
 ---------------
 
-The Symfony web 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:
+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
 
@@ -37,8 +37,8 @@ common workflow to serve a Symfony project:
     $ 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:
+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
 
@@ -99,13 +99,17 @@ root directory:
     directory to set the same PHP version for a group of projects under that
     directory.
 
-This command is useful if you don't remember all the PHP versions installed on
-your computer:
+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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -180,8 +184,7 @@ Defining the Local Domain
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By default, Symfony proposes ``.wip`` (for *Work in Progress*) for the local
-domains (but you can choose any other TLD you like). Define a local domain for a
-project as follows:
+domains. You can define a local domain for your project as follows:
 
 .. code-block:: terminal
 
@@ -204,6 +207,12 @@ domains work:
 
     $ 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
 ---------------------
 

From 6f0b34ff88ec08896916bb7ee7aac25491dc515a Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Fri, 29 Mar 2019 17:30:38 +0100
Subject: [PATCH 4/4] Tweak

---
 setup/symfony_server.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/setup/symfony_server.rst b/setup/symfony_server.rst
index d245a32b289..5f991b827fa 100644
--- a/setup/symfony_server.rst
+++ b/setup/symfony_server.rst
@@ -153,6 +153,11 @@ to it:
     $ 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
 ------------------