hyva-create-module

创建 Magento 2 模块

此实用技能可在 app/code/ 中创建新的 Magento 2 模块，旨在供需要模块脚手架的其他技能调用。

命令执行： 对于需要在开发环境中运行的命令（例如 bin/magento），请使用 hyva-exec-shell-cmd 技能检测环境并确定合适的命令包装器。

参数

调用此技能时，调用方技能应提供：

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

工作流

步骤 1：验证输入

• 验证供应商名称是否为 PascalCase（以大写字母开头，且仅包含字母数字字符）
• 验证模块名称是否为 PascalCase
• 检查 app/code/{Vendor}/{Module} 是否已存在

步骤 2：创建目录结构

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

步骤 3：生成文件

registration.php

使用模板 assets/templates/registration.php.tpl：

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

composer.json

使用模板 assets/templates/composer.json.tpl：

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

module.xml

使用模板 assets/templates/module.xml.tpl：

• 将 {{VENDOR}} 替换为 PascalCase 格式的供应商名称
• 将 {{MODULE}} 替换为 PascalCase 格式的模块名称
• 将 {{SEQUENCE}} 替换为包含依赖项的 <sequence> 块；如果没有依赖项，则替换为空字符串

步骤 4：运行设置（可选）

如果调用方技能提出请求，请使用 hyva-exec-shell-cmd 技能选择合适的包装器并运行 bin/magento setup:upgrade。

错误处理

遇到以下情况时，中止模块创建并向调用方技能报告错误：

条件	操作
供应商名称不是 PascalCase	报告："Invalid vendor name '{name}': must start with uppercase letter and contain only alphanumeric characters"
模块名称不是 PascalCase	报告："Invalid module name '{name}': must start with uppercase letter and contain only alphanumeric characters"
目录已存在	报告："Module already exists at app/code/{Vendor}/{Module}"
无法创建目录	报告："Failed to create directory app/code/{Vendor}/{Module}: {error}"
无法写入文件	报告："Failed to write {filename}: {error}"

如果请求执行步骤 4 时 hyva-exec-shell-cmd 技能不可用，则跳过 setup:upgrade 步骤并报告："Skipped setup:upgrade - hyva-exec-shell-cmd skill not available. Run manually: bin/magento setup:upgrade"

模板占位符

占位符	说明	示例
{{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 转 kebab-case

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

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

其他技能的用法

技能应在创建模块时引用此技能：

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": "*"}

输出示例

对于供应商 Acme、模块 CmsComponents，以及依赖项 Hyva_CmsBase：

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

<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

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

app/code/Acme/CmsComponents/composer.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 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>