Выбор целевой версии Symfony

Самое важное, что вам нужно сделать - решить, на какую версию вы хотите мигрировать - на текущий стабильный релиз, или на долгосрочно поддерживаемую версию (LTS). Основное различие в том, как часто вам нужно будет проводить обновления для использование поддерживаемой версии. В контексте миграции, другие факторы, вроде поддерживаемой PHP-версии или поддержи библиотек/пакетов, которые вы используете, могут также иметь сильное влияние. Использование самого нового стабильного релиза скорее всего предоставит вам больше функций, но также будет требовать более частых обновлений, чтобы гарантировать вам поддержку исправлений багов и патчей безопасности, и вам нужно будет быстрее работать над исправлением устаревших функций, чтобы иметь возможность обновляться.

Для начала, вашему окружению необходима возможность поддерживать минимальные тртебования для обоих приложений. Другими словами, если релизу Symfony, который вы хотите использовать, необходим PHP 7.1, а ваше существующее приложение еще не поддерживает данную версию PHP, вам скорее всего придется обновить ваш наследуемый проект. Используйте команду check:requirements, чтобы проверить, отвечает ли ваш сервер техническим требованиям для запуска приложений Symfony , и сравните их с вашим текущим окружением приложения, чтобы убедиться, что вы можете запускать оба приложения в одной системе. Наличие тестовой системы, максимально приближенной к окружению производства, где вы можете просто установить новый проект Symfony наряду с существующим, и проверить, работает ли он, даст вам еще более надежный результат.

Настройка Composer

Вам также нужно будет следить за конфликтами между зависимостями в обоих приложениях. Это особенно важно, если ваше существующее приложение уже использует компоненты Symfony или библиотеки, часто используемые в приложениях Symfony, вроде Doctrine ORM, Swiftmailer или Twig. Хорошим способом гарантировать совместимость будет использовать одинаковый composer.json для зависимостей обоих проектов.

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

1

require __DIR__.'/vendor/autoload.php';

Удаление глобального состояния из наследуемого приложения

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

Настройка окружения

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

Запуск Symfony в фронт-контроллере

При рассмотрении первичного запуска типичного PHP-приложения, существует два основных подхода. Сегодня большинство фреймфорков предоставляют так называемый фронт-контроллер, который действует точкой входа. Независимо от того, по какому пути URL вашего приложения вы хотите перейти, каждый запрос отправляется этому фронт-контроллеру, который затем определяет, какие части вашего приложения щагружать, например, какой контроллер и действие вызвать. Этот подход также использует Symfony, где public/index.php - это фронт- контроллер. Особенно в более старых приложениях было распространено, чтобы разные пути обрабатывались разными PHP-файлами.

В любом случае, вам нужно создать public/index.php, который запустит ваше приложение Symfony либо скопировав файл из рецепта FrameworkBundle, либо используя Flex и затребовав FrameworkBundle. Вам также скорее всего будет необходимо обновить ваш веб-сервер (например, Apache или nginx), чтобы он всегда использовал этот фронт-контроллер. Вы можете просмотреть конфигурацию веб-сервера, чтобы увидеть примеры того, как это может выглядеть. Например, при использовании Apache вы можете использовать Правила переписывания, чтобы гарантировать, что PHP-файлы игнорируются, а вызывается только index.php:

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

RewriteEngine On

RewriteCond %{REQUEST_URI}::$1 ^(/.+)/(.*)::\2$
RewriteRule ^(.*) - [E=BASE:%1]

RewriteCond %{ENV:REDIRECT_STATUS} ^$
RewriteRule ^index\.php(?:/(.*)|$) %{ENV:BASE}/$1 [R=301,L]

RewriteRule ^index\.php - [L]

RewriteCond %{REQUEST_FILENAME} -f
RewriteCond %{REQUEST_FILENAME} !^.+\.php$
RewriteRule ^ - [L]

RewriteRule ^ %{ENV:BASE}/index.php [L]

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

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

• Фронт-контроллер с наследуемым мостом, который оставляет наследуемое приложение нетронутым и позволяет поэтапно мигрировать его в приложение Symfony.
• Загрузчик наследумого маршрута, где наследуемое приложение интегрируется в Symfony поэтапно, с полностью интегрированным финальным результатом.

Фронт-контроллер с наследуемым мостом

Когда у вас будет работающее приложение 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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

// public/index.php
use App\Kernel;
use App\LegacyBridge;
use Symfony\Component\Dotenv\Dotenv;
use Symfony\Component\ErrorHandler\Debug;
use Symfony\Component\HttpFoundation\Request;

require dirname(__DIR__).'/vendor/autoload.php';

(new Dotenv())->bootEnv(dirname(__DIR__).'/.env');

/*
 * Ядро будет всегда доступно глобально, позволяя вам иметь
 * доступ к нему из вашего существующего приложения, и через него
 * к сервис-контейнеру. Это позволяет представить новые функции в
 * существующем приложении.
 */
global $kernel;

if ($_SERVER['APP_DEBUG']) {
    umask(0000);

    Debug::enable();
}

if ($trustedProxies = $_SERVER['TRUSTED_PROXIES'] ?? $_ENV['TRUSTED_PROXIES'] ?? false) {
    Request::setTrustedProxies(
      explode(',', $trustedProxies),
      Request::HEADER_X_FORWARDED_FOR | Request::HEADER_X_FORWARDED_PORT | Request::HEADER_X_FORWARDED_PROTO
    );
}

if ($trustedHosts = $_SERVER['TRUSTED_HOSTS'] ?? $_ENV['TRUSTED_HOSTS'] ?? false) {
    Request::setTrustedHosts([$trustedHosts]);
}

$kernel = new Kernel($_SERVER['APP_ENV'], (bool) $_SERVER['APP_DEBUG']);
$request = Request::createFromGlobals();
$response = $kernel->handle($request);

/*
 * LegacyBridge позаботится о том, чтобы решить, нужно ли загружать
 * существующее приложение, или отправить ответ Symfony обратно клиенту.
 */
$scriptFile = LegacyBridge::prepareLegacyScript($request, $response, __DIR__);
if ($scriptFile !== null) {
    require $scriptFile;
} else {
    $response->send();
}
$kernel->terminate($request, $response);

Существует 2 основных отклонения от изначального файла:

Строка 18

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

Строки 41 - 50

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

Этот мост наследования отвечает за понимание того, какой файл должен быть загружен для того, чтобы обработать старую логику приложения. Это может быть либо фронт- контроллер, схожий с public/index.php Symfony, или особенный скриптовый файл, основанный на текущем маршруте. Базовый вид этого LegacyBridge может выглядеть как-то так:

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

// src/LegacyBridge.php
namespace App;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class LegacyBridge
{
    public static function prepareLegacyScript(Request $request, Response $response, string $publicDirectory): ?string
    {
        // Если Symfony успешно обработала этот маршрут, вам не нужно ничего делать.
        if (false === $response->isNotFound()) {
            return null;
        }

        // Поймите, как проложить маршрут к необходимому скриптовому файлу
        // из существующего приложения, и возможно (пере)установить
        // некоторые переменные окружения.
        $legacyScriptFilename = ...;

        return $legacyScriptFilename;
    }
}

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

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

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

Загрузчик наследуемого машрута

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

Загрузчик наследуемого маршрута - это пользовательский загрузчик маршрута. Загрузчик наследуемого маршрута имеет функции, схожие с предыдущим LegacyBridge, но также является сервисом, зарегистрированным внутри компонента Маршрутизация 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
31
32
33

// src/Legacy/LegacyRouteLoader.php
namespace App\Legacy;

use Symfony\Component\Config\Loader\Loader;
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;

class LegacyRouteLoader extends Loader
{
    // ...

    public function load($resource, $type = null)
    {
        $collection = new RouteCollection();
        $finder = new Finder();
        $finder->files()->name('*.php');

        /** @var SplFileInfo $legacyScriptFile */
        foreach ($finder->in($this->webDir) as $legacyScriptFile) {
            // Предполагает, что все файлы наследования используют ".php" в качестве расширения
            $filename = basename($legacyScriptFile->getRelativePathname(), '.php');
            $routeName = sprintf('app.legacy.%s', str_replace('/', '__', $filename));

            $collection->add($routeName, new Route($legacyScriptFile->getRelativePathname(), [
                '_controller' => 'App\Controller\LegacyController::loadLegacyScript',
                'requestPath' => '/' . $legacyScriptFile->getRelativePathname(),
                'legacyScript' => $legacyScriptFile->getPathname(),
            ]));
        }

        return $collection;
    }
}

Вам также понадобится зарегистрировать загрузчик в routing.yaml вашего приложения, как описано в документации Пользовательских загрузчиков маршрута. В зависимости от вашей конфигурации, вам также может понадобиться тегировать сервис с помощью routing.loader. После этого вы должны увидеть все наследуемые маршруты в вашей конфигурации маршрутов, например, когда вы вызываете команду debug:router:

1

$ php bin/console debug:router

Для того, чтобы использовать эти маршруты, вам понадобится создать контроллер, который обрабатывает эти маршруты. Вы могли заметить атрибут _controller в предыдущем примере кода, который сообщает Symfony, какой контроллер вызывать, когда она пытается получить доступ к одному из наследуемых маршрутов. Сам контроллер затем может использовать другие атрибуты маршрута (т.е. requestPath и legacyScript), чтобы определить, какой скрипт вызывать, и обернуть вывод в класс ответа:

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

// src/Controller/LegacyController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\StreamedResponse;

class LegacyController
{
    public function loadLegacyScript(string $requestPath, string $legacyScript)
    {
        return new StreamedResponse(
            function () use ($requestPath, $legacyScript) {
                $_SERVER['PHP_SELF'] = $requestPath;
                $_SERVER['SCRIPT_NAME'] = $requestPath;
                $_SERVER['SCRIPT_FILENAME'] = $legacyScript;

                chdir(dirname($legacyScript));

                require $legacyScript;
            }
        );
    }
}

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

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