Develop data and schema patches
A data patch is a class that contains data modification instructions. It is defined in a <Vendor>/<Module_Name>/Setup/Patch/Data/<Patch_Name>.php file and implements \Magento\Setup\Model\Patch\DataPatchInterface.
A schema patch contains custom schema modification instructions. These modifications can be complex. It is defined in a <Vendor>/<Module_Name>/Setup/Patch/Schema/<Patch_Name>.php file and implements \Magento\Setup\Model\Patch\SchemaPatchInterface.
Optionally, if you plan to enable rollback for your patch during module uninstallation, then you must implement \Magento\Setup\Model\Patch\PatchRevertableInterface.
The declarative schema approach removes the version from the setup_module table (in a backward compatible way), leaving only the Composer version. Therefore, you can create all new patches and modules without specifying a setup_module version.
The sequnce of installing patches is handled through a dependency-based approach. Patches can either be independent or dependent on other patches. Independent patches can be installed in any sequence. A dependent patch requires a minimal number of patches so that it can be installed successfully.
To define a dependency in a patch, make a static reference to the patch class. The class can be in any module.
return [
\SomeVendor\SomeModule\Setup\Patch\Data\SomePatch::class
];
The following code sample defines a data patch class that has a dependency.
<?php
/**
* Copyright © Magento, Inc. All rights reserved.
* See COPYING.txt for license details.
*/
namespace Magento\DummyModule\Setup\Patch\Data;
use Magento\Setup\Model\Patch\DataPatchInterface;
use Magento\Setup\Model\Patch\PatchRevertableInterface;
/**
*/
class DummyPatch
implements DataPatchInterface,
PatchRevertableInterface
{
/**
* @var \Magento\Framework\Setup\ModuleDataSetupInterface
*/
private $moduleDataSetup;
/**
* @param \Magento\Framework\Setup\ModuleDataSetupInterface $moduleDataSetup
*/
public function __construct(
\Magento\Framework\Setup\ModuleDataSetupInterface $moduleDataSetup
) {
/**
* If before, we pass $setup as argument in install/upgrade function, from now we start
* inject it with DI. If you want to use setup, you can inject it, with the same way as here
*/
$this->moduleDataSetup = $moduleDataSetup;
}
/**
* {@inheritdoc}
*/
public function apply()
{
$this->moduleDataSetup->getConnection()->startSetup();
//The code that you want apply in the patch
//Please note, that one patch is responsible only for one setup version
//So one UpgradeData can consist of few data patches
$this->moduleDataSetup->getConnection()->endSetup();
}
/**
* {@inheritdoc}
*/
public static function getDependencies()
{
/**
* This is dependency to another patch. Dependency should be applied first
* One patch can have few dependencies
* Patches do not have versions, so if in old approach with Install/Ugrade data scripts you used
* versions, right now you need to point from patch with higher version to patch with lower version
* But please, note, that some of your patches can be independent and can be installed in any sequence
* So use dependencies only if this important for you
*/
return [
SomeDependency::class
];
}
public function revert()
{
$this->moduleDataSetup->getConnection()->startSetup();
//Here should go code that will revert all operations from `apply` method
//Please note, that some operations, like removing data from column, that is in role of foreign key reference
//is dangerous, because it can trigger ON DELETE statement
$this->moduleDataSetup->getConnection()->endSetup();
}
/**
* {@inheritdoc}
*/
public function getAliases()
{
/**
* This internal Magento method, that means that some patches with time can change their names,
* but changing name should not affect installation process, thats why if we will change name of the patch
* we will add alias here
*/
return [];
}
}Will old scripts work in newer versions?
Old scripts will work with new versions of Magento. However, if you want to convert your old scripts to the new format,
implement \Magento\Setup\Model\Patch\PatchVersionInterface. This interface allows you to specify the setup version of the module in your database. If the version of the module is higher than the version specified in your patch, then the patch is skipped. If the version in the database is equal or lower, then the patch installs.