hyva-create-module

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Magento 2 Module

创建Magento 2模块

This utility skill creates new Magento 2 modules in

app/code/

. It is designed to be called by other skills that need module scaffolding.

Command execution: For commands that need to run inside the development environment (e.g.,

bin/magento

), use the

hyva-exec-shell-cmd

skill to detect the environment and determine the appropriate command wrapper.

此实用技能可在

app/code/

目录下创建新的Magento 2模块，专为需要模块框架搭建的其他技能调用而设计。

命令执行： 对于需要在开发环境中运行的命令（如

bin/magento

），请使用

hyva-exec-shell-cmd

技能检测环境并确定合适的命令包装器。

Parameters

参数

When invoking this skill, the calling skill should provide:

Parameter	Required	Description
`vendor`	Yes	Vendor name in PascalCase (e.g., `Acme` )
`module`	Yes	Module name in PascalCase (e.g., `CustomFeature` )
`description`	No	Module description for composer.json (default: "[Vendor] [Module] module")
`dependencies`	No	Array of module dependencies for `<sequence>` in module.xml
`composer_require`	No	Object of composer requirements (package: version)

调用此技能时，调用方技能需提供以下参数：

参数	是否必填	描述
`vendor`	是	PascalCase格式的供应商名称（例如： `Acme` ）
`module`	是	PascalCase格式的模块名称（例如： `CustomFeature` ）
`description`	否	用于composer.json的模块描述（默认值："[Vendor] [Module] module"）
`dependencies`	否	用于module.xml中 `<sequence>` 的模块依赖数组
`composer_require`	否	composer依赖项对象（包名: 版本号）

Workflow

工作流程

Step 1: Validate Input

步骤1：验证输入

Verify vendor name is PascalCase (starts with uppercase, alphanumeric only)
Verify module name is PascalCase
Check that
```
app/code/{Vendor}/{Module}
```
does not already exist

验证供应商名称为PascalCase格式（首字母大写，仅包含字母数字）
验证模块名称为PascalCase格式
检查
```
app/code/{Vendor}/{Module}
```
目录是否已存在

Step 2: Create Directory Structure

步骤2：创建目录结构

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

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

Step 3: Generate Files

步骤3：生成文件

registration.php

Use template

assets/templates/registration.php.tpl

Replace
```
{{VENDOR}}
```
with vendor name
Replace
```
{{MODULE}}
```
with module name

使用模板

assets/templates/registration.php.tpl

：

将
```
{{VENDOR}}
```
替换为供应商名称
将
```
{{MODULE}}
```
替换为模块名称

composer.json

Use template

assets/templates/composer.json.tpl

Replace
```
{{VENDOR}}
```
with vendor name (PascalCase)
Replace
```
{{MODULE}}
```
with module name (PascalCase)
Replace
```
{{vendor_kebabcase}}
```
with kebab-case, hyphenated vendor name
Replace
```
{{module_kebabcase}}
```
with kebab-case, hyphenated module name
Replace
```
{{DESCRIPTION}}
```
with description
Add entries from
```
composer_require
```
parameter to the
```
require
```
section

使用模板

assets/templates/composer.json.tpl

：

将
```
{{VENDOR}}
```
替换为PascalCase格式的供应商名称
将
```
{{MODULE}}
```
替换为PascalCase格式的模块名称
将
```
{{vendor_kebabcase}}
```
替换为kebab-case格式的供应商名称（连字符分隔）
将
```
{{module_kebabcase}}
```
替换为kebab-case格式的模块名称（连字符分隔）
将
```
{{DESCRIPTION}}
```
替换为模块描述
将
```
composer_require
```
参数中的条目添加到
```
require
```
部分

module.xml

Use template

assets/templates/module.xml.tpl

Replace
```
{{VENDOR}}
```
with PascalCase vendor name
Replace
```
{{MODULE}}
```
with PascalCase module name
Replace
```
{{SEQUENCE}}
```
with
```
<sequence>
```
block containing dependencies, or empty string if none

使用模板

assets/templates/module.xml.tpl

：

将
```
{{VENDOR}}
```
替换为PascalCase格式的供应商名称
将
```
{{MODULE}}
```
替换为PascalCase格式的模块名称
将
```
{{SEQUENCE}}
```
替换为包含依赖项的
```
<sequence>
```
块，若无依赖则为空字符串

Step 4: Run Setup (Optional)

步骤4：运行安装（可选）

If the calling skill requests it, run

bin/magento setup:upgrade

using the

hyva-exec-shell-cmd

skill for the appropriate wrapper.

若调用方技能要求，使用

hyva-exec-shell-cmd

技能运行

bin/magento setup:upgrade

以适配对应的命令包装器。

Error Handling

错误处理

Abort module creation and report the error to the calling skill when:

Condition	Action
Vendor name not PascalCase	Report: "Invalid vendor name '{name}': must start with uppercase letter and contain only alphanumeric characters"
Module name not PascalCase	Report: "Invalid module name '{name}': must start with uppercase letter and contain only alphanumeric characters"
Directory already exists	Report: "Module already exists at app/code/{Vendor}/{Module}"
Cannot create directory	Report: "Failed to create directory app/code/{Vendor}/{Module}: {error}"
Cannot write file	Report: "Failed to write {filename}: {error}"

hyva-exec-shell-cmd

skill is unavailable when Step 4 is requested, skip the setup:upgrade step and report: "Skipped setup:upgrade - hyva-exec-shell-cmd skill not available. Run manually: bin/magento setup:upgrade"

当出现以下情况时，终止模块创建并向调用方技能报告错误：

条件	操作
供应商名称非PascalCase格式	报告："无效的供应商名称'{name}'：必须以大写字母开头且仅包含字母数字字符"
模块名称非PascalCase格式	报告："无效的模块名称'{name}'：必须以大写字母开头且仅包含字母数字字符"
目录已存在	报告："模块已存在于app/code/{Vendor}/{Module}"
无法创建目录	报告："创建目录app/code/{Vendor}/{Module}失败：{error}"
无法写入文件	报告："写入{filename}失败：{error}"

若步骤4被请求时

hyva-exec-shell-cmd

技能不可用，则跳过setup:upgrade步骤并报告："已跳过setup:upgrade - hyva-exec-shell-cmd技能不可用。请手动运行：bin/magento setup:upgrade"

Template Placeholders

模板占位符

Placeholder	Description	Example
`{{VENDOR}}`	Vendor name (PascalCase)	`Acme`
`{{MODULE}}`	Module name (PascalCase)	`CustomFeature`
`{{vendor_kebabcase}}`	Vendor name (kebab-case, split on capitals)	`acme`
`{{module_kebabcase}}`	Module name (kebab-case, split on capitals)	`custom-feature`
`{{DESCRIPTION}}`	Module description	`Acme CustomFeature module`
`{{SEQUENCE}}`	Module sequence XML or empty	`<sequence><module name="Magento_Catalog"/></sequence>`

占位符	描述	示例
`{{VENDOR}}`	PascalCase格式的供应商名称	`Acme`
`{{MODULE}}`	PascalCase格式的模块名称	`CustomFeature`
`{{vendor_kebabcase}}`	kebab-case格式的供应商名称（按大写字母拆分）	`acme`
`{{module_kebabcase}}`	kebab-case格式的模块名称（按大写字母拆分）	`custom-feature`
`{{DESCRIPTION}}`	模块描述	`Acme CustomFeature module`
`{{SEQUENCE}}`	模块序列XML或空值	`<sequence><module name="Magento_Catalog"/></sequence>`

PascalCase to kebab-case Conversion

PascalCase转kebab-case转换

Convert module names by inserting a hyphen before each capital letter and lowercasing:

PascalCase	kebab-case
`CustomFeature`	`custom-feature`
`ShoppingCartGraphQl`	`shopping-cart-graph-ql`
`CmsComponents`	`cms-components`
`MyModule`	`my-module`

转换模块名称时，在每个大写字母前插入连字符并转为小写：

PascalCase	kebab-case
`CustomFeature`	`custom-feature`
`ShoppingCartGraphQl`	`shopping-cart-graph-ql`
`CmsComponents`	`cms-components`
`MyModule`	`my-module`

Usage by Other Skills

其他技能调用方式

Skills should reference this skill for module creation:

To create the module, use the `hyva-create-module` skill with:
- vendor: "Acme"
- module: "CmsComponents"
- dependencies: ["Hyva_CmsBase"]
- composer_require: {"hyva-themes/commerce-module-cms": "*"}

其他技能可引用此技能进行模块创建：

要创建模块，请使用`hyva-create-module`技能，参数如下：
- vendor: "Acme"
- module: "CmsComponents"
- dependencies: ["Hyva_CmsBase"]
- composer_require: {"hyva-themes/commerce-module-cms": "*"}

Example Output

示例输出

For vendor

Acme

, module

CmsComponents

, with

Hyva_CmsBase

dependency:

app/code/Acme/CmsComponents/registration.php:

php

<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(ComponentRegistrar::MODULE, 'Acme_CmsComponents', __DIR__);

app/code/Acme/CmsComponents/composer.json:

json

{
    "name": "acme/module-cms-components",
    "description": "Acme CmsComponents module",
    "type": "magento2-module",
    "require": {
        "php": ">=8.1",
        "hyva-themes/commerce-module-cms": "*"
    },
    "autoload": {
        "files": ["registration.php"],
        "psr-4": {
            "Acme\\CmsComponents\\": ""
        }
    }
}

app/code/Acme/CmsComponents/etc/module.xml:

xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Acme_CmsComponents">
        <sequence>
            <module name="Hyva_CmsBase"/>
        </sequence>
    </module>
</config>

对于供应商

Acme

、模块

CmsComponents

，且依赖

Hyva_CmsBase

的情况：

app/code/Acme/CmsComponents/registration.php：

php

<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(ComponentRegistrar::MODULE, 'Acme_CmsComponents', __DIR__);

app/code/Acme/CmsComponents/composer.json：

json

{
    "name": "acme/module-cms-components",
    "description": "Acme CmsComponents module",
    "type": "magento2-module",
    "require": {
        "php": ">=8.1",
        "hyva-themes/commerce-module-cms": "*"
    },
    "autoload": {
        "files": ["registration.php"],
        "psr-4": {
            "Acme\\CmsComponents\\": ""
        }
    }
}

app/code/Acme/CmsComponents/etc/module.xml：

xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Acme_CmsComponents">
        <sequence>
            <module name="Hyva_CmsBase"/>
        </sequence>
    </module>
</config>