Инсталляторы

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

• Создание таблиц базы данных
• Создание или обновление определений классов
• Импорт переводов
• Обновление таблиц или определений базы данных после обновления до более новой версии
• ...

Чтобы предоставить бандлам полный контроль над процессом установки, Pimcore определяет базовый интерфейс инсталлятора, который должен быть реализован вашим классом. Методы инсталлятора вызываются командами типа pimcore:bundle:install. Базовый интерфейс можно найти в InstallerInterface, а его реализация представлена в AbstractInstaller, который можно использовать в качестве отправной точки.

Бандл Pimcore должен возвращать экземпляр инсталлятора в методе getInstaller(). Этот метод также может возвращать null, если функционал установки не требуется. В этом случае действия, обычно выполняемые инсталлятором, не будут запускаться командой pimcore:bundle:install.

Рекомендуется определять инсталлятор как сервис и получать его из контейнера внутри класса бандла по требованию. Пример:

services:  
    App\Installer:  
        public: true  

<?php  
  
namespace App;  
  
use Pimcore\Extension\Bundle\AbstractPimcoreBundle;  
  
class App extends AbstractPimcoreBundle  
{  
    public function getInstaller(): Installer  
    {  
        return $this->container->get(Installer::class);  
    }  
}  

Миграции

Типичная задача при развитии бандла — обновление уже существующей структуры данных до более новой версии с сохранением поддержки «чистой» установки. Для управления версионными изменениями Pimcore интегрирует Doctrine Migrations Bundle, который предоставляет мощный фреймворк для миграций. Для получения подробной информации о том, как работать с миграциями, пожалуйста, ознакомьтесь с документацией Doctrine Migrations Bundle.

Специфика Pimcore

Pimcore добавил дополнительную опцию (--prefix=) к командам миграций Doctrine. Это позволяет фильтровать версии миграций для конкретного пространства имен (namespace), что дает возможность контролировать, какие миграции должны быть выполнены. Типичный сценарий использования — запуск только миграций ядра Pimcore или только миграций конкретного бандла.

Чтобы команда выполняла миграции только установленных бандлов Pimcore, рекомендуется наследоваться от Pimcore\Migrations\BundleAwareMigration и реализовывать метод getBundleName. Этот абстрактный класс проверяет, установлен ли бандл, и при необходимости пропускает миграцию.

Примеры команд в консоли

# Запустить миграции только для ядра Pimcore
./bin/console doctrine:migrations:migrate --prefix=Pimcore\\Bundle\\CoreBundle  
  
# Показать список миграций для CMF бандла
./bin/console doctrine:migrations:list --prefix=CustomerManagementFrameworkBundle\\Migrations  
  
# Запустить вообще все миграции
./bin/console doctrine:migrations:migrate   

Пример конфигурации (config.yaml)

doctrine_migrations:  
    migrations_paths:  
        'Pimcore\Bundle\DataHubBundle\Migrations': '@PimcoreDataHubBundle/Migrations'  
        'CustomerManagementFrameworkBundle\Migrations': '@PimcoreCustomerManagementFrameworkBundle/Migrations'  

Инсталлятор c поддержкой SettingsStore

SettingsStoreAwareInstaller добавляет следующий функционал к стандартному AbstractInstaller:

• Управление статусом установки через Settings Store (вместо проверки выполненных миграций).
• Возможность пометить определенные миграции как «выполненные» во время установки.
• Сброс статуса миграций (если они есть) при удалении бандла.

Реализация

Для использования этого инсталлятора наследуйтесь от SettingsStoreAwareInstaller и реализуйте стандартные методы install и uninstall. В конце этих методов вызовите либо родительский метод, либо $this->markInstalled() / $this->markUninstalled(), чтобы корректно обновить статус в SettingsStore.

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

<?php  
  
namespace Pimcore\Bundle\DummyBundle;  
  
use Pimcore\Bundle\DummyBundle\Migrations\Version20210304111225;  
use Pimcore\Extension\Bundle\Installer\SettingsStoreAwareInstaller;  
  
class Installer extends SettingsStoreAwareInstaller  
{  
    public function getLastMigrationVersionClassName(): ?string  
    {  
        // Возвращает полное имя класса последней миграции, которую нужно пометить как выполненную при установке. 
        return Version20210304111225::class;  
    }  
  
    public function install(): void  
    {  
        //Логика установки  
  
        $this->markInstalled();  
        //или parent::install();       
    }  
  
    public function uninstall(): void  
    {  
        //Логика удаления
  
        $this->markUninstalled();  
        //или parent::uninstall();     
    }  
}  

    Pimcore\Bundle\DummyBundle\Installer:  
        public: true  
        arguments:  
            $bundle: "@=service('kernel').getBundle('PimcoreDummyBundle')"  

Процесс установки

Во время установки бандла произойдут следующие действия:

• Выполняются все инструкции метода install.
• Бандл помечается как установленный в SettingsStore.
• Если настроено, указанные миграции помечаются как выполненные (без фактического их выполнения).

Процесс удаления

Во время удаления бандла произойдут следующие действия:

• Выполняются все инструкции метода uninstall.
• Бандл помечается как удаленный в SettingsStore.
• Статус всех миграций бандла сбрасывается (без фактического их выполнения).

Миграции

Работа с миграциями аналогична описанной в разделе "Миграция" выше.

---

Для получения более подробной информации см.

• Миграции
• Миграции в Doctrine
• Пакет миграций Doctrine