Edit in GitHubLog an issue

Extension lifecycle

This topic describes a module's lifecycle and how to create classes that execute code when your module is initialized, upgraded, or uninstalled. These executable classes can perform tasks that set up the database, update data, and clean up data.

Note: Theme and language package extensions do not need initialization or uninstallation tasks because they do not install database schemas or update data.

Lifecycle guidelines#

Follow these guidelines when developing your executable classes to have them run during specific lifecycle stages:

  • Put your executable class in the Setup directory inside your module's root directory.
  • Use the specific file and class name for your class's target lifecycle stage.
  • Implement the specific class interface and function for your class's target stage.
  • Follow Magento's versioning policy when changing your module's version.

Schema initialization stages#

The schema initialization stages are the first set of processes that Adobe Commerce and Magento Open Source run when your module is installed, re-installed, or upgraded.

Schema installation#

The application executes the schema installation class during your module's initial install. If the schema_version for your module is found in the setup_module table, the application skips this stage and proceeds to the schema upgrade stage.

Class name:InstallSchema
Interface:InstallSchemaInterface
Method:install()

Example: InstallSchema.php

Copied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace VendorName\ModuleName\Setup;
8
9use Magento\Framework\Setup\InstallSchemaInterface;
10
11class InstallSchema implements InstallSchemaInterface
12{
13 /**
14 * @inheritdoc
15 */
16 public function install(SchemaSetupInterface $setup, ModuleContextInterface $context)
17 {
18 //Install schema logic
19 }
20}

Schema upgrade#

The applicationexecutes your module's schema upgrade class when it detects an earlier installation. The purpose of this class is to update the database structure or apply patches.

Class nameUpgradeSchema
InterfaceUpgradeSchemaInterface
Methodupgrade()

Example: UpgradeSchema.php

Copied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace VendorName\ModuleName\Setup;
8
9use Magento\Framework\Setup\UpgradeSchemaInterface;
10
11class UpgradeSchema implements UpgradeSchemaInterface
12{
13 /**
14 * @inheritdoc
15 */
16 public function upgrade(SchemaSetupInterface $setup, ModuleContextInterface $context)
17 {
18 //Upgrade schema logic
19 }
20}

Recurring schema event#

The applicationexecutes your module's recurring schema event class after every schema installation or upgrade stage. This class makes final modifications to the database schema after it has been installed or updated.

Class nameRecurring
InterfaceInstallSchemaInterface
Methodinstall()

Example: Recurring.php

Copied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace VendorName\ModuleName\Setup;
8
9use Magento\Framework\Setup\InstallSchemaInterface;
10
11class Recurring implements InstallSchemaInterface
12{
13 /**
14 * @inheritdoc
15 */
16 public function install(SchemaSetupInterface $setup, ModuleContextInterface $context)
17 {
18 //Recurring schema event logic
19 }
20}

Data initialization#

The applicationgoes through your module's data initialization stages after the schema initialization processes complete.

Data installation#

The applicationexecutes the data installation class during your module's initial install unless an existing version entry is found in the database. The purpose of this class is to populate the database with initial data.

Class nameInstallData
InterfaceInstallDataInterface
Methodinstall()

Example: InstallData.php

Copied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace VendorName\ModuleName\Setup;
8
9use Magento\Framework\Setup\InstallDataInterface;
10
11class InstallData implements InstallDataInterface
12{
13 /**
14 * {@inheritdoc}
15 */
16 public function install(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
17 {
18 // Data install logic
19 }
20}

Data upgrade#

The applicationexecutes the data upgrade class when it detects an earlier version in the data_version field for the module in the setup_module table. The purpose of this class is to fix corrupted data or populate a new data field after a schema change.

Class nameUpgradeData
InterfaceUpgradeDataInterface
Methodupgrade()

Example: UpgradeData.php

Copied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace VendorName\ModuleName\Setup;
8
9use Magento\Framework\Setup\UpgradeDataInterface;
10
11class UpgradeData implements UpgradeDataInterface
12{
13 /**
14 * @inheritdoc
15 */
16 public function upgrade(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
17 {
18 // Data upgrade logic
19 }
20}

Recurring data event#

The applicationexecutes your module's recurring data event class after every data installation or upgrade stage. This class makes final modifications to the database store after data has been installed or updated.

Class nameRecurringData
InterfaceInstallDataInterface
Methodinstall()

Example: RecurringData.php

Copied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace VendorName\ModuleName\Setup;
8
9use Magento\Framework\Setup\InstallDataInterface;
10
11class RecurringData implements InstallDataInterface
12{
13 /**
14 * @inheritdoc
15 */
16 public function install(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
17 {
18 // Recurring data event logic
19 }
20}

Database interface#

Use the ModuleDataSetupInterface when you need to do database manipulations. If your installation or upgrade logic spans multiple classes, pass this resource on to other classes that need to modify the database.

Example: Customer module's DefaultCustomerGroupsAndAttributes.php

Copied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7class DefaultCustomerGroupsAndAttributes implements DataPatchInterface, PatchVersionInterface
8{
9 /**
10 * @var CustomerSetupFactory
11 */
12 private $customerSetupFactory;
13 /**
14 * @var ModuleDataSetupInterface
15 */
16 private $moduleDataSetup;
17 /**
18 * DefaultCustomerGroupsAndAttributes constructor.
19 * @param CustomerSetupFactory $customerSetupFactory
20 * @param ModuleDataSetupInterface $moduleDataSetup
21 */
22 public function __construct(
23 CustomerSetupFactory $customerSetupFactory,
24 ModuleDataSetupInterface $moduleDataSetup
25 ) {
26 $this->customerSetupFactory = $customerSetupFactory;
27 $this->moduleDataSetup = $moduleDataSetup;
28 }
29 /**
30 * {@inheritdoc}
31 * @SuppressWarnings(PHPMD.ExcessiveMethodLength)
32 */
33 public function apply()
34 {
35 /** @var CustomerSetup $customerSetup */
36 $customerSetup = $this->customerSetupFactory->create(['setup' => $this->moduleDataSetup]);
37 ...
38 $customerSetup->installEntities();
39 $customerSetup->installCustomerForms();
40 $disableAGCAttribute = $customerSetup->getEavConfig()->getAttribute('customer', 'disable_auto_group_change');
41 ...
42 $migrationSetup = $this->moduleDataSetup->createMigrationSetup();
43 $migrationSetup->appendClassAliasReplace(
44 'customer_eav_attribute',
45 'data_model',
46 Migration::ENTITY_TYPE_MODEL,
47 Migration::FIELD_CONTENT_TYPE_PLAIN,
48 ['attribute_id']
49 );
50 $migrationSetup->doUpdateClassAliases();
51 }
52 ...
53}

Module version#

Use the ModuleContextInterface to get the current module version and execute logic based on the version.

Example: User module's UpgradeData.php

Copied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace Magento\User\Setup;
8
9use Magento\Framework\Encryption\Encryptor;
10use Magento\Framework\Setup\ModuleContextInterface;
11use Magento\Framework\Setup\ModuleDataSetupInterface;
12use Magento\Framework\Setup\UpgradeDataInterface;
13
14class UpgradeData implements UpgradeDataInterface
15{
16 /**
17 * @inheritdoc
18 */
19 public function upgrade(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
20 {
21 $setup->startSetup();
22 if (version_compare($context->getVersion(), '2.0.1', '<')) {
23 $this->upgradeHash($setup);
24 }
25 $setup->endSetup();
26 }
27
28 ...
29
30}

Uninstall event#

The applicationexecutes the uninstall event class when your module is uninstalled using the following command:

Copied to your clipboard
bin/magento module:uninstall --remove-data <module_name>

In this phase, your module should remove all traces of its existence in the database by dropping tables, deleting data, or restoring data.

Class nameUninstall
InterfaceUninstallInterface
Methoduninstall()

Example: Uninstall.php

Copied to your clipboard
1<?php
2/**
3 * Copyright © Magento, Inc. All rights reserved.
4 * See COPYING.txt for license details.
5 */
6
7namespace VendorName\ModuleName\Setup;
8
9use Magento\Framework\Setup\UninstallInterface;
10
11class Uninstall implements UninstallInterface
12{
13 /**
14 * @inheritdoc
15 */
16 public function uninstall(SchemaSetupInterface $setup, ModuleContextInterface $context)
17 {
18 //Uninstall logic
19 }
20}

Disabled modules#

A disabled module can still execute its uninstall event. However, module-specific configurations such as its dependency injection and event/observer configurations will not be available and will cause problems.

Avoid this situation by not including dependencies in your uninstall event class

Related Topics:

Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.