@@ -10,8 +10,8 @@ the previous 2.8 version. If your bundle uses any deprecated feature and it's
1010published as a third-party bundle, applications upgrading to Symfony 3 will no
1111longer be able to use it.
1212
13- Allow to Install Symfony 3 Components
14- -------------------------------------
13+ Allowing to Install Symfony 3 Components
14+ ----------------------------------------
1515
1616Most third-party bundles define their Symfony dependencies using the ``~2.N `` or
1717``^2.N `` constraints in the ``composer.json `` file. For example:
@@ -46,12 +46,12 @@ The above example can be updated to work with Symfony 3 as follows:
4646tip ::
4747
4848 Another common version constraint found on third-party bundles is ``>=2.N ``.
49- You should avoid using that constraint because it can wrongly consider as
50- valid some Symfony versions which are in fact incompatible with your bundle.
51- Use instead ``~2.N|~3.0 `` or ``^2.N|~3.0 `` to make your bundle future-proof.
49+ You should avoid using that constraint because it's too generic (it means
50+ that your bundle is compatible with any future Symfony version). Use instead
51+ ``~2.N|~3.0 `` or ``^2.N|~3.0 `` to make your bundle future-proof.
5252
53- Look for Deprecations and Fix Them
54- ----------------------------------
53+ Looking for Deprecations and Fix Them
54+ -------------------------------------
5555
5656Besides allowing to install Symfony 3 packages, your bundle must stop using
5757any feature deprecated in 2.8 version, because they are removed (and you'll get
@@ -104,8 +104,8 @@ of deprecated features:
104104 It analyzes Symfony projects to find deprecations. In addition it solves
105105 automatically some of them thanks to the growing list of supported "fixers".
106106
107- Test your Bundle in Symfony 3
108- -----------------------------
107+ Testing your Bundle in Symfony 3
108+ --------------------------------
109109
110110Now that your bundle has removed all deprecations, it's time to test it for real
111111in a Symfony 3 application. Assuming that you already have a Symfony 3 application,
@@ -158,6 +158,59 @@ following recommended configuration as the starting point of your own configurat
158158
159159script :phpunit
160160
161+
162+ ------------------------------------------------------------------
163+
164+ The real challenge of adding Symfony 3 support for your bundles is when you want
165+ to support both Symfony 2.x and 3.x simultaneously using the same code. There
166+ are some edge cases where you'll need to deal with the API differences.
167+
168+ Before diving into the specifics of the most common edge cases, the general
169+ recommendation is to **not rely on the Symfony Kernel version ** to decide which
170+ code to use::
171+
172+ if (Kernel::VERSION_ID <= 20800) {
173+ // code for Symfony 2.x
174+ } else {
175+ // code for Symfony 3.x
176+ }
177+
178+ Instead of checking the Symfony Kernel version, check the version of the specific
179+ component. For example, the OptionsResolver API changed in its 2.6 version by
180+ adding a ``setDefined() `` method. The recommended check in this case would be::
181+
182+ if (!method_exists('Symfony\Component\OptionsResolver\OptionsResolver', 'setDefined')) {
183+ // code for the old OptionsResolver API
184+ } else {
185+ // code for the new OptionsResolver API
186+ }
187+
188+ Form Name Refactoring
189+ ~~~~~~~~~~~~~~~~~~~~~
190+
191+ .. TODO
192+
193+ - how to check which version to use
194+ - how to update FormType classes
195+ - how to update type service definitions
196+ - how to update FormTypeExtension classes & service definition
197+
198+
199+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
200+
201+ .. TODO
202+
203+ - how to check which version to use
204+ - how to both APIs
205+
206+
207+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
208+
209+ .. TODO
210+
211+ - how to support both APIs ==> Is there a nice way except from (a) doing
212+ it in the DI extension or (b) creating 2 service definition files?
213+
161214`symfony/phpunit-bridge package` :https://github.com/symfony/phpunit-bridge
162215.. _`Official Symfony Guide to Upgrade from 2.x to 3.0` :https://github.com/symfony/symfony/blob/2.8/UPGRADE-3.0.md
163216.. _`SensioLabs DeprecationDetector` :https://github.com/sensiolabs-de/deprecation-detector