Symfony 6 что нового

Готовимся к переходу на Symfony 6.4 и Symfony 7.0

Symfony 6.4 и Symfony 7.0 будут выпущены одновременно в конце ноября 2023 года. В этой статье рассказывается об их различиях и о том, как выбрать оптимальную версию для своих проектов.

Symfony 6.4 и Symfony 7.0 будут выпущены одновременно в конце ноября 2023 года. Обе версии будут обладать абсолютно одинаковым набором функций, но будут и некоторые важные отличия. Продолжайте читать, чтобы узнать, как подготовить свои проекты к обновлению до новых версий Symfony.

Мажорная и минорная версии Symfony

Symfony выпускает минорные версии (6.0, 6.1, 6.2 и т.д.) каждые полгода — в конце мая и в конце ноября. Минорные версии содержат множество новых возможностей, но после их выпуска новые возможности не добавляются.

Например, Symfony 6.3 был выпущен в мае 2023 года с большим количеством новых возможностей. Следующие версии патчей (которые выпускаются ежемесячно) будут содержать только исправления ошибок: 6.3.1 содержит те же возможности, что и 6.3.0, и некоторые исправления; 6.3.2 содержит те же возможности, что и 6.3.0 и 6.3.1, и ещё больше исправлений; и т.д.

Устаревания в Symfony

Помимо новых функций и исправления ошибок, в программные проекты вносятся такие изменения, как переименование опции конфигурации, добавление или удаление аргумента метода и т.д. Если Symfony внесёт подобные изменения и выпустит новую версию, то ваши приложения просто перестанут работать после обновления.

Вместо этого Symfony использует другой подход, основанный на использовании устаревшего поведения. При внесении изменений Symfony сохраняет старое поведение (помечая его, как устаревшее) и добавляет поддержку нового поведения. Это заставляет Symfony генерировать сообщение в журнале всякий раз, когда ваше приложение использует устаревшую функцию.

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

• Symfony 6.0 (ноябрь 2021 г.): не имеет устареваний
• Symfony 6.1 (май 2022 г.): имеет некоторые устаревания
• Symfony 6.2 (ноябрь 2022 г.): имеет устаревания версии 6.1 + новые устаревания
• Symfony 6.3 (май 2023 г.): имеет устаревание в версиях 6.1 и 6.2 + новые устаревания
• Symfony 6.4 (ноябрь 2023 г.): имеет устаревания 6.1, 6.2 и 6.3 + новые устаревания
• Symfony 7.0 (ноябрь 2023 г.): не содержит устареваний

Symfony 7.0 = Symfony 6.4 — устаревания. Обе версии имеют абсолютно одинаковые возможности, но в 6.4 включён код, связанный со всеми устареваниями 6.x, а в 7.0 такого кода нет.

Планирование обновления до версий 6.4 и 7.0

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

1. Обновление проекта с текущей версии Symfony до Symfony 6.4
2. Проверьте, какие устаревшие функции используются в вашем приложении
3. Исправьте все устаревшие функции
4. Теперь вы готовы к переходу на Symfony 7.0

Лучшим способом проверки устаревших функций, используемых в приложении, является запуск тестов с помощью тестового пакета Symfony и команды php bin/phpunit . В результатах вы увидите, что устаревшие функции разделены на две группы:

• Direct Непосредственные устаревания: это те устаревания, которые вы можете исправить самостоятельно; они вызваны вашим собственным кодом приложения;
• Inderect Косвенные устаревания: их невозможно исправить быстро; они вызваны пакетами, пакетами и библиотеками в vendor/ , которые используют устаревшие функции; пожалуйста, сообщайте об этих устареваниях в репозитории каждого проекта, чтобы они могли их исправить.

Если в вашем приложении нет тестов, и у вас нет времени на написание хороших тестов, подумайте о том, чтобы добавить smoke-тесты в ваше Symfony-приложение. Их можно написать очень быстро, и они помогут вам сообщать об устареваниях.

Усилия сообщества

Существуют тысячи пакетов Symfony, и ваше приложение, вероятно, будет использовать некоторые из них. Пакеты обычно нуждаются в некоторых обновлениях для подготовки к основным релизам Symfony. Подумайте о том, чтобы помочь волонтёрам, работающим над каждым пакетом, сообщая об устареваниях и помогая их устранить. Давайте сделаем всю экосистему Symfony готовой к выходу Symfony 7.0!

LTS и обычные версии

Помимо устареваний, важным отличием Symfony 6.4 от 7.0 является то, что 6.4 — это версия с долгосрочной поддержкой (LTS), а 7.0 — обычная версия:

• LTS: исправление ошибок в течение 3 лет и исправление ошибок безопасности в течение 4 лет;
• Обычная: исправление ошибок в течение 8 месяцев и исправление ошибок безопасности также в течение 8 месяцев.

Теоретически версия LTS выглядит лучше из-за расширенной поддержки. Однако на практике необходимо учитывать и следующее:

• Если вы решили остаться на Symfony 6.4 LTS: вы будете получать исправления ошибок до ноября 2026 года и исправления безопасности до ноября 2027 года; однако вы не получите никаких новых возможностей Symfony в течение двух лет, до перехода на следующую версию LTS (7.4) в ноябре 2025 года.
• Если вы решите перейти на Symfony 7.0: вы будете получать исправления ошибок/безопасности только до июля 2024 года, но сможете без особых усилий перейти на версии 7.1 (май 2024 года), 7.2 (ноябрь 2024 года), 7.3 (май 2025 года) и 7.4 (ноябрь 2025 года), что позволит вам получить все новые возможности Symfony и постоянную поддержку ошибок/безопасности. Кроме того, при переходе от одной минорной версии к другой можно регулярно исправлять недоработки, вместо того чтобы исправлять все недоработки сразу при переходе к следующей мажорной версии.

Официальная рекомендация Symfony — по возможности использовать обычные версии.

Symfony: Обновление основной версии (c 5.4.0 до 6.0.0)

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

Что бы обновиться до основной версии нужно выполнить несколько шагов:

1. Избавится от устаревшего кода;
2. Обновится до новой основной версии через Composer;
3. Обновить ваш код для работы с новой версией.

1. Избавится от устаревшего кода

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

Когда выпускается старшая основная/мажорная версия (например, 6.0.0), весь устаревший функционал удаляется. Итак, если вы обновили свой код и прекратили использовать устаревший функционал в последних версиях (например, 5.4.*), вы сможете обновиться без проблем. Это значит, что вы должны обновиться до последней минорной версии (например, 5.4.0), что бы увидеть весь устаревший код.

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

В конечном итоге ваша цель прекратить использовать устаревший функционал. Иногда предупреждение может сказать вам, что именно нужно изменить.

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

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

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

Устаревший код в PHPUnit

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

Всё что вам нужно сделать для установки PHPUnit bridge:

composer require --dev symfony/phpunit-bridge

Теперь вы можете приступить к исправлению уведомлений:

 
$ ./bin/phpunit 
... 
 
OK (10 tests, 20 assertions) 
 
Remaining deprecation notices (6) 
 
The "request" service is deprecated and will be removed in 3.0. Add a type-hint for 
Symfony\Component\HttpFoundation\Request to your controller parameters to retrieve the 
request instead: 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 (успешно), и всё готово!

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

Использование режима Weak Deprecation

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

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

Вы так же можете сделать это с помощью команды:

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

2. Обновится до новой основной версии через Composer

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

  ". ": ". ", 
 "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.*", ". ": ". ", 
 ". ": "A few libraries starting with 
symfony/ follow their own versioning scheme. You 
do not need to update these versions: you can 
upgrade them independently whenever you want", 
"symfony/monolog-bundle": "^3.5", 
>, 
". ": ". ", 
> 

Внизу вашего файла composer.json , в дополнительном блоке, вы можете найти настройки данных для версии Symfony. Обязательно обновите их. Например, обновите, как указано ниже, до версии 6.0.* , что бы перейти на Symfony 6.0:

"extra":  "symfony": "allow-contrib": false, - "require": "4.4.*" + "require": "6.0.*" > 
> 

Затем используйте Composer для загрузки новых версий библиотек:

composer update "symfony/*"

Ошибки зависимости

Если вы получаете сообщения об ошибках зависимости, это может означать, что вам также необходимо обновить другие библиотеки, которые являются зависимостями библиотек Symfony. Чтобы разрешить это, установить флаг —with-all-dependencies :

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

Это обновит symfony/* и все пакеты, от которых зависят эти пакеты. Используя жёсткое ограничение версий в composer.json , вы можете контролировать, до каких версий обновится каждая библиотека.

Если это по-прежнему не работает, в вашем файле composer.json может быть указана версия библиотеки, которая не совместима с более новой версией Symfony. В этом случае обновление этой библиотеки до более новой версии в composer.json может решить эту проблему.

Или у вас могут быть более глубокие проблемы, когда разные библиотеки зависят от конфликтующих версий других библиотек. Проверьте сообщение об ошибке для отладки.

Другая проблема, которая может возникнуть, заключается в том, что зависимости проекта могут быть установлены на вашем локальном компьютере/сервере, но не на удалённом. Обычно это происходит, когда на разных машинах стоят разные версии PHP . Решение состоит в том, чтобы добавить параметр конфигурации платформы в ваш composer.json , что бы определить самую высокую версию PHP, разрешённую для зависимостей (установить версию PHP, которая стоит на сервере).

Обновление других пакетов

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

composer update

Остерегайтесь, если у вас есть некоторые неопределённые ограничения версий в вашем composer.json (например, dev-master ), это может привести к обновлению некоторых не Symfony библиотек до новых версий, которые содержат изменения нарушающие обратную совместимость.

3. Обновление рецептов

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

Symfony Flex предоставляет несколько команд, которые помогут обновить ваши рецепты. Обязательно закоммитьте все несвязанные изменения, над которыми вы работаете перед тем как начать.

Команды recipes были введены в Symfony Flex 1.6

# посмотреть список всех установленных рецептов и каким требуются обновления 
$ composer recipes 
 
# посмотреть детальную информацию о специфических рецептах 
$ composer recipes symfony/framework-bundle 
 
# обновить специфические рецепты 
$ composer recipes:install symfony/framework-bundle --force -v

Сложность этого процесса заключается в том, что рецепт update не выполняет никакого интеллектуального «обновления» кода. Вместо этого процесс обновления переустанавливает последнюю версию рецепта, что означает, что ваш пользовательский код будет полностью переопределён. После обновления рецепта, вам нужно тщательно выбрать, какие обновления вы хотите внести, и отменить остальные.

4. Обновить ваш код для работы с новой версией

В некоторых, редких случая следующая основная/мажорная версия может содержать нарушения обратной совместимости. Убедитесь, что вы прочитали 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 dump-autoload -o и запустите скрипт для перебора карты классов и исправления любого несовместимого метода ./vendor/bin/patch-type-declarations :

# Make sure "exclude-from-classmap" is not filled in your "composer.json". Then dump the autoloader: 
 
# "-o" is important! This forces Composer to find all classes 
$ composer dump-autoload -o 
 
# patch all incompatible method declarations 
$ ./vendor/bin/patch-type-declarations

Эта возможность не ограничивается пакетами Symfony. Она также поможет вам добавить типы и подготовится к другим зависимостям в вашем проекте.

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

force — включает исправление возвращаемых типов, значение должно быть одним из:

• 2 для добавления всех возможных возвращаемых типов (включено по умолчанию, рекомендуется для приложений);
• 1 добавляет возвращаемые типы только в tests , final или private методы;
• phpdoc добавляет только к аннотации @return к несовместимым методам, или #[\ReturnTypeWillChange] если он запускается движком php

php — Используемая версия PHP, например 7.1 не генерирует «объектные» типы (которые были введены в php 7.2). По умолчанию используется версия php, используемая при запуске скрипта.

deprecations — Установите 0 для отключения уведомлений об использовании устаревших функций. В противном случае выдаёт сообщение об устаревшем коде когда в дочернем классе пропущен возвращаемый тип, в то время, когда в родительском классе объявлен через аннотацию @return (значение по умолчанию — 1 ).

Если есть определённые файлы, которые нужно игнорировать, вы можете указать их через переменную окружения SYMFONY_PATCH_TYPE_EXCLUDE как регулярное выражение. Это регулярное выражение должно соответствовать полному пути к классу и каждое совпадение будет проигнорировано (например, SYMFONY_PATCH_TYPE_EXCLUDE=»/tests\/Fixtures\//» ). Классы в каталоге vendor/ всегда игнорируются.

Скрипт не заботится о стиле кодирования. Запустите средство исправления стиля кода, или PHP CS Fixer с правилами phpdoc_trim_consecutive_blank_line_separation , no_superfluous_phpdoc_tags и ordered_imports rules , после исправления типов.

Исправление типов для разработчиков ПО с открытым исходным кодом

При добавлении возвращаемых типов в бандлы и пакеты с открытым исходным кодом нужно быть более осторожным, поскольку добавление возвращаемого типа вынуждает пользователей расширяющих класс, так же добавлять возвращаемый тип. Рекомендуемый подход — использовать двухэтапный процесс.

Во-первых, создайте минорный релиз (т.е. без нарушения обратной совместимости), добавьте типы, которые можно безопасно ввести и добавьте аннотацию @return в PHPDOC ко всем другим методам:

# Add type declarations to all internal, final, tests and private methods. 
# Update the "php" parameter to match your minimum required PHP version 
$ SYMFONY_DEPRECATIONS_HELPER="force=1&php=7.4" ./vendor/bin/patch-type-declarations 
 
# Add PHPDoc to the leftover public and protected methods 
$ SYMFONY_DEPRECATIONS_HELPER="force=phpdoc&php=7.4" ./vendor/bin/patch-type-declarations

# Update the "php" parameter to match your minimum required PHP version 
SYMFONY_DEPRECATIONS_HELPER="force=2&php=7.4" ./vendor/bin/patch-type-declarations

Теперь вы можете безопасно разрешить ^6.0 для зависимостей Symfony.

Подготовка ваших приложений и пакетов для Symfony 6

Согласно Symfony Release Process, каждые два года Symfony выпускает последнюю версию ветки (X.4) и первую версию следующей ветки (Y.0) одновременно. Это произойдет в конце Ноября 2021 года, когда будут выпущены и Symfony 5.4, и Symfony 6.0.

Основное различие между ними заключается в том, что Symfony 5.4 по-прежнему будет содержать все устаревшие функции, и вы можете использовать его в приложениях, использующих эти устаревшие функции. В Symfony 6.0 будут удалены все устаревшие функции. Сначала вам нужно будет перейти на версию 5.4, удалить все устаревшие версии кода, а затем выполнить обновление до версии 6.0.

Представляем типы PHP повсюду

На этот раз и Symfony 5.4, и 6.0 будут включать другое изменение, которое может иметь большое влияние на ваши приложения: добавлены типы PHP во все свойства, аргументы и возвращаемые значения методов, когда это возможно.

Это была титаническая многолетняя работа под руководством Николаса Грекаса и Александра М. Турека, которая могла быть завершена к Symfony 5.4 и 6.0.

Ниже приводится реальный пример влияния этого изменения на ваши приложения. Если у вас есть пользовательский класс, реализующий UserInterface от Symfony, ваш код, вероятно, будет включать следующее:

// src/Entity/User.php namespace App\Entity; use Symfony\Component\Security\Core\User\UserInterface; class User implements UserInterface < // . public function getRoles() < // . >>

Начиная с Symfony 5.4/6.0 это не правильно. Причина в том, что в Symfony добавили возвращаемый тип массива в метод getRoles() . Из-за того, как типы работают в PHP, это означает, что вы обязательно должны добавить возвращаемый тип в свой код:

public function getRoles(): array < // . >

Добавление типов PHP в ваш собственный код

Добавление всех необходимых типов PHP в ваши приложения может оказаться трудоемкой и обременительной задачей. Чтобы упростить задачу, Symfony предоставит несколько инструментов:

• При обновлении до Symfony 5.4 вы будете видеть сообщения об устаревании всякий раз, когда отсутствующий тип в вашем коде вызовет ошибку PHP при обновлении;
• Компонент ErrorHandler включает небольшую командную утилиту, называемую patch-type-declrations , которая автоматически добавляет требуемые типы возврата в ваш код;
• Для сторонних пакетов/бандлов с открытым исходным кодом процесс обновления аналогичен, но вам необходимо выполнить некоторые дополнительные действия, чтобы избежать сбоев обратной совместимости.

Обновление старшей версии (например, с 5.4.0 до 6.0.0)

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

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

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

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

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

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

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

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

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

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

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

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

Устаревания в PHPUnit

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

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

$ 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

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

Вы скорее всего увидите много устареваний касательно несовместимости нативных типов возврата. См. Добавление нативных типов возвращаемых значений , чтобы получить руководство по исправлению таких устареваний.

Исползование слабого режима устареваний

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

1 2 3 4 5 6 7 8

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

Вы также можете выполнить такую команду:

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

2) Обновить до новой старшей версии через Composer

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

• «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, чтобы скачать новые версии библиотек:

$ composer update "symfony/*"

Ошибки зависимостей

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

$ composer update symfony/symfony --with-dependencies

Это обновляет symfony/symfony и все пакеты, от которых он завсит, которые будут включать всебя несколько других пакетов. Используя облегчённую версию ограничений в composer.json , вы можете контролировать, до каких версий будет обновлена каждая из ваших библиотек.

Если и это не сработает, ваш файл composer.json может указывать версию для билиотеки, котора не совместима с более новыми версиями Symfony. В таком случае, обновление библиотеки до более новой версии в composer.json может решить проблему.

Или, у вас могут быть более глубокие проблемы, когда разные библиотеки зависят от конфликтующих версий других библиотек. Проверьте ваши сообщения ошибок для отладки.

Обновление других пакетов

Вы можете также захотеть обновить и остальные ваши библиотеки. Если вы хорошо справились с вашими version constraints в composer.json , вы можете без опаски сделать это, выполнив:

$ composer update

Будьте осторожны, если у вас есь какие-то общие ограничения версий в вашем composer.json (например, dev-master ), это может обновить некоторые библиотеки не из Symfony до более новых версий, которые содержат существенные изменения обратной совместимости.

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:

The recipes:update command was introduced in Symfony Flex 1.18.

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. Она также поможет вам добавлять типы и готовиться к другим зависимостям в вашем проекте.

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

Включает исправление типов возвращаемых значений, значение должно быть:

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

Если есть какие-то конкретные файлы, которые нужно игнорировать, вы можете установить переменную окружения SYMFONY_PATCH_TYPE_EXCLUDE как регулярное выражение. Это регулярное выражение будет сопоставлено с полным путем к классу, и каждый совпадающий путь будет проигнорирован (например, SYMFONY_PATCH_TYPE_EXCLUDE=»/tests\/Fixtures\//» ). Классы в каталоге vendor/ всегда будут игнорироваться.

Скрипту неважен стиль кода. Запустите свой исправитель стиля кода, или PHP CS Fixer с правилами phpdoc_trim_consecutive_blank_line_separation , no_superfluous_phpdoc_tags и ordered_imports , после исправления типов.

Исправление типов для эксплуатационного персонала открытого кода

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

Во-первых, создайте младший релиз (т.е. без нарушений обратной совместимости), где вы добавите типы, которые могут быть представлены безопасно, и добавите PHPDoc @return ко всем другим методам:

1 2 3 4 5 6

# Добавить декларации типов ко всем внутренним, финальным, тестовым и приватным методам. # Обновить параметр "php", чтобы он соответствовал вашей минимально требуемой версии PHP $ SYMFONY_DEPRECATIONS_HELPER="force=1&php=7.4" ./vendor/bin/patch-type-declarations # Добавить PHPDoc к оставшимся публичным и защищенным методам $ SYMFONY_DEPRECATIONS_HELPER="force=phpdoc&php=7.4" ./vendor/bin/patch-type-declarations

# Обновить параметр "php", чтобы он соответствовал вашей минимально требуемой версии PHP $ SYMFONY_DEPRECATIONS_HELPER="force=2&php=7.4" ./vendor/bin/patch-type-declarations