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

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

Коли випускається старша версія (наприклад, 7.0.0), всі застарілі функції та особливості видаляються. Так що, якщо ви оновили ваш код так, щоб він перестав використовувати такі застарілі функції у останній версії перед старшою (наприклад, в 6.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

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

      "require": {
-         "symfony/config": "6.4.*",
+         "symfony/config": "7.0.*",
-         "symfony/console": "6.4.*",
+         "symfony/console": "7.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": "6.4.*"
+         "require": "7.0.*"
      }
  }

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

1

$ composer update "symfony/*"

Найкращою практикою після оновлення до нової старшої версії є очищення кешу. Замість виконання команди cache:clear (яка не спрацює, якщо додаток не завантажується у консолі після оновлення), краще видалити весь зміст каталогу кешу:

1
2
3
4
5

# виконайте цю команду на Linux та macOS
$ rm -rf var/cache/*

# виконайте цю команду на Windows
C:\> rmdir /s /q var\cache\*

Дата оновлення перекладу 2025-02-24

1

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

1

$ composer update

3) Оновлення рецептів

З часом - і особливо при оновленні до нової версії бібліотеки - може з'явитися оновлена
версія рецепту . Ці оновлення зазвичай незначні - наприклад, нові коментарі у файлі конфігурації - але бажано синхронізувати ваші файли з рецептами.

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

1
2
3
4
5
6
7
8
9
10
11

# обрати застарілий рецепт для оновлення
$ composer recipes:update

# оновити конкретний рецепт
$ composer recipes:update symfony/framework-bundle

# побачити список всіх встановлених рецептів та які оновлення доступні
$ composer recipes

# побачити деталізовану інформацію про конкретні рецепти
$ composer recipes symfony/framework-bundle

Команда recipes:update є розумною: вона дивиться на різницю між
рецептом, коли ви його встановили, і його останньою версією. Потім вона створює патч і застосовує його до вашого додатку. Якщо виникають конфлікти, ви можете вирішити їх як звичайний конфлікт у git і зафіксувати його як звичайний.

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

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

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

Symfony 6 та Symfony 7 додали власні нативні типи повернення 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/ ігноруватимуться завжди.