Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3303206

Browse files
committed
Merge branch '4.4' into 5.0
* 4.4: Adding details about recipe upgrade system and upgrade improvements Updated link
2 parents 71f97f8 + 9f943a3 commit 3303206

File tree

5 files changed

+113
-43
lines changed

5 files changed

+113
-43
lines changed

messenger.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1473,6 +1473,6 @@ Learn more
14731473

14741474
/messenger/*
14751475

1476-
.. _`Enqueue's transport`: https://github.com/php-enqueue/messenger-adapter
1476+
.. _`Enqueue's transport`: https://github.com/sroze/messenger-enqueue-transport
14771477
.. _`streams`: https://redis.io/topics/streams-intro
14781478
.. _`Supervisor docs`: http://supervisord.org/

setup.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,8 @@ you'll see a Composer error explaining that ``logger`` is not a valid package
160160
name. However, if the application has Symfony Flex installed, that command
161161
installs and enables all the packages needed to use the official Symfony logger.
162162

163+
.. _recipes-description:
164+
163165
This is possible because lots of Symfony packages/bundles define **"recipes"**,
164166
which are a set of automated instructions to install and enable packages into
165167
Symfony applications. Flex keeps tracks of the recipes it installed in a

setup/_update_dep_errors.rst.inc

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,17 @@
11
Dependency Errors
22
~~~~~~~~~~~~~~~~~
33

4-
If you get a dependency error, it may simply mean that you need to upgrade
5-
other Symfony dependencies too. In that case, try the following command:
4+
If you get a dependency error, it may mean that you also need to upgrade
5+
other libraries that are dependencies of the Symfony libraries. To allow
6+
that, pass the ``--with-all-dependencies`` flag:
67

78
.. code-block:: terminal
89

910
$ composer update "symfony/*" --with-all-dependencies
1011

11-
This updates ``symfony/symfony`` and *all* packages that it depends on, which will
12-
include several other packages. By using tight version constraints in
13-
``composer.json``, you can control what versions each library upgrades to.
12+
This updates ``symfony/*`` and *all* packages that those packages depend on.
13+
By using tight version constraints in ``composer.json``, you can control what
14+
versions each library upgrades to.
1415
1516
If this still doesn't work, your ``composer.json`` file may specify a version
1617
for a library that is not compatible with the newer Symfony version. In that

setup/upgrade_major.rst

Lines changed: 39 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,11 @@ it will be removed/changed in the future and that you should stop using it.
3333
When the major version is released (e.g. 5.0.0), all deprecated features and
3434
functionality are removed. So, as long as you've updated your code to stop
3535
using these deprecated features in the last version before the major (e.g.
36-
4.4.*), you should be able to upgrade without a problem.
36+
``4.4.*``), you should be able to upgrade without a problem. That means that
37+
you should first :doc:`upgrade to the last minor version </setup/upgrade_minor>`
38+
(e.g. 4.4) so that you can see *all* the deprecations.
3739

38-
To help you with this, deprecation notices are triggered whenever you end up
40+
To help you find deprecations, notices are triggered whenever you end up
3941
using a deprecated feature. When visiting your application in the
4042
:ref:`dev environment <configuration-environments>`
4143
in your browser, these notices are shown in the web dev toolbar:
@@ -123,24 +125,44 @@ done!
123125
2) Update to the New Major Version via Composer
124126
-----------------------------------------------
125127

126-
Once your code is deprecation free, you can update all the Symfony packages via
127-
Composer by modifying your ``composer.json`` file. In this file update all
128-
mentions of ``4.*`` to ``5.0.*``:
128+
Once your code is deprecation free, you can update the Symfony library via
129+
Composer by modifying your ``composer.json`` file and changing all the libraries
130+
starting with ``symfony/`` to the new major version:
129131

130-
.. code-block:: json
132+
.. code-block:: diff
131133
132134
{
133135
"...": "...",
134136
135137
"require": {
136-
"symfony/console": "^5.0",
137-
"symfony/dotenv": "^5.0",
138-
"symfony/flex": "^1.3.1",
139-
"symfony/framework-bundle": "^5.0",
140-
"symfony/validator": "^5.0",
141-
"symfony/yaml": "^5.0"
138+
- "symfony/cache": "4.3.*",
139+
+ "symfony/cache": "4.4.*",
140+
- "symfony/config": "4.3.*",
141+
+ "symfony/config": "4.4.*",
142+
- "symfony/console": "4.3.*",
143+
+ "symfony/console": "4.4.*",
144+
"...": "...",
145+
146+
"...": "A few libraries starting with
147+
symfony/ follow their versioning scheme. You
148+
do not need to update these versions: you can
149+
upgrade them independently whenever you want",
150+
"symfony/monolog-bundle": "^3.5",
142151
},
143-
"...": "..."
152+
"...": "...",
153+
}
154+
155+
Your ``composer.json`` file should also have an ``extra`` block that you will
156+
*also* need to update:
157+
158+
.. code-block:: diff
159+
160+
"extra": {
161+
"symfony": {
162+
"...": "...",
163+
- "require": "4.4.*"
164+
+ "require": "5.0.*"
165+
}
144166
}
145167
146168
At the bottom of your ``composer.json`` file, in the ``extra`` block you can
@@ -160,7 +182,7 @@ Next, use Composer to download new versions of the libraries:
160182

161183
.. code-block:: terminal
162184
163-
$ composer update "symfony/*"
185+
$ composer update symfony/*
164186
165187
.. include:: /setup/_update_dep_errors.rst.inc
166188

@@ -171,7 +193,6 @@ Next, use Composer to download new versions of the libraries:
171193
3) Update your Code to Work with the New Version
172194
------------------------------------------------
173195

174-
The next major version *may* also contain new BC breaks as a BC layer is not always
175-
a possibility. Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major
176-
version) included in the Symfony repository for any BC break that you need to be aware
177-
of.
196+
In some rare situations, the next major version *may* contain backwards-compatibility
197+
breaks. Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major version)
198+
included in the Symfony repository for any BC break that you need to be aware of.

setup/upgrade_minor.rst

Lines changed: 65 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -22,37 +22,43 @@ There are two steps to upgrading a minor version:
2222
------------------------------------------
2323

2424
The ``composer.json`` file is configured to allow Symfony packages to be
25-
upgraded to patch versions. But, if you would like the packages to be upgraded
26-
to minor versions, check that the version constrains of the Symfony dependencies
27-
are like this:
25+
upgraded to patch versions. But to upgrade to a new minor version, you will
26+
probably need to update the version constraint next to each library starting
27+
``symfony/``. Suppose you are upgrading from Symfony 4.3 to 4.4:
2828

29-
.. code-block:: json
29+
.. code-block:: diff
3030
3131
{
3232
"...": "...",
3333
3434
"require": {
35-
"symfony/cache": "^4.0",
36-
"symfony/config": "^4.0",
37-
"symfony/console": "^4.0",
38-
"symfony/debug": "^4.0",
39-
"symfony/dependency-injection": "^4.0",
40-
"symfony/dotenv": "^4.0",
41-
"...": "..."
35+
- "symfony/cache": "4.3.*",
36+
+ "symfony/cache": "4.4.*",
37+
- "symfony/config": "4.3.*",
38+
+ "symfony/config": "4.4.*",
39+
- "symfony/console": "4.3.*",
40+
+ "symfony/console": "4.4.*",
41+
"...": "...",
42+
43+
"...": "A few libraries starting with
44+
symfony/ follow their versioning scheme. You
45+
do not need to update these versions: you can
46+
upgrade them independently whenever you want",
47+
"symfony/monolog-bundle": "^3.5",
4248
},
4349
"...": "...",
4450
}
4551
46-
At the bottom of your ``composer.json`` file, in the ``extra`` block you can
47-
find a data setting for the symfony version. Make sure to also upgrade
48-
this one. For instance, update it to ``4.4.*`` to upgrade to Symfony 4.4:
52+
Your ``composer.json`` file should also have an ``extra`` block that you will
53+
*also* need to update:
4954

50-
.. code-block:: json
55+
.. code-block:: diff
5156
5257
"extra": {
5358
"symfony": {
54-
"allow-contrib": false,
55-
"require": "4.4.*"
59+
"...": "...",
60+
- "require": "4.3.*"
61+
+ "require": "4.4.*"
5662
}
5763
}
5864
@@ -76,12 +82,52 @@ to your code to get everything working. Additionally, some features you're
7682
using might still work, but might now be deprecated. While that's just fine,
7783
if you know about these deprecations, you can start to fix them over time.
7884

79-
Every version of Symfony comes with an UPGRADE file (e.g. `UPGRADE-4.1.md`_)
85+
Every version of Symfony comes with an UPGRADE file (e.g. `UPGRADE-4.4.md`_)
8086
included in the Symfony directory that describes these changes. If you follow
8187
the instructions in the document and update your code accordingly, it should be
8288
safe to update in the future.
8389

8490
These documents can also be found in the `Symfony Repository`_.
8591

92+
.. _updating-flex-recipes:
93+
94+
3) Updating Recipes
95+
-------------------
96+
97+
Over time - and especially when you upgrade to a new version of a library - an
98+
updated version of the :ref:`recipe <recipes-description>` may be available.
99+
These updates are usually minor - e.g. new comments in a configuration file - but
100+
it's a good idea to update the core Symfony recipes.
101+
102+
Symfony Flex provides several commands to help upgrade your recipes. Be sure to
103+
commit any unrelated changes you're working on before starting:
104+
105+
.. versionadded:: 1.6
106+
107+
The recipes commands were introduced in Symfony Flex 1.6.
108+
109+
.. code-block:: terminal
110+
111+
# see a list of all installed recipes and which have updates available
112+
$ composer recipes
113+
114+
# see detailed information about a specific recipes
115+
$ composer recipes symfony/framework-bundle
116+
117+
# update a specific recipes
118+
$ composer recipes:install symfony/framework-bundle --force -v
119+
120+
The tricky part of this process is that the recipe "update" does not perform
121+
any intelligent "upgrading" of your code. Instead, **the updates process re-installs
122+
the latest version of the recipe** which means that **your custom code will be
123+
overridden completely**. After updating a recipe, you need to carefully choose
124+
which changes you want, and undo the rest.
125+
126+
.. admonition:: Screencast
127+
:class: screencast
128+
129+
For a detailed example, see the `SymfonyCasts Symfony 5 Upgrade Tutorial`_.
130+
86131
.. _`Symfony Repository`: https://github.com/symfony/symfony
87-
.. _`UPGRADE-4.1.md`: https://github.com/symfony/symfony/blob/4.1/UPGRADE-4.1.md
132+
.. _`UPGRADE-4.4.md`: https://github.com/symfony/symfony/blob/4.4/UPGRADE-4.4.md
133+
.. _`SymfonyCasts Symfony 5 Upgrade Tutorial`: https://symfonycasts.com/screencast/symfony5-upgrade

0 commit comments

Comments
 (0)