diff --git a/cookbook/index.rst b/cookbook/index.rst index 3587d3e4efd..98828a56287 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -18,6 +18,7 @@ The Cookbook event_dispatcher/index form/index frontend/index + install/index logging/index profiler/index request/index diff --git a/cookbook/install/index.rst b/cookbook/install/index.rst new file mode 100644 index 00000000000..9177815770e --- /dev/null +++ b/cookbook/install/index.rst @@ -0,0 +1,8 @@ +Install and Upgrade +=================== + +.. toctree:: + :maxdepth: 2 + + upgrading + unstable_versions diff --git a/cookbook/install/unstable_versions.rst b/cookbook/install/unstable_versions.rst new file mode 100644 index 00000000000..b1d2b9abc77 --- /dev/null +++ b/cookbook/install/unstable_versions.rst @@ -0,0 +1,80 @@ +How to Install or Upgrade to the Latest, Unreleased Symfony Version +=================================================================== + +In this article, you'll learn how to install and use new Symfony versions before +they are released as stable versions. + +Creating a New Project Based on an Unstable Symfony Version +----------------------------------------------------------- + +Suppose that Symfony 2.7 version hasn't been released yet and you want to create +a new project to test its features. First, :doc:`install the Composer ` +package manager. Then, open a command console, enter your project's directory and +execute the following command: + +.. code-block:: bash + + $ composer create-project symfony/framework-standard-edition my_project "2.7.*" --stability=dev + +Once the command finishes its execution, you'll have a new Symfony project created +in the ``my_project/`` directory and based on the most recent code found in the +``2.7`` branch. + +If you want to test a beta version, use ``beta`` as the value of the ``stability`` +option: + +.. code-block:: bash + + $ composer create-project symfony/framework-standard-edition my_project "2.7.*" --stability=beta + +Upgrading your Project to an Unstable Symfony Version +----------------------------------------------------- + +Suppose again that Symfony 2.7 hasn't been released yet and you want to upgrade +an existing application to test that your project works with it. + +First, open the ``composer.json`` file located in the root directory of your +project. Then, edit the value of the version defined for the ``symfony/symfony`` +dependency as follows: + +.. code-block:: json + + { + "require": { + // ... + "symfony/symfony" : "2.7.*@dev" + } + } + +Finally, open a command console, enter your project directory and execute the +following command to update your project dependencies: + +.. code-block:: bash + + $ composer update symfony/symfony + +If you prefer to test a Symfony beta version, replace the ``"2.7.*@dev"`` constraint +by ``"2.7.0-beta1"`` to install a specific beta number or ``2.7.*@beta`` to get +the most recent beta version. + +After upgrading the Symfony version, read the :doc:`Symfony Upgrading Guide ` +to learn how you should proceed to update your application's code in case the new +Symfony version has deprecated some of its features. + +.. tip:: + + If you use Git to manage the project's code, it's a good practice to create + a new branch to test the new Symfony version. This solution avoids introducing + any issue in your application and allows you to test the new version with + total confidence: + + .. code-block:: bash + + $ cd projects/my_project/ + $ git checkout -b testing_new_symfony + # ... update composer.json configuration + $ composer update symfony/symfony + + # ... after testing the new Symfony version + $ git checkout master + $ git branch -D testing_new_symfony diff --git a/cookbook/install/upgrading.rst b/cookbook/install/upgrading.rst new file mode 100644 index 00000000000..34d11369ce5 --- /dev/null +++ b/cookbook/install/upgrading.rst @@ -0,0 +1,137 @@ +How to Upgrade Your Symfony Project +=================================== + +So a new Symfony release has come out and you want to upgrade, great! Fortunately, +because Symfony protects backwards-compatibility very closely, this *should* +be quite easy. + +There are two types of upgrades, and both are a little different: + +* :ref:`upgrading-patch-version` +* :ref:`upgrading-minor-version` + +.. _upgrading-patch-version: + +Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1) +----------------------------------------------- + +If you're upgrading and only the patch version (the last number) is changing, +then it's *really* easy: + +.. code-block:: bash + + $ composer update symfony/symfony + +That's it! You should not encounter any backwards-compatibility breaks or +need to change anything else in your code. That's because when you started +your project, your ``composer.json`` included Symfony using a constraint +like ``2.6.*``, where only the *last* version number will change when you +update. + +You may also want to upgrade the rest of your libraries. If you've done a +good job with your `version constraints`_ in ``composer.json``, you can do +this safely by running: + +.. code-block:: bash + + $ composer update + +But beware. If you have some bad `version constraints`_ in your ``composer.json``, +(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries +to new versions that contain backwards-compatibility breaking changes. + +.. _upgrading-minor-version: + +Upgrading a Minor Version (e.g. 2.5.3 to 2.6.1) +----------------------------------------------- + +If you're upgrading a minor version (where the middle number changes), then +you should also *not* encounter significant backwards compatibility changes. +For details, see our :doc:`/contributing/code/bc`. + +However, some backwards-compatibility breaks *are* possible, and you'll learn +in a second how to prepare for them. + +There are two steps to upgrading: + +:ref:`upgrade-minor-symfony-composer`; +:ref:`upgrade-minor-symfony-code` + +1) Update the Symfony Library via Composer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, you need to update Symfony by modifying your ``composer.json`` file +to use the new version: + +.. code-block:: json + + { + "...": "...", + + "require": { + "php": ">=5.3.3", + "symfony/symfony": "2.6.*", + "...": "... no changes to anything else..." + }, + "...": "...", + } + +Next, use Composer to download new versions of the libraries: + +.. code-block:: bash + + $ composer update symfony/symfony + +You may also want to upgrade the rest of your libraries. If you've done a +good job with your `version constraints`_ in ``composer.json``, you can do +this safely by running: + +.. code-block:: bash + + $ composer update + +But beware. If you have some bad `version constraints`_ in your ``composer.json``, +(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries +to new versions that contain backwards-compatibility breaking changes. + +2) Updating Your Code to Work with the new Version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In theory, you should be done! However, you *may* need to make a few changes +to your code to get everything working. Additionally, some features you're +using might still work, but might now be deprecated. That's actually ok, +but if you know about these deprecations, you can start to fix them over +time. + +Every version of Symfony comes with an UPGRADE file that describes these +changes. Below are links to the file for each version, which you'll need +to read to see if you need any code changes. + +.. tip:: + + Don't see the version here that you're upgrading to? Just find the + UPGRADE-X.X.md file for the appropriate version on the `Symfony Repository`_. + +Upgrading to Symfony 2.6 +........................ + +First, of course, update your ``composer.json`` file with the ``2.6`` version +of Symfony as described above in :ref:`upgrade-minor-symfony-composer`. + +Next, check the `UPGRADE-2.6`_ document for details about any code changes +that you might need to make in your project. + +Upgrading to Symfony 2.5 +........................ + +First, of course, update your ``composer.json`` file with the ``2.5`` version +of Symfony as described above in :ref:`upgrade-minor-symfony-composer`. + +Next, check the `UPGRADE-2.5`_ document for details about any code changes +that you might need to make in your project. + +.. _`UPGRADE-2.5`: https://github.com/symfony/symfony/blob/2.5/UPGRADE-2.5.md +.. _`UPGRADE-2.6`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md +.. _`Symfony Repository`: https://github.com/symfony/symfony +.. _`Composer Package Versions`: https://getcomposer.org/doc/01-basic-usage.md#package-versions +.. _`version constraints`: https://getcomposer.org/doc/01-basic-usage.md#package-versions diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 2c4d8eb94f6..1faf17e7f84 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -112,6 +112,11 @@ * :doc:`/cookbook/frontend/bower` +* :doc:`/cookbook/install/index` + + * :doc:`/cookbook/install/upgrading` + * :doc:`/cookbook/install/unstable_versions` + * :doc:`/cookbook/logging/index` * :doc:`/cookbook/logging/monolog` diff --git a/redirection_map b/redirection_map index 7e60794f8c6..b0cb87b38ad 100644 --- a/redirection_map +++ b/redirection_map @@ -14,6 +14,7 @@ /cookbook/service_container/parentservices /components/dependency_injection/parentservices /cookbook/service_container/factories /components/dependency_injection/factories /cookbook/service_container/tags /components/dependency_injection/tags +/cookbook/upgrading /cookbook/install/upgrading /reference/configuration/mongodb /bundles/DoctrineMongoDBBundle/config /reference/YAML /components/yaml /components/dependency_injection /components/dependency_injection/introduction