minor #8135 Updated the installation instructions for Symfony 4 (javiereguiluz)

xabbuh · xabbuh · commit d7dd8dd257a0 · 2017-07-11T19:43:38.000+02:00
This PR was squashed before being merged into the master branch (closes #8135). Discussion ---------- Updated the installation instructions for Symfony 4 It's great to see how simple things are now (for example, there's nothing to say or explain about permissions because you can't have permissions problems when installing Symfony, because of the use of `umask()` by default). Commits ------- 2565b47 Updated the installation instructions for Symfony 4
diff --git a/setup.rst b/setup.rst
@@ -4,219 +4,117 @@
 Installing & Setting up the Symfony Framework
 =============================================
 
-This article explains how to install Symfony in different ways and how to solve
-the most common issues that may appear during the installation process.
+This article explains how to install Symfony and solve the most common issues
+that may appear during the installation process.
 
 .. seealso::
 
     Do you prefer video tutorials? Check out the `Joyful Development with Symfony`_
     screencast series from KnpUniversity.
 
+.. _installation-creating-the-app:
+
 Creating Symfony Applications
 -----------------------------
 
-Symfony provides a dedicated application called the **Symfony Installer** to ease
-the creation of Symfony applications. This installer is a PHP 5.4 compatible
-executable that needs to be installed on your system only once:
-
-.. code-block:: terminal
-
-    # Linux and macOS systems
-    $ sudo mkdir -p /usr/local/bin
-    $ sudo curl -LsS https://symfony.com/installer -o /usr/local/bin/symfony
-    $ sudo chmod a+x /usr/local/bin/symfony
-
-    # Windows systems
-    c:\> php -r "file_put_contents('symfony', file_get_contents('https://symfony.com/installer'));"
-
-.. note::
-
-    In Linux and macOS, a global ``symfony`` command is created. In Windows,
-    move the ``symfony`` file to a directory that's included in the ``PATH``
-    environment variable and create a ``symfony.bat`` file to create the global
-    command or move it to any other directory convenient for you:
-
-    .. code-block:: terminal
-
-        # for example, if WAMP is used ...
-        c:\> move symfony c:\wamp\bin\php
-        # create symfony.bat in the same folder
-        c:\> cd c:\wamp\bin\php
-        c:\> (echo @ECHO OFF & echo php "%~dp0symfony" %*) > symfony.bat
-        # ... then, execute the command as:
-        c:\> symfony
-
-        # moving it to your projects folder ...
-        c:\> move symfony c:\projects
-        # ... then, execute the command as
-        c:\> cd projects
-        c:\projects\> php symfony
-
-.. _installation-creating-the-app:
-
-Once the Symfony Installer is installed, create your first Symfony application
-with the ``new`` command:
+Symfony applications are created with `Composer`_, the package manager used by
+modern PHP applications. If you don't have Composer installed in your computer,
+start by :doc:`installing Composer globally </setup/composer>`. Then, execute
+this command to create a new empty Symfony application based on its latest
+stable version:
 
 .. code-block:: terminal
 
-    $ symfony new my_project_name
-
-This command creates a new directory called ``my_project_name/`` that contains
-an empty project based on the most recent stable Symfony version available. In
-addition, the installer checks if your system meets the technical requirements
-to execute Symfony applications. If not, you'll see the list of changes needed
-to meet those requirements.
-
-.. note::
-
-    If the installer doesn't work for you or doesn't output anything, make sure
-    that the PHP `Phar extension`_ is installed and enabled on your computer.
-
-.. note::
-
-    If the SSL certificates are not properly installed in your system, you
-    may get this error:
+    $ composer create-project symfony/skeleton my-project
 
-        cURL error 60: SSL certificate problem: unable to get local issuer certificate.
-
-    You can solve this issue as follows:
-
-    #. Download a file with the updated list of certificates from
-       https://curl.haxx.se/ca/cacert.pem
-    #. Move the downloaded ``cacert.pem`` file to some safe location in your system
-    #. Update your ``php.ini`` file and configure the path to that file:
-
-       .. code-block:: ini
-
-           ; Linux and macOS systems
-           curl.cainfo = "/path/to/cacert.pem"
-
-           ; Windows systems
-           curl.cainfo = "C:\path\to\cacert.pem"
+.. tip::
 
-Basing your Project on a Specific Symfony Version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    If your Internet connection is slow, you may think that Composer is not
+    doing anything. If that's your case, add the ``-vvv`` flag to the previous
+    command to display a detailed output of everything that Composer is doing.
 
-In case your project needs to be based on a specific Symfony version, use the
-optional second argument of the ``new`` command:
+If your project needs to be based on a specific Symfony version, use the
+optional third argument of the ``create-project`` command:
 
 .. code-block:: terminal
 
     # use the most recent version in any Symfony branch
-    $ symfony new my_project_name 2.8
-    $ symfony new my_project_name 3.1
+    $ composer create-project symfony/skeleton my-project "3.3.*"
 
     # use a specific Symfony version
-    $ symfony new my_project_name 2.8.3
-    $ symfony new my_project_name 3.1.5
+    $ composer create-project symfony/skeleton my-project "3.3.5"
 
     # use a beta or RC version (useful for testing new Symfony versions)
-    $ symfony new my_project 2.7.0-BETA1
-    $ symfony new my_project 2.7.0-RC1
-
-    # use the most recent 'lts' version (Long Term Support version)
-    $ symfony new my_project_name lts
-
-Each version has its *own* documentation, which you can select on any documentation
-page.
+    $ composer create-project symfony/skeleton my-project 3.3.0-BETA1
 
 .. note::
 
     Read the :doc:`Symfony Release process </contributing/community/releases>`
     to better understand why there are several Symfony versions and which one
     to use for your projects.
 
-Creating Symfony Applications with Composer
--------------------------------------------
-
-If you still use PHP 5.3 or can't use the Symfony installer for any reason, you
-can create Symfony applications with `Composer`_, the dependency manager used by
-modern PHP applications.
-
-If you don't have Composer installed in your computer, start by
-:doc:`installing Composer globally </setup/composer>`. Then, execute the
-``create-project`` command to create a new Symfony application based on its
-latest stable version:
-
-.. code-block:: terminal
-
-    $ composer create-project symfony/framework-standard-edition my_project_name
-
-You can also install any other Symfony version by passing a second argument to
-the ``create-project`` command:
-
-.. code-block:: terminal
-
-    $ composer create-project symfony/framework-standard-edition my_project_name "2.8.*"
-
-.. tip::
-
-    If your Internet connection is slow, you may think that Composer is not
-    doing anything. If that's your case, add the ``-vvv`` flag to the previous
-    command to display a detailed output of everything that Composer is doing.
-
 Running the Symfony Application
 -------------------------------
 
-Symfony leverages the internal PHP web server (available since PHP 5.4) to run
-applications while developing them. Therefore, running a Symfony application is
-a matter of browsing to the project directory and executing this command:
+Symfony provides a utility called ``server`` that leverages the internal PHP web
+server to run applications while developing them. First, install that utility
+in your application:
 
 .. code-block:: terminal
 
-    $ cd my_project_name/
-    $ php bin/console server:run
+    $ cd my-project/
+    $ composer require server
 
-Then, open your browser and access the ``http://localhost:8000/`` URL to see the
-Welcome Page of Symfony:
+Then, whenever you want to run the application, execute this command:
 
-.. image:: /_images/quick_tour/welcome.png
-   :align: center
-   :alt:   Symfony Welcome Page
-   :class: with-browser
+.. code-block:: terminal
 
-If you see a blank page or an error page instead of the Welcome Page, there is
-a directory permission misconfiguration. The solution to this problem is
-explained in the :doc:`/setup/file_permissions`.
+    $ php bin/console server:run
 
-When you are finished working on your Symfony application, stop the server by
-pressing ``Ctrl+C`` from the terminal or command console.
+Open your browser, access the ``http://localhost:8000/`` URL and you'll see the
+application running. When you are finished working on your Symfony application,
+stop the server by pressing ``Ctrl+C`` from the terminal or command console.
 
 .. tip::
 
     PHP's internal web server is great for developing, but should **not** be
     used on production. Instead, use Apache or Nginx.
     See :doc:`/setup/web_server_configuration`.
 
-Checking Symfony Application Configuration and Setup
-----------------------------------------------------
+Checking Symfony Requirements
+-----------------------------
 
-The Symfony Installer checks if your system is ready to run Symfony applications.
-However, the PHP configuration for the command console can be different from the
-PHP web configuration. For that reason, Symfony provides a visual configuration
-checker. Access the following URL to check your configuration and fix any issue
-before moving on:
+In addition to PHP 7.1, Symfony has other `technical requirements`_ that your
+server must meet. Symfony provides a tool called "Requirements Checker" (or
+``req-checker``) to check those requirements:
 
-.. code-block:: text
+.. code-block:: terminal
+
+    $ cd my-project/
+    $ composer require req-checker
 
-    http://localhost:8000/config.php
+The ``req-checker`` utility adds two PHP scripts in your application:
+``bin/check.php`` and ``public/check.php``. Run the first one in the command
+console and the second one in the browser. This is needed because PHP can define
+a different configuration for both the command console and the web server, so
+you need to check both.
 
-Fixing Permissions Problems
----------------------------
+Once you've fixed all the reported issues, uninstall the requirements checker:
 
-If you have any file permission errors or see a white screen, then read
-:doc:`/setup/file_permissions` for more information.
+.. code-block:: terminal
+
+    $ composer remove req-checker
 
 .. _installation-updating-vendors:
 
 Updating Symfony Applications
 -----------------------------
 
-At this point, you've created a fully-functional Symfony application! Every Symfony
-app depends on a number of third-party libraries stored in the ``vendor/`` directory
-and managed by Composer.
+At this point, you've created a fully-functional Symfony application! Every
+Symfony app depends on a number of third-party libraries stored in the
+``vendor/`` directory and managed by Composer.
 
-Updating those libraries frequently is a good practice to prevent bugs and
+Updating those libraries frequently is a good practice to fix bugs and prevent
 security vulnerabilities. Execute the ``update`` Composer command to update them
 all at once (this can take up to several minutes to complete depending on the
 complexity of your project):
@@ -226,68 +124,64 @@ complexity of your project):
     $ cd my_project_name/
     $ composer update
 
-.. tip::
-
-    Symfony provides a command to check whether your project's dependencies
-    contain any known security vulnerability:
+.. _install-existing-app:
 
-    .. code-block:: terminal
+Installing an Existing Symfony Application
+------------------------------------------
 
-        $ php bin/console security:check
+When working collaboratively in a Symfony application, it's uncommon to create
+a new Symfony application as explained in the previous sections. Instead,
+someone else has already created and submitted it to a shared repository.
 
-    A good security practice is to execute this command regularly to be able to
-    update or replace compromised dependencies as soon as possible.
+It's recommended to not submit some files (``.env``) and directories (``vendor/``,
+cache, logs) to the repository, so you'll have to do the following when
+installing an existing Symfony application:
 
-.. _installing-a-symfony2-distribution:
+.. code-block:: terminal
 
-Installing the Symfony Demo or Other Distributions
---------------------------------------------------
+    # clone the project to download its contents
+    $ cd projects/
+    $ git clone ...
 
-You've already downloaded the `Symfony Standard Edition`_: the default starting project
-for all Symfony apps. You'll use this project throughout the documentation to build
-your app!
+    # make Composer install the project's dependencies into vendor/
+    $ cd my-project/
+    $ composer install
 
-Symfony also provides some other projects and starting skeletons that you can use:
+Checking for Security Vulnerabilities
+-------------------------------------
 
-`The Symfony Demo Application`_
-    This is a fully-functional application that shows the recommended way to develop
-    Symfony applications. The app has been conceived as a learning tool for Symfony
-    newcomers and its source code contains tons of comments and helpful notes.
+Symfony provides a utility called "Security Checker" (or ``sec-checker``) to
+check whether your project's dependencies contain any known security
+vulnerability. Run this command to install it in your application:
 
-`The Symfony CMF Standard Edition`_
-    The `Symfony CMF`_ is a project that helps make it easier for developers to add
-    CMS functionality to their Symfony applications. This is a starting project
-    containing the Symfony CMF.
+.. code-block:: terminal
 
-`The Symfony REST Edition`_
-    Shows how to build an application that provides a RESTful API using the
-    `FOSRestBundle`_ and several other related Bundles.
+    $ cd my-project/
+    $ composer require sec-checker
 
-.. _install-existing-app:
+From now on, this command will be run automatically whenever you install or
+update any dependency in the application.
 
-Installing an Existing Symfony Application
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Installing the Symfony Demo application
+---------------------------------------
 
-When working collaboratively in a Symfony application, it's uncommon to create
-a new Symfony application as explained in the previous sections. Instead,
-someone else has already created and submitted it to a shared repository.
+`The Symfony Demo Application`_ is a fully-functional application that shows the
+recommended way to develop Symfony applications. It's a great learning tool for
+Symfony newcomers and its code contains tons of comments and helpful notes.
 
-It's recommended to not submit some files (:ref:`parameters.yml <config-parameters-yml>`)
-and directories (``vendor/``, cache, logs) to the repository, so you'll have to do
-the following when installing an existing Symfony application:
+Run the following command to download and install the Symfony Demo application:
 
 .. code-block:: terminal
 
-    # clone the project to download its contents
-    $ cd projects/
-    $ git clone ...
+    $ composer create-project symfony/symfony-demo my-project
 
-    # make Composer install the project's dependencies into vendor/
-    $ cd my_project_name/
-    $ composer install
+Now, enter the ``my-project/`` directory, run the internal web server and
+browse ``http://127.0.0.1:8000``:
+
+.. code-block:: terminal
 
-    # now Composer will ask you for the values of any undefined parameter
-    $ ...
+    $ cd my-project
+    $ php bin/console server:start
 
 Keep Going!
 -----------
@@ -315,10 +209,5 @@ Go Deeper with Setup
 
 .. _`Joyful Development with Symfony`: http://knpuniversity.com/screencast/symfony
 .. _`Composer`: https://getcomposer.org/
-.. _`Phar extension`: http://php.net/manual/en/intro.phar.php
-.. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard
+.. _`technical requirements`: https://symfony.com/doc/current/reference/requirements.html
 .. _`The Symfony Demo application`: https://github.com/symfony/symfony-demo
-.. _`The Symfony CMF Standard Edition`: https://github.com/symfony-cmf/standard-edition
-.. _`Symfony CMF`: http://cmf.symfony.com/
-.. _`The Symfony REST Edition`: https://github.com/gimler/symfony-rest-edition
-.. _`FOSRestBundle`: https://github.com/FriendsOfSymfony/FOSRestBundle
