Оновлення стороннього пакету для старшої версії Symfony
Дата оновлення перекладу 2023-06-22
Оновлення стороннього пакету для старшої версії Symfony
Symfony 3 була випущена у листопаді 2015 року. Незважаючи на те, що ця версія не містить ніяких нових функцій, вона видаляє всі шари зворотної сумістності, включені у попередній версії 2.8. Якщо ваш пакет використовує будь-яку застарілу функцію і він був опублікований в якості стороннього пакету, додатки, що оновлюються до Symfony 3, більше не зможуть його використовувати.
Дозвіл установки компонентів Symfony 3
Більшість сторонніх пакетів визначають свої залежності Symfony, використовуючи
обмеження ~2.N
або ^2.N
у файлі composer.json
. Наприклад:
1 2 3 4 5 6 7
{
"require": {
"symfony/framework-bundle": "~2.7",
"symfony/finder": "~2.7",
"symfony/validator": "~2.7"
}
}
Ці обмеження запобігають використанню пакетом компонентів Symfony 3, так що стає
неомжливо встановити його у додаток, заснований на Symfony 3. Цю проблему дуже
легко вирішити завдяки гнучкості обмежень залежності Composer. Просто замініть
~2.N
на ~2.N|~3.0
(або ^2.N
на ^2.N|~3.0
).
Вищеописаний приклад можна оновити так, щоб він працював з Symfony 3 наступним чином:
1 2 3 4 5 6 7
{
"require": {
"symfony/framework-bundle": "~2.7|~3.0",
"symfony/finder": "~2.7|~3.0",
"symfony/validator": "~2.7|~3.0"
}
}
Tip
Ще одним обмеженням версій, яке часто буває у сторонніх пакетах, є >=2.N
. Ви
маєте уникати використання цього обмеження, тому що воно занадто загальне (що означає,
що ваш пакет сумісний з будь-якою наступною версією Symfony). Використовуйте замість
цього ~2.N|~3.0
або ^2.N|~3.0
, щоб зміцнити ваш пакет на майбутнє.
Шукайте старіння та виправляйте їх
Крім того, щоб дозволити користувачам використовувати ваш пакет в Symfony 3, ваш пакет має перестати використовувати будь-які функції, застарілі у версії 2.8, тому що у версії 3.0 вони були видалені (ви отримуватимете виключення або PHP-помилки). Найлегшим способом визначити старіння є установка symfony/phpunit-bridge package та наступний запуск набору тестів.
Спочатку встановіть компонент в якості залежності dev
вашого пакету:
1
$ composer require --dev symfony/phpunit-bridge
Потім запустіть ваш набір тестів та шукайте перелік старінь, відображений після звіту про тестування PHPUnit:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
# ця команда доступна після виконання "composer require --dev symfony/phpunit-bridge"
$ ./bin/phpunit
# ... виведення PHPUnit
Сповіщення про старіння, що залишилися (3)
Опція "pattern" у файлі ... застаріла у версії 2.2 і буде видалена у версії 3.0.
Використайте опцію Используйте опцию "path" у визначенні машруту замість цього ...
Функція Twig "form_enctype" застаріла. Замість неї використайте "form_start" у ...
Клас Symfony\Component\Security\Core\SecurityContext застарів у версії 2.6 і буде
видалений у версії 3.0. Використайте ...
Виправте знайдені старіння, запустіть набір тестів знову та повторюйте процес до тих пір, поки не отримаєте звіт без старінь.
Корисні ресурси
Існує декілька ресурсів, які можуть допомогти вам знайти, зрозуміти та виправити використання застарілих функцій:
- Офіційний посібник Symfony з оновлення з версій 2.x до 3.0
- Повний перелік змін, необхідних для оновлення до Symfony 3.0, згрупованих за компонентами.
- SensioLabs DeprecationDetector
- Запускає аналіз статичного коду у порівнянні з початковим кодом вашого проекту, щоб знайти використання застарілих методів, класів та інтерфейсів. Працює для будь-якого PHP-додатку, але містить спеціальні детектори для додатків Symfony, де він також може визначати використання застарілих сервісів.
- Налагоджувач оновлення Symfony
- Аналізує проекти Symfony, щоб знайти старіння. На додаток також автоматично розвʼязує деякі з них завдяки зростаючому списку підтримуваних "налагоджувачів".
Тестування вашого пакету в Symfony 3
Тепер, коли ваш пакет було позбавлено від всіх старінь, прийшов час тестувати його по-справжньому у додатку Symfony 3. Якщо припустити, що у вас вже є додаток Symfony 3, то ви можете протестувати оновлений пакет, без необхідності його установки через Composer.
Якщо ваша операційна система підтримує символьні посилання, просто спрямуйте необхідний каталог-постачальник до вашого локального кореневогу каталогу пакету:
1
$ ln -s /path/to/your/local/bundle/ vendor/you-vendor-name/your-bundle-name
Якщо ваша операційна система не підтримує символьні посилання, вам знадобиться
скопіювати ваш локальний каталог пакету у відповідний каталог всередині vendor/
.
Оновлення конфігурації Travis CI
На додаток до запуску інструментів локально, рекомендовано встановити сервіс Travis CI, щоб виконкувати тести вашого пакету, викоирстовуючи різні конфігурації Symfony. Викоритайте наступну рекомендовану конфігурацію в якості відправної точки вашої власної конфігурації:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
language: php
sudo: false
php:
- 5.3
- 5.6
- 7.0
matrix:
include:
- php: 5.3.3
env: COMPOSER_FLAGS='--prefer-lowest --prefer-stable' SYMFONY_DEPRECATIONS_HELPER=weak
- php: 5.6
env: SYMFONY_VERSION='2.7.*'
- php: 5.6
env: SYMFONY_VERSION='2.8.*'
- php: 5.6
env: SYMFONY_VERSION='3.0.*'
- php: 5.6
env: SYMFONY_VERSION='3.1.*'
- php: 5.6
env: DEPENDENCIES='dev' SYMFONY_VERSION='3.2.*@dev'
before_install:
- composer self-update
- if [ "$DEPENDENCIES" == "dev" ]; then perl -pi -e 's/^}$/,"minimum-stability":"dev"}/' composer.json; fi;
- if [ "$SYMFONY_VERSION" != "" ]; then composer --no-update require symfony/symfony:${SYMFONY_VERSION}; fi;
install: composer update $COMPOSER_FLAGS
script: phpunit
Оновлення вашого коду для підтримки Symfony 2.x і 3.x одночасно
Справжньою складністю додавання підтримки Symfony 3 у ваші пакети є ситуація, коли ви хочете, щоб пакет підтиримував обидві версії Symfony 2.x і 3.x одночасно, використовуючи один код. Є декілька гострих кутів, де вам знадобиться впоратися з відімнностями API.
Перед тим, як заглиблюватися у специфіку найрозповсюдженіших крайніх випадків, загальною рекомендацією є не покладатися на версію Ядра Symfony, щоб вирішити, який код використовувати:
1 2 3 4 5
if (Kernel::VERSION_ID < 20800) {
// код для Symfony 2.x
} else {
// код для Symfony 3.x
}
Замість того, щоб перевіряти версію Ядра Symfony, перевірте версію конкретного
компонента. Наприклад, OptionsResolver API змінився у версії 2.6, шляхом додавання
методу setDefined()
. Рекомендованою перевіркою у цьому випадку буде:
1 2 3 4 5 6 7
use Symfony\Component\OptionsResolver\OptionsResolver;
if (!method_exists(OptionsResolver::class, 'setDefined')) {
// код для старого OptionsResolver API
} else {
// код для нового OptionsResolver API
}
Tip
Існує один випадок, коли ви дійсно можете покластися на константу
Symfony\Component\HttpKernel\Kernel::VERSION_ID
: при спробі визначити версію
компонента symfony/http-kernel
, так як це той компонент, де визначається
константа.