Обновление полноценной версии (например, с 2.7.0 до 3.0.0)

Обновление полноценной версии (например, с 2.7.0 до 3.0.0)

Каждые два года Symfony выпускает новую полноценную версию (меняется первая цифра). Эти релизы самые сложные в обновлении, так как им разрешено нарушать обратную совместимость. Однако, Symfony делает так, чтобы процесс обновления прошёл как можно более гладко.

Это означает, что вы можете обновить большую часть вашего кода до того, как полноценная версия на самом деле будет выпущена. Это называется делать ваш код совместимым с будущим.

В обновлении полноценной версии существует несколько шагов:

  1. Избавить ваш код от возражений;
  2. Обновить до новой полноценной версии через Composer;
  3. Обновить ваш код, чтобы он работал с новой версией.

1) Избавить ваш код от возражений

Во время жизненного релиза полноценного релиза, добавляются новые функции, а подписи методов и использование публичных API изменяются. Однако, упрощённые версии не должны содержать никаких изменений обратной совместимости. Чтобы добиться этого, "старый" код (например, функции, классы и т.д.) всё ещё будет работать, но будет помечен как осуждённый, обозначая, что он будет удалён или изменён в будущем, и что вам стоит перестать его использовать.

Когда выпускается полноценная версия (например, 3.0.0), все осуждённые функции и особенности удаляются. Так что, если вы обновили ваш код так, чтобы он перестал использовать такие функции в последней версии перед полноценной (например, в 2.8.*), у вас не должно возникнуть проблем с обновлением.

Чтобы помочь вам в этом, пометки возражения запускаются каждый раз, когда вы используете осуждённую функцю. Когда вы посещаете ваше приложение в окружении разработки вашего браузера, эти пометки отображаются в панели инструментов веб-разработки:

../_images/deprecations-in-profiler.png

В конце-концов, вы захотите перестать использовать осуждённую функциональность. Иногда это просто: предупреждение может сказать вам о том, что именно нужно изменить.

Но в других ситуациях предупреждение может быть туманным: установка где-то может вызвать более глубокий класс вызвать предупреждение. В этом случае Symfony старается как можно чётче сформулировать сообщение, но возможно вы захотите глубже исследовать такое предупреждение.

А иногда предупреждение может поступать от сторонней библиотеки или пакета, которые вы используете. Если это так, то существует высокая вероятность, что такие возражения уже были обновлены. В таком случае, обновите библиотеку, чтобы исправить их.

Как только исчезнут все предупреждения о возражениях, вы можете обновляться с наибольшей уверенностью.

Возражения в PHPUnit

Когда вы выполняете ваши тесты, используя PHPUnit, сообщения о возражениях не отображаются. Чтобы помочь вам в этом, Symfony предоставляет мост PHPUnit. Этот мост покажет вам удобное резюме всех сообщений о возражениях в конце тестовго отчёта.

Всё, что вам нужно - это установить мост PHPUnit:

1
$ composer require --dev symfony/phpunit-bridge

Теперь вы можете начать исправлять сообщения:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
$ phpunit
...

OK (10 тестов, 20 утверждений)

Оставшиеся сообщения о возражениях (6)

Сервис "запроса" ("request") вызывает возражение и будет удалён в версии 3.0.
Добавьте типизирование для Symfony\Component\HttpFoundation\Request в параметры
вашего контроллера, чтобы вместо этого вернуть запрос: 6x
    3x in PageAdminTest::testPageShow from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin
    2x in PageAdminTest::testPageList from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin
    1x in PageAdminTest::testPageEdit from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin

Как только вы исправите всё, команда окончится 0 (успех) и вы закончили!

Иногда вам не удастся исправить все возражения (например, что-то вызвало возражение в версии 2.8, а вам всё еще нужна поддержка версии 2.7). В таких случаях, вы всё равно можете использовать мост для исправления как можно наибольшего количества возражений, а потом переключиться в режим слабого тестирования, чтобы заставить ваши тесты снова пройти. Вы можете сделать это, используя переменную SYMFONY_DEPRECATIONS_HELPER:

1
2
3
4
5
6
7
8
<!-- phpunit.xml.dist -->
<phpunit>
    <!-- ... -->

    <php>
        <env name="SYMFONY_DEPRECATIONS_HELPER" value="weak"/>
    </php>
</phpunit>

(Вы также можете выполнить команду так: SYMFONY_DEPRECATIONS_HELPER=weak phpunit).

Tip

Некоторые члены сообщества Symfony разработали инструмент под названием Symfony-Upgrade-Fixer, который автоматически исправляет некоторые из самых распространённых возражений, обнаруженным при обновлении с Symfony 2 до Symfony 3.

2) Обновить до новой полноценной версии через Composer

Когда ваш код будет избавлен от возражений, вы можете обновить библиотеку Symfony через Composer, модифицировав ваш файл composer.json:

1
2
3
4
5
6
7
8
{
    "...": "...",

    "require": {
        "symfony/symfony": "3.0.*",
    },
    "...": "..."
}

Далее, используйте Composer, чтобы скачать новые версии билиотек:

1
$ composer update symfony/symfony

Dependency Errors

If you get a dependency error, it may simply mean that you need to upgrade other Symfony dependencies too. In that case, try the following command:

1
$ composer update symfony/symfony --with-dependencies

This updates symfony/symfony and all packages that it depends on, which will include several other packages. By using tight version constraints in composer.json, you can control what versions each library upgrades to.

If this still doesn't work, your composer.json file may specify a version for a library that is not compatible with the newer Symfony version. In that case, updating that library to a newer version in composer.json may solve the issue.

Or, you may have deeper issues where different libraries depend on conflicting versions of other libraries. Check your error message to debug.

Upgrading other Packages

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:

1
$ composer update

Caution

Beware, if you have some unspecific version constraints in your composer.json (e.g. dev-master), this could upgrade some non-Symfony libraries to new versions that contain backwards-compatibility breaking changes.

3) Обновить ваш код, чтобы он работал с новой версией

Существует неплохой шанс того, что вы уже закончили! Однако, следующая полноценная версия может тоже содержать новые нарушения обратной совместимости, так как уровень обратной совместимости не всегда возможен. Обязательно прочитайте UPGRADE-X.0.md (где X - это новая полноценная версия), включённый в хранилище Symfony, чтобы узнать о любом нарушении обратной совместимости.

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.