README

A small framework for cleaning up the database footprint a Magento 2 module leaves behind after it is uninstalled. Disabling or deleting a module's code does not remove what it created — tables, columns, indexes, EAV attributes, configuration, admin ACL rules, patch history, saved grid views, and its setup_module record all remain. This module provides two abstract setup-patch base classes that a consuming module extends to declare what to remove; the removal logic lives here and is shared.

How it works

• Setup\Patch\AbstractModuleDataCleanUp (a DataPatchInterface) — removes data rows, delegating to Setup\Operation\ModuleDataCleaner.
• Setup\Patch\AbstractModuleSchemaCleanUp (a SchemaPatchInterface) — drops schema objects, delegating to Setup\Operation\ModuleSchemaCleaner.

A consuming module creates one patch per removed module, extends the relevant base class, and sets a few protected properties. The patches run once during bin/magento setup:upgrade and are then recorded in patch_list like any other patch. Every operation is guarded by existence checks, so the patches are safe to run even after the target module's code is already gone.

Usage

1. Add a <sequence> dependency on this module so the base classes load first:

   <!-- Acme/Cleanup/etc/module.xml -->
   <module name="Acme_Cleanup">
       <sequence>
           <module name="Magetu_ModuleDataCleanUp"/>
       </sequence>
   </module>

2. Create a data patch per removed module (no constructor needed — it is inherited):

   namespace Acme\Cleanup\Setup\Patch\Data;
   
   use Magetu\ModuleDataCleanUp\Setup\Patch\AbstractModuleDataCleanUp;
   
   class RemoveFooBar extends AbstractModuleDataCleanUp
   {
       protected string $moduleName = 'Foo_Bar';
   
       /** @var string[] */
       protected array $attributeCodes = ['foo_bar_flag'];
   
       /** @var string[] */
       protected array $configSectionGroups = ['foobar/', 'payment/foo_bar/active'];
   }

3. Add a schema patch only when the module owns tables/views or modified core tables:

   namespace Acme\Cleanup\Setup\Patch\Schema;
   
   use Magetu\ModuleDataCleanUp\Setup\Patch\AbstractModuleSchemaCleanUp;
   
   class RemoveFooBar extends AbstractModuleSchemaCleanUp
   {
       /** @var string[] */
       protected array $tableNames = ['foo_bar_item', 'foo_bar'];
   
       /** @var array<string, string[]> */
       protected array $coreTableColumnMappings = ['sales_order' => ['foo_bar_token']];
   }

What the data patch removes

Derived automatically from $moduleName — no extra properties:

Declared via properties:

$attributeCodes removes EAV attributes by hard delete (cascades to all product/customer value rows — irreversible). Only list attributes whose data is genuinely dead; leave anything a surviving feature might still read.

What the schema patch removes

Operation classes (low-level primitives)

• Setup\Operation\ModuleDataCleaner — removeAttributes(), removePatches(), removeConfigs(), removeAclRules(), removeUiBookmarks(), removeRecordInSetupModuleTable().
• Setup\Operation\ModuleSchemaCleaner — removeTables(), removeViews(), removeCoreTableColumns(), removeUnusedCoreTableColumns() (drops a column only when it holds no data), removeCoreTableIndexes(), dropTriggersForTables().

Not handled (decide per removal)

Intentionally out of scope — these are user data, transient, or not derivable from a module name:

• email_template rows (admin-customised templates) — user data; never auto-deleted.
• cron_schedule rows — transient; Magento prunes them.
• url_rewrite, CMS blocks/pages, widget instances, custom EAV entity types / attribute sets — add a dedicated patch only if the removed module actually created them.
• Front-end markup in themes/templates that referenced the module by brand or feature token (CSS classes, Knockout bindings, layout block names, template files) — these live in no DB table; remove them from the theme/templates directly.
• Files under pub/media, pub, or lib that the extension extracted — delete separately.
• Products of a removed custom product type — the type falls back to simple at runtime; reassign or delete those rows as a business decision.
• A reindex may be required afterwards if the cleanup removed EAV attributes, a product type, or other catalog/indexed data (config-only removals do not need one).

Requirements

Built for Adobe Commerce / Magento Open Source 2.4.x and Mage-OS, PHP 8.1 – 8.5.

The unit suite (Test/Unit/) runs on PHPUnit 9.5, 10.5, or 12 — it uses no APIs removed in PHPUnit 10/12. Note PHPUnit 12 itself requires PHP 8.3+.