1) Позбавити ваш код старінь

Під час життєвого циклу релізу старшої версії додаються нові функції, а підписи методів та використання публічних API змінюються. Однак, молодші версії не повинні містити ніяких змін зворотної сумісності. Щоб досягти цього, "старий" код (наприклад, функції, класи і т.д.) все ще працюватиме, але буде відмічений як застарілий, що означає, що його буде видалено або змінено у майбутньому, і що вам варто перестати його використовувати.

Коли випускається старша версія (наприклад, 6.0.0), всі застарілі функції та особливості видаляються. Так що, якщо ви оновили ваш код так, щоб він перестав використовувати такі застарілі функції у останній версії перед старшою (наприклад, в 5.4.*), у вас не повинно виникнути проблем з оновленням. Це означає, що ви спочатку повинні оновитися до останньої молодшої версії (наприклад, 5.4), щоб ви могли побачити всі старіння.

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

Врешті-решт, ви захочете перестати використовувати застарілу функціональність. Іноді попередження може сказати вам про те, що саме вам треба змінити.

Але в інших ситуаціях, попередження може бути розмитим: установка десь може змусити глибший клас викликати попередження. У цьому випадку Symfony намагається як можна чіткіше сформулювати повідомлення, але можливо ви захочете глибше дослідити таке попередження.

А іноді попередження може поступати від сторонньої бібліотеки або пакету, які ви використовуєте. Якщо це так, то існує висока вірогідність, що такі старіння вже були оновлені. У такому випадку, оновіть бібліотеку, щоб виправити їх.

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

1

$ composer require --dev symfony/phpunit-bridge

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# ця команда доступна після запуску "composer require --dev symfony/phpunit-bridge"
$ ./bin/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

1
2
3
4
5
6
7
8

<!-- phpunit.xml.dist -->
<phpunit>
    <!-- ... -->

    <php>
        <env name="SYMFONY_DEPRECATIONS_HELPER" value="max[total]=999999"/>
    </php>
</phpunit>

1

$ SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 php ./bin/phpunit

2) Оновити до нової старшої версії через Composer

Коли ваш код буде позбавлено від старінь, ви можете оновити бібліотеку Symfony через Composer, модифікувавши ваш файл composer.json, та змінивши всі бібліотеки, які починаються з symfony/ на нову старшу версію:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
      "...": "...",

      "require": {
-         "symfony/cache": "5.4.*",
+         "symfony/cache": "6.0.*",
-         "symfony/config": "5.4.*",
+         "symfony/config": "6.0.*",
-         "symfony/console": "5.4.*",
+         "symfony/console": "6.0.*",
          "...": "...",

          "...": "Декілька бібліотек, що починаються з symfony/,
                  дотримуються власної схеми версіонування. Вам
                  не потрібно оновлювати ці версії: ви можете оновити
                  їх незалежно, коли захочете",
          "symfony/monolog-bundle": "^3.5",
      },
      "...": "...",
  }

Знизу вашого файлу composer.json, у блоці extra, ви можете знайти налаштування даних длля версії Symfony. Переконайтеся в тому, що оновили і її. Наприклад, змініть її на 6.0.*, щоб оновитися до версії Symfony 6.0:

1
2
3
4
5
6
7

"extra": {
      "symfony": {
          "allow-contrib": false,
-       "require": "5.4.*"
+       "require": "6.0.*"
      }
  }

Далі, використайте Composer, щоб завантажити нові версії бібліотек:

1

$ composer update "symfony/*"

1

$ composer update symfony/symfony --with-dependencies

1

$ composer update

3) Updating Recipes

Over time - and especially when you upgrade to a new version of a library - an updated version of the recipe may be available. These updates are usually minor - e.g. new comments in a configuration file - but it's a good idea to keep your files in sync with the recipes.

Symfony Flex provides several commands to help upgrade your recipes. Be sure to commit any unrelated changes you're working on before starting:

1
2
3
4
5
6
7
8
9
10
11

# choose an outdated recipe to update
$ composer recipes:update

# update a specific recipe
$ composer recipes:update symfony/framework-bundle

# see a list of all installed recipes and which have updates available
$ composer recipes

# see detailed information about a specific recipes
$ composer recipes symfony/framework-bundle

The recipes:update command is smart: it looks at the difference between the recipe when you installed it and the latest version. It then creates a patch and applies it to your app. If there are any conflicts, you can resolve them like a normal git conflict and commit like normal.

3) Оновити ваш код, щоб він працював з новою версією

У деяких рідкісних ситуаціях, наступна старша версія може містити порушення зворотної сумісності. Не забудьте прочитати UPGRADE-X.0.md (де X - це нова старша версія), включений до сховища Symfony, щоб дізнатися про будь-які порушення зворотної сумісності, на які вам варто звернути увагу.

Оновлення до Symfony 6: Додавання нативних типів значень, що повертаються

Symfony 6 буде постачатися з нативними типами значень PHP, що повертаються, (майже) до всіх методів.

В PHP, якщо батько має декларацію типу значення, що повертається, будь-який клас, шо реалізує або перевизначає метод, повинен також мати тип значення, що повертається. Однак, ви можете додати тип значення, що повертається, до того, як його додасть батько. Це означає, що важливо додавати нативні типи значень PHP, що повертаються, до ваших класів до оновлення на Symfony 6.0. Інакше, ви отримаєте помилки несумісних декларацій.

Коли увімкнено режим налагодження (зазвичай у середовищах розробки та тестування), Symfony видаватиме старіння для кожної несуммісної декларації методів. Наприклад, метод UserInterface::getRoles() в Symfony 6 матиме тип значення, що повертається, array. В Symfony 5.4, ви отримаєте повідомлення про старіння, і повинні будете додати декларацію типу значення, що повертається, до вашого методу getRoles().

Щоб допомогти з цим, Symfony надає скрипт, який може додавати ці типи значень, що повертаються, за вас автоматично. Переконайтеся в тому, що ви встановили компонент symfony/error-handler. Після цього, згенеруйте повне відображення класів, викоритовуючи Composer, і виконайте скрипт, щоб виконати перебір та виправити всі несумісні методи:

1
2
3
4
5
6
7

# Переконайтеся, що "exclude-from-classmap" не заповнений у вашому "composer.json". Потім скиньте автозавантажувач:

# "-o" - це важливо! Це змушує Composer знайти всі класи
$ composer dump-autoload -o

# виправте всі старіння несумісних методів
$ ./vendor/bin/patch-type-declarations

Поведінку цього скрипта можна змінити, використовуючи змінну середовища SYMFONY_PATCH_TYPE_DECLARATIONS. Значення цієї змінної середовища url-зашифроване (наприклад, param1=value2&param2=value2), і доступні наступні параметри:

force

Включає виправлення типів значень, що повертаються, значення повинно бути:

• 2, щоб додати всі можливі типи значень, що повертаються (за замовчуванням рекомендовано для додатків);
• 1, щоб додати типи значень, що повертаються, лише до тестів, фінальних, внутрішніх та приватних методів;
• phpdoc, щоб додати лише анотації docblock @return до несумісних методів, або #[\ReturnTypeWillChange], якщо воно викликано PHP-двигуном.

php

Цільова версія PHP - наприклад, 7.1 не генерує типи "object" (які були представлені в 7.2). За замовчуванням це прирівнюється до PHP-версії, що використовується при виконанні скрипту.

deprecations

Встановіть 0, щоб відключити старіння. Інакше, виникне сповіщення про старіння, коли дочірньому класу не вистачатиме типу значення, що повертається, в той час як батьківський клас буде оголошувати анотацію @return (за замовчуванням - 1).

Якщо є якісь конкретні файли, які треба ігнорувати, ви можете встановити змінну середовища SYMFONY_PATCH_TYPE_EXCLUDE як регулярний вираз. Цей регулярний вираз буде співставлений з повним шляхом до класу, і кожний шлях, що співпадає, буде проігноровано (наприклад, SYMFONY_PATCH_TYPE_EXCLUDE="/tests\/Fixtures\//"). Класи у каталозі vendor/ ігноруватимуться завжди.