Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 076636c

Browse filesBrowse files
weaverryanweaverryan
committed
adding details about recipe upgrade system and other tweaks
1 parent 67399d3 commit 076636c
Copy full SHA for 076636c

File tree

Expand file treeCollapse file tree

4 files changed

+106
-44
lines changed
Open diff view settings
Filter options
Expand file treeCollapse file tree

4 files changed

+106
-44
lines changed
Open diff view settings
Collapse file

‎setup.rst‎

Copy file name to clipboardExpand all lines: setup.rst
+2Lines changed: 2 additions & 0 deletions
  • Display the source diff
  • Display the rich diff
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
Collapse file

‎setup/_update_dep_errors.rst.inc‎

Copy file name to clipboardExpand all lines: setup/_update_dep_errors.rst.inc
+6-5Lines 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
Collapse file

‎setup/upgrade_major.rst‎

Copy file name to clipboardExpand all lines: setup/upgrade_major.rst
+40-20Lines changed: 40 additions & 20 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. index::
22
single: Upgrading; Major Version
33

4-
Upgrading a Major Version (e.g. 3.4.0 to 4.1.0)
4+
Upgrading a Major Version (e.g. 4.4.0 to 5.0.0)
55
===============================================
66

77
Every two years, Symfony releases a new major version release (the first number
@@ -30,12 +30,14 @@ backwards incompatible changes. To accomplish this, the "old" (e.g. functions,
3030
classes, etc) code still works, but is marked as *deprecated*, indicating that
3131
it will be removed/changed in the future and that you should stop using it.
3232

33-
When the major version is released (e.g. 4.1.0), all deprecated features and
33+
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-
3.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:
@@ -124,24 +126,50 @@ done!
124126
-----------------------------------------------
125127

126128
Once your code is deprecation free, you can update the Symfony library via
127-
Composer by modifying your ``composer.json`` file:
129+
Composer by modifying your ``composer.json`` file and changing all the libraries
130+
starting with ``symfony/`` to the new major version:
128131

129-
.. code-block:: json
132+
.. code-block:: diff
130133
131134
{
132135
"...": "...",
133136
134137
"require": {
135-
"symfony/symfony": "^4.1",
138+
- "symfony/cache": "4.4.*",
139+
+ "symfony/cache": "5.0.*",
140+
- "symfony/config": "4.4.*",
141+
+ "symfony/config": "5.0.*",
142+
- "symfony/console": "4.4.*",
143+
+ "symfony/console": "5.0.*",
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",
136151
},
137-
"...": "..."
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+
}
138166
}
139167

140168
Next, use Composer to download new versions of the libraries:
141169

142170
.. code-block:: terminal
143171
144-
$ composer update symfony/symfony
172+
$ composer update symfony/*
145173
146174
.. include:: /setup/_update_dep_errors.rst.inc
147175

@@ -152,14 +180,6 @@ Next, use Composer to download new versions of the libraries:
152180
3) Update your Code to Work with the New Version
153181
------------------------------------------------
154182

155-
The next major version *may* also contain new BC breaks as a BC layer is not always
156-
a possibility. Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major
157-
version) included in the Symfony repository for any BC break that you need to be aware
158-
of.
159-
160-
4) Updating to the Symfony 4 Flex Directory Structure
161-
-----------------------------------------------------
162-
163-
When upgrading to Symfony 4, you will probably also want to upgrade to the new
164-
Symfony 4 directory structure so that you can take advantage of Symfony Flex.
165-
This takes some work, but is optional. For details, see :doc:`/setup/flex`.
183+
In some rare situations, the next major version *may* contain backwards-compatibility
184+
breaks. Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major version)
185+
included in the Symfony repository for any BC break that you need to be aware of.
Collapse file

‎setup/upgrade_minor.rst‎

Copy file name to clipboardExpand all lines: setup/upgrade_minor.rst
+58-19Lines changed: 58 additions & 19 deletions
  • Display the source diff
  • Display the rich diff
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.3.*`` to upgrade to Symfony 4.3:
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.3.*"
59+
"...": "...",
60+
- "require": "4.3.*"
61+
+ "require": "4.4.*"
5662
}
5763
}
5864

@@ -76,12 +82,45 @@ 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+
updating 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+
Starting in ``symfony/flex`` version 1.6, several commands are available to help
103+
upgrade your recipes:
104+
105+
.. code-block:: terminal
106+
107+
# see a list of all installed recipes and which have updates available
108+
$ composer recipes
109+
110+
# see detailed information about a specific recipes
111+
$ composer recipes symfony/framework-bundle
112+
113+
# update a specific recipes
114+
$ composer recipes:install symfony/framework-bundle --force -v
115+
116+
The tricky part of this process is that the recipe "update" does not perform
117+
any intelligent "upgrading" of your code. Instead, **the updates process re-installs
118+
the latest version of the recipe** which means that **your custom code will be
119+
overridden completely**. After updating a recipe, you need to carefully choose
120+
which changes you want, and undo the rest.
121+
122+
For a detailed example, see the `SymfonyCasts Symfony 5 Upgrade Tutorial`_.
123+
86124
.. _`Symfony Repository`: https://github.com/symfony/symfony
87-
.. _`UPGRADE-4.1.md`: https://github.com/symfony/symfony/blob/4.1/UPGRADE-4.1.md
125+
.. _`UPGRADE-4.4.md`: https://github.com/symfony/symfony/blob/4.4/UPGRADE-4.4.md
126+
.. _`SymfonyCasts Symfony 5 Upgrade Tutorial`: https://symfonycasts.com/screencast/symfony5-upgrade

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.