magento-module-dev git:20260309.786511cA

Immutable. This exact content is served forever at /api/v1/blob/84532207ae36fd8f.

---
name: magento-module-dev
description: Create Magento 2 custom modules — registration, directory structure, models, resource models, collections, declarative schema, and data/schema patches. Use when building new modules or understanding module architecture.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# Magento 2 Module Development

## Before writing code

**Fetch live docs**:
1. Fetch `https://developer.adobe.com/commerce/php/development/build/component-file-structure/` for module structure
2. Fetch `https://developer.adobe.com/commerce/php/development/` for development overview
3. Web-search `site:developer.adobe.com commerce php development build` for build guides

## Module Directory Structure

```
app/code/VendorName/ModuleName/
├── Api/                    # Service contract interfaces
│   └── Data/               # Data interfaces
├── Block/                  # View blocks
├── Console/                # CLI commands
├── Controller/             # Controllers
│   └── Adminhtml/          # Admin controllers
├── Cron/                   # Cron job classes
├── etc/                    # Configuration XML
│   ├── adminhtml/          # Admin-area configs
│   ├── frontend/           # Frontend configs
│   ├── module.xml          # Module declaration
│   ├── di.xml              # Dependency injection
│   ├── db_schema.xml       # Declarative schema
│   └── db_schema_whitelist.json
├── Helper/                 # Utility classes
├── Model/                  # Models
│   └── ResourceModel/      # Resource models + collections
├── Observer/               # Event observers
├── Plugin/                 # Interceptor classes
├── Setup/
│   └── Patch/
│       ├── Data/           # Data patches
│       └── Schema/         # Schema patches
├── Test/                   # Tests
├── ViewModel/              # MVVM view models
├── view/                   # Templates, layouts, JS, CSS
├── registration.php        # Module registration
└── composer.json           # Composer definition
```

## Essential Files

### registration.php
Registers the module with Magento's component registrar. Uses `ComponentRegistrar::register()` with type `MODULE`.

### etc/module.xml
Declares the module name and sequence dependencies (modules that must load before this one).

### composer.json
Package definition with type `magento2-module`, PSR-4 autoload mapping, and Magento module dependencies.

## Data Layer Pattern

### Model → Resource Model → Collection

- **Model** — extends `AbstractModel`, represents a single entity, `_construct()` initializes resource model
- **Resource Model** — extends `AbstractDb`, handles CRUD against a specific table, `_init()` sets table and primary key
- **Collection** — extends `AbstractCollection`, represents a set of models, `_init()` maps model to resource model

### Declarative Schema (db_schema.xml)

Since Magento 2.3+, database schema is declared in XML rather than install/upgrade scripts. The system computes diffs and applies changes automatically on `setup:upgrade`.

### Data and Schema Patches

- **Schema Patches** — structural changes (add columns, modify indexes)
- **Data Patches** — data migrations (insert default records, transform data)
- Implement `DataPatchInterface` or `SchemaPatchInterface`
- `apply()` method contains the migration logic
- Patches run once and are tracked in `patch_list` table

## CLI Command Pattern

Console commands extend `Symfony\Component\Console\Command\Command`:
- Register in `etc/di.xml` as arguments to `Magento\Framework\Console\CommandListInterface`
- Implement `configure()` for name/description and `execute()` for logic

## Best Practices

- Follow `VendorName_ModuleName` naming convention
- Declare all module dependencies in `module.xml` sequence
- Use declarative schema instead of install/upgrade scripts
- Use data patches for data migrations
- Keep models thin — business logic in service classes
- Always define service contract interfaces in `Api/`

Fetch the component file structure guide for exact directory conventions and required files before creating a module.