Addon hooks are programming code used to perform certain operations with data in the process of executing the events like addon installation, removal, activation, deactivation and rebuild.

Addon Hooks Overview

• init - run on every request to XC
• install - run after the add-on installation
• enable - run after the add-on is enabled (after install, in case of installation)
• disable - run after the add-on is disabled
• remove - run only during deletion of an add-on that cannot be disabled (that has canDisable:false in main.yaml)
• rebuild - run after every rebuild (after install and enable)
• schema-migration - run during an update (when modifying the database structure prior to SQL code generation)
• sql-migration - run during an update (when modifying the database structure after to SQL code generation but prior to using the code)
• upgrade - run during an upgrade (before rebuild)

Addon Hook Format

To store hooks, use separate classes that are DI services.

To subscribe to every hook, add a corresponding tag to the service description:

modules/[Author]/[Name]/config/services/hooks.yaml

[Author]\[Name]\LifetimeHook\Init:
  tags:
    - {name: xcart.lifetime-hook, type: init, method: onInit}

[Author]\[Name]\LifetimeHook\Install:
  tags:
    - {name: xcart.lifetime-hook, type: install, method: onInstall}

[Author]\[Name]\LifetimeHook\Enable:
  tags:
    - {name: xcart.lifetime-hook, type: enable, method: onEnable}

[Author]\[Name]\LifetimeHook\Disable:
  tags:
    - {name: xcart.lifetime-hook, type: disable, method: onDisable}

[Author]\[Name]\LifetimeHook\Rebuild:
  tags:
    - {name: xcart.lifetime-hook, type: rebuild, method: onRebuild}

[Author]\[Name]\LifetimeHook\Upgrade\UpgradeTo5{major}{minor}build{build}:
  tags:
    - {name: xcart.lifetime-hook, type: upgrade, method: onUpgrade, version: 5.{major}.{minor}.{build}}

[Author]\[Name]\LifetimeHook\Upgrade\UpgradeTo5{major}{minor}build{build}\ThematicClassName:
  tags:
    - {name: xcart.lifetime-hook, type: upgrade, method: onUpgrade, version: 5.{major}.{minor}.{build}}

An add-on can have several hook classes, if it is required for a better code readability. For example, upgrade hooks can be moved to a separate class, or every hook can have a separate class.

schema-migration

The method accepts a Doctrine\DBAL\Schema\SchemaDiff object and must return an object of the same type.

This hook is intended to be used when certain changes need to be excluded. For example:

• table removal when the data needs to be migrated to another table;
• column removal when a column needs to be renamed.

Working with the Doctrine\DBAL\Schema\SchemaDiff object allows for more precise targeting of the required schema parts compared to searching through the generated SQL code.

sql-migration

The method accepts an array of SQL query strings and must return the corresponding array.

This hook is intended to be used in conjunction with schema-migration for the restoration of the correct schema and data. For example:

• When migrating data from one table to another (or to multiple tables): the schema-migration hook is used to preserve the data to be transferred, while the sql-migration hook adds SQL queries for data transfer and removal of obsolete tables or columns.
• When renaming a column: the schema-migration hook ensures the column is retained (a drop-and-create operation can be generated instead of a rename), while the sql-migration hook adds the actual SQL query for renaming the column.

Important!!!

Both the SchemaDiff object and the array of SQL queries are shared across the entire upgrade process — meaning they are global for all hooks of these types in all installed modules. Therefore, the null priority value of the tag by default may need to be adjusted in certain cases using priority: -N/+N

The combined result of all schema-migration and sql-migration hooks must ensure that the actual database schema is aligned with the model definitions. In other words, if a table or column has been removed in the model, the corresponding table or column must also be removed from the database.