Lots of minor fixes

symfony · javiereguiluz · Mar 22, 2019 · Mar 25, 2019 · Mar 27, 2019 · Mar 29, 2019
commit 78089182cbebd832450043b7658c41adef72cf5b
diff --git 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,18 +67,20 @@ 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
 ----------------------------------

 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