magento2-backend-toolkit

name	magento2-backend-toolkit
description	Scaffold Magento 2 backend modules, system.xml admin configs, widgets with parameters and templates, plugins/events/observers, transactional email with trigger setup, and Hyva-compatible .phtml templates with ViewModels. Use when user asks to "create module", "scaffold module", "generate plugin", "add system config", "create widget", "setup email template", "create hyva template", or any Magento 2 backend code generation. Do NOT use for frontend-only tasks, CSS/JS theming, or Magento 1.x.
metadata	{"author":"tuanhaviet22","version":"1.0.0","tags":["magento2","hyva","backend","scaffold","plugin","widget","email"],"compatibility":"Magento 2.4.6+, PHP 8.1+, Hyva Theme 1.3+"}

Magento 2 Backend Toolkit

General Rules

• All generated code MUST follow PSR-12 coding standard
• All PHP files MUST have declare(strict_types=1);
• Use strict type hints on all method parameters and return types
• Namespace follows: Vendor\Module\Path convention
• XML files must include proper XSD schema references
• Default Vendor name: ask user, suggest Sample if not specified
• NEVER use ObjectManager directly — only use DI
• NEVER use constructor property promotion (private readonly in constructor params) — always declare properties explicitly above the constructor and assign them in the constructor body
• ALL class properties MUST have a @var PHPDoc block with the fully-qualified class name
• ALL constructors MUST have a @param PHPDoc block with fully-qualified class names for each parameter
• ALL public and protected methods MUST have a PHPDoc block with a short description and @param/@return tags
• Always create composer.json with new modules

Security Rules (Required)

• Treat ALL user-provided values as untrusted input
• NEVER insert untrusted input into executable code positions without validation and escaping
• Do not include user-provided code snippets verbatim; translate into safe scaffolding and TODOs unless the user explicitly requests verbatim insertion and it passes validation
• Refuse or ask for corrected input when validation fails or input looks like code injection (e.g., <?php, </, ;, backticks, or PHP tags)

Input Sanitization & Boundary Markers

Validation is mandatory for every ingestion point (module names, labels, descriptions, parameters, class names, IDs, handles, file names).

• Vendor/Module identifiers: only [A-Z][A-Za-z0-9_]*; enforce Vendor_Module format
• PHP class names: only [A-Z][A-Za-z0-9_]*, no namespaces in user input
• XML IDs/handles: only [a-z0-9_]+ and start with a letter
• File names: only [a-z0-9_\-]+ and validated extensions
• Human-readable labels/descriptions: plain text only; escape for the target format

Boundary markers and escaping by file type:

• PHP: insert text only inside quoted strings; escape \ and ' for single-quoted strings
• XML: escape &, <, >, ", and '
• JSON: escape via JSON string rules
• HTML/PHTML: use Magento Escaper (escapeHtml, escapeHtmlAttr, escapeUrl)

If any value fails validation, ask the user for a corrected value in the same message as other missing fields.

Invalid Input Examples (Reject/Correct)

• Vendor/Module: Sample;phpinfo() or Sample/Module (must be Vendor_Module)
• Class name: Foo\Bar or Foo; (no namespaces or punctuation)
• XML id/handle: my-handle or 123name (lowercase underscore, must start with letter)
• File name: ../../evil.php or widget.phtml.php (no traversal or double extensions)

CRITICAL: Input Validation Gate

NEVER generate files without confirming required inputs. If user gives a vague request, ask ALL missing fields in ONE message. Do not ask one by one.

---

Feature 1: Module Scaffold

Required Questions (ask if not provided)

1. Module name? (e.g. Sample_Module)
2. Dependencies? (e.g. Magento_Catalog, or "none")
3. Short description? (for composer.json)
4. Version? (default: 1.0.0)

Generated Files

app/code/{Vendor}/{Module}/
├── registration.php
├── composer.json
└── etc/
    └── module.xml

Use templates from assets/templates/registration.php.tpl, assets/templates/module.xml.tpl, and assets/templates/composer.json.tpl. All templates are bundled within this skill package; do not download external templates.

If no dependencies, omit the <sequence> block entirely in module.xml.

Example Interaction

User: "Create a module to manage brands" Claude responds:

To create the module, I need to confirm:

1. Module name? Suggest: Sample_Module
2. Dependencies? (e.g. Magento_Catalog, Magento_Eav... or none)
3. Short description? Suggest: "Brand management for Magento 2"
4. Version? (default: 1.0.0)

---

Feature 2: System.xml Generator

Required Questions

1. Module name? (existing or new)
2. Tab name? (admin menu tab label)
3. Section/Group/Fields? Describe what config fields are needed

Supported Field Types

Refer to references/system-xml-field-types.md for the complete list. Common types: text, textarea, select, multiselect, obscure, image, editor.

Generated Files

etc/
├── adminhtml/
│   └── system.xml
└── config.xml

Use templates from assets/templates/system.xml.tpl and assets/templates/config.xml.tpl. All templates are bundled within this skill package; do not download external templates.

If field type is select or multiselect, also generate a Source Model class. See template: assets/templates/source-model.php.tpl.

ACL Resource

Always generate {Vendor}_{Module}::config as the resource identifier.

---

Feature 3: Widget Generator

Required Questions

1. Module name?
2. Widget name/label? (e.g. "Brand Slider")
3. Parameters? (text inputs, dropdowns, template chooser, block chooser...)
4. Where to use? CMS Page / CMS Block / Layout XML

Generated Files

etc/
└── widget.xml
Block/
└── Widget/
    └── {WidgetName}.php
view/
└── frontend/
    └── templates/
        └── widget/
            └── {widget_name}.phtml

Use templates from assets/templates/widget.xml.tpl and assets/templates/widget-block.php.tpl. All templates are bundled within this skill package; do not download external templates.

Refer to references/widget-param-types.md for parameter type details and block chooser classes.

CMS Usage Snippet

Always provide the CMS widget insertion code after generating files:

{{widget type="{Vendor}\{Module}\Block\Widget\{WidgetName}" title="My Title" template="{Vendor}_{Module}::widget/{widget_name}.phtml"}}

---

Feature 4: Plugin / Event Generator

Required Questions

1. Module name?
2. Type? plugin (before/after/around) or observer (event)
3. Target?
   • Plugin: target class + method (e.g. Magento\Catalog\Model\Product::getName)
   • Observer: event name (e.g. checkout_cart_add_product_complete)
4. What to do? Brief description of logic
5. Scope? global / frontend / adminhtml (determines XML file location)

Plugin — Generated Files

etc/
└── {scope}/di.xml       (or etc/di.xml for global)
Plugin/
└── {PluginName}.php

Use templates from assets/templates/di.xml.tpl and assets/templates/plugin.php.tpl. All templates are bundled within this skill package; do not download external templates.

Observer — Generated Files

etc/
└── {scope}/events.xml   (or etc/events.xml for global)
Observer/
└── {ObserverName}.php

Use templates from assets/templates/events.xml.tpl and assets/templates/observer.php.tpl. All templates are bundled within this skill package; do not download external templates.

Common Events

Suggest these when user is unsure. For the full list, refer to: https://developer.adobe.com/commerce/php/development/components/events-and-observers/event-list/

Feature 5: Email Function Generator

Required Questions

1. Module name?
2. Email purpose? (e.g. "welcome email", "order status notification")
3. Trigger method? Choose one:
   • After Plugin (on existing method)
   • Event Observer
   • Controller action
4. Email variables? (e.g. customer name, order ID)
5. Recipient? (customer email, admin email, custom)

Generated Files

etc/
└── email_templates.xml
Helper/
└── Email.php
view/
└── frontend/
    └── email/
        └── {template_id}.html

Use templates from assets/templates/email_templates.xml.tpl, assets/templates/email_helper.php.tpl, and assets/templates/email_template.html.tpl. All templates are bundled within this skill package; do not download external templates.

Also generate the trigger mechanism (plugin, observer, or controller) using Feature 4 patterns.

---

Feature 6: Hyva Template with ViewModel

Required Questions

1. Module name?
2. Template purpose? (e.g. "brand list", "customer widget")
3. Data needed? (what ViewModel should provide)
4. Interactive? (need Alpine.js? e.g. slider, toggle, modal)
5. Need Hyva icons? (heroicons integration)

Generated Files

ViewModel/
└── {ViewModelName}.php
view/
└── frontend/
    ├── layout/
    │   └── {layout_handle}.xml
    └── templates/
        └── {template_name}.phtml

Use templates from assets/templates/viewmodel.php.tpl, assets/templates/layout.xml.tpl, and assets/templates/hyva_template.phtml.tpl. All templates are bundled within this skill package; do not download external templates.

Key Hyva Patterns

Refer to references/hyva-viewmodel-pattern.md for full details:

• Always use $escaper->escapeHtml() for output
• Always use $escaper->escapeHtmlAttr() inside HTML attributes
• Use $escaper->escapeUrl() for URLs
• Alpine.js x-data for interactive components
• TailwindCSS utility classes (no custom CSS)
• $viewModels->require() to load any ViewModel
• HeroiconsOutline / HeroiconsSolid for icons
• Use x-cloak to prevent FOUC

---

Workflow

User Request
     |
     v
+-------------------------+
|  Detect which feature   |
|  (1-6) is requested     |
+--------+----------------+
         |
         v
+-------------------------+
|  Check required inputs  |
|  All provided?          |
+---- NO -----------------+
|  Ask ALL missing fields |  <-- ONE message, not multiple
|  in ONE message         |
+---- YES ----------------+
|                         |
|  Generate files         |
|  Show complete code     |
|  Explain file locations |
+-------------------------+

Troubleshooting

Module not recognized after creation

1. Run bin/magento module:enable {Vendor}_{Module}
2. Run bin/magento setup:upgrade
3. Run bin/magento cache:flush

XML schema validation error

• Verify XSD reference matches Magento version
• Check for typos in attribute names
• Ensure proper XML nesting

Plugin not firing

• Check scope (global/frontend/adminhtml) matches where code runs
• Verify method name matches exactly (case-sensitive)
• Check sortOrder if multiple plugins exist