oxid-esales/module-template

带有解决方案示例的模块

维护者

详细信息

github.com/OXID-eSales/module-template

源代码

问题

安装: 485

依赖项: 0

建议者: 0

安全: 0

星标: 28

关注者: 8

分支: 4

开放性问题: 0

类型：oxideshop-module

v3.0.0 2024-06-27 11:49 UTC

Requires

Requires (Dev)

Conflicts

GPL-3.0 0c75ca73d9e6dcf9a7d10065de9a38aedf302c20

moduleseshopOXID

This package is auto-updated.

Last update: 2024-09-11 06:50:28 UTC

README

Development Latest Version PHP Version

Quality Gate Status Coverage Technical Debt

用于扩展OXID eShop核心功能的可重用模块模板。

该模块模板包含最常见用例的示例（见下文），如OXID建议的实施方式。

此模块还附带OXID推荐使用的所有质量工具。

分支兼容性

  • b-6.4.x分支与OXID eShop编译b-6.4.x兼容
  • b-6.5.x分支/ v1.0.0版本 - 与OXID eShop编译b-6.5.x兼容
  • b-7.0.x分支/ v2.x版本 - 与OXID eShop编译b-7.0.x兼容
  • b-7.1.x分支/ v3.x版本 - 与OXID eShop编译7.1.x及其分支兼容

安装

此存储库旨在帮助实现以下三个主要目标

  • 通过简单的示例安装和尝试模块，以回答最常见的开发问题
    • 扩展控制器和模型
    • 服务
    • 迁移
    • 为您的模块创建模板，扩展OXID主题模板或块
    • 使用您的模块特定短语的翻译
    • 测试您的模块后端和前端部分
    • 使用github actions作为CI工具，为您预先配置所有推荐的工具。
  • 提供的解决方案可以用作您自己的模块的基础。它将帮助创建具有所有先前点中列出的示例的个性化模块基础。
  • 可以使用此存储库创建一个干净的骨架，其中仅包含为新模块预先配置的OXID推荐的质量工具。

安装并尝试

注意：此安装方法适用于尝试模块开发基础知识，不建议用作您自己的模块的开发基础。请检查其他安装/使用方法。

此模块处于工作状态，可以直接通过composer安装

composer require oxid-esales/module-template
./vendor/bin/oe-eshop-doctrine_migration migrations:migrate oe_moduletemplate

并激活模块。

作为自己模块的基础使用

如果您想将此模块用作自己模块的模板，本节为您准备。

重要 指示：如果您打算为OXID eShop 7.1.x开发模块，请在此处阅读说明。对于Shop 6.x，请参阅b-6.5.x README.md。

在开始操作之前，请先阅读本节，然后决定所需的问题，确定您想要实现的目标，并按照程序进行。

术语

首先，让我们决定一下术语

  • 决定您的 <yourVendorPrefix> 和（小写） <yourModuleRootDirectory>。
    • 请注意，<yourVendorPrefix> 和 <yourModuleRootDirectory> 的组合应该是唯一的。根据此信息，您的模块ID将被组成，其外观如下： <yourVendorPrefix>_<yourModuleRootDirectory>。在我们的例子中是 oe_moduletemplate。
    • 建议仅使用字母数字字符，如果需要分隔符，可以使用下划线。有关模块ID的更多信息，请参阅此处。
  • 模块可以安装到 vendor/<yourPackageName> 目录。包名看起来像： <yourVendorName>/<yourModuleName>，例如： oxid-esales/module-template。决定你的新模块包名。
  • 决定你的模块命名空间 - <YourVendorName>\<YourModuleName>，例如： OxidEsales\ModuleTemplate。
  • 以下示例中，你需要填写的信息将以占位符显示： <yourPackageName>，这意味着你应该在不带括号的情况下将包名放在那个位置，例如
    composer config repositories.<yourPackageName> path source/modules/<yourVendorPrefix>/<yourModuleRootDirectory>
    可能看起来像
    composer config repositories.my-vendor-name/my-module-name path source/modules/mvn/mymodulerootdir
    在我们的例子中是
    composer config repositories.oxid-esales/module-template path source/modules/oe/moduletemplate

注意：从 OXID eShop 7.0 开始，模块代码将不再复制到 source/modules 目录。这意味着在正常的 composer 安装后，你的模块代码将只位于 vendor 目录中。

  • 在以下步骤中，我们将使用我们在 模块安装教程 中的最佳实践，以便尽可能使你的开发过程变得顺畅和简单。

步骤

以下步骤描述了如何为你的进一步模块创建基础，并显示了开发过程的基本安装步骤

  1. 点击模板 主页 上的“使用此模板”按钮，从提供的模板创建你的模块仓库。请确保选择“获取所有分支”选项。作为结果，你应该有一个包含模板仓库中所有内容的仓库副本。

  2. 将你创建的仓库克隆到本地商店模块目录

    cd <shopRoot>
git clone <yourModuleGithubRepositoryUrl> source/modules/<yourVendorPrefix>/<yourModuleRootDirectory> --branch=b-7.0.x

  3. 下一步是使用你的供应商、模块 ID、命名空间等个人信息来个性化原始 OXID 跟踪。我们为此准备了一个脚本，该脚本将提示你输入所需信息，并在克隆的模板中交换所有主要位置

    cd <shopRoot>
./source/modules/<yourVendorPrefix>/<yourModuleRootDirectory>/bin/personalize.sh

    注意：此个性化脚本将自动建议一个模块 ID。请确保它符合上述提到的 模块 ID 的要求。

  4. （可选）如果你想要一个干净的模块骨架但保留所有质量工具、测试配置、github 工作流程，此外还可以使用 cleanexamples.sh 脚本，该脚本将删除所有示例解决方案代码。

     cd <shopRoot>
 ./source/modules/<yourVendorPrefix>/<yourModuleRootDirectory>/bin/cleanexamples.sh

    注意：请在脚本完成后删除 source/modules/<yourVendorPrefix>/<yourModuleRootDirectory>/bin 目录。

  5. 在商店中注册并安装你新建的模块

    cd <shopRoot>
composer config repositories.<yourPackageName> --json \
 '{"type":"path", "url":"./source/modules/<yourVendorPrefix>/<yourModuleRootDirectory>", "options": {"symlink": true}}'
composer require <yourPackageName>:*

  6. 到此为止，你有一个作为实现你想要扩展的任何内容的起点的工作模块（包括测试）。初始化并激活模块

    cd <shopRoot>
bin/oe-console oe:module:install vendor/<yourPackageName>
bin/oe-console oe:module:activate <yourModuleId>

  7. 尝试运行模块，如果模块正常工作，请将你的个性化模块更改提交到你的仓库

    cd <shopRoot>
cd source/modules/<yourVendorPrefix>/<yourModuleRootDirectory>
git commit -am "Personalize the module"

你可能不需要所有的示例代码，但你可以从中选择一些并修改。所以我们把它留给你，取你所需要的，清理所有其他内容：）

请注意，该模块包含数据库表、翻译和一些模板，这些模板仍然使用原始名称。请留意所有以 'OEMT'、'oemt'、'OEMODULETEMPLATE' 等前缀的。

此外，你还需要调整 README、CHANGELOG、LICENSE、元数据和 GitHub 工作流程文件，以使用你的凭据和名称。为了在 GitHub 工作流程步骤中将 SonarCloud 作为一部分运行，你需要配置 SonarCloud 并为你的仓库创建一个名为 SONAR_TOKEN 的秘密环境变量。令牌本身由 SonarCloud 提供。

开发安装

此处提供改善和开发当前模块的安装示例

  1. 克隆模块

    cd <shopRoot>
git clone https://github.com/OXID-eSales/module-template source/modules/oe/moduletemplate --branch=b-7.0.x

  2. 从本地路径安装模块

    cd <shopRoot>
composer config repositories.oxid-esales/module-template path source/modules/oe/moduletemplate
composer require oxid-esales/module-template:*
bin/oe-console oe:module:install vendor/oxid-esales/module-template

  3. 激活模块

    cd <shopRoot>
bin/oe-console oe:module:activate oe_moduletemplate

想法

OXID eSales 希望提供一个轻量级可重用的示例模块，其中包含我们最佳实践建议，用作开发自己模块解决方案的模板。

故事

  • 模块将扩展商店首页上的一个区块来显示问候消息（模块激活时可见）。
  • 模块将有一个设置，用于在登录用户的通用问候消息和个人自定义问候之间切换。管理员选择哪种方式。
  • 登录用户可以根据模块设置设置自定义问候。在首页上按下按钮，将被重定向到处理输入的模块控制器。
  • 用户自定义问候将通过商店模型保存方法保存。我们订阅BeforeModelUpdate来跟踪用户更改其个人问候的频率。
  • 此信息的跟踪将在新的数据库表中完成，作为模块自己的商店模型的示例。
  • 当商品添加到购物车时，模块将扩展商店的购物车模型，向特定于模块的日志文件中添加信息。日志记录可以根据模块设置启用或禁用。
  • 模块将有一个控制台命令oetemplate:logger:read来读取日志文件。
./vendor/bin/oe-console oetemplate:logger:read

扩展商店功能

有时我们只需要扩展商店已经提供的内容

  • 扩展商店模型（OxidEsales\ModuleTemplate\Extension\Model\User）或（OxidEsales\ModuleTemplate\Extension\Model\Basket）
  • 扩展商店控制器（OxidEsales\ModuleTemplate\Extension\Controller\StartController）
  • 扩展商店数据库表（oxuser）
  • 扩展商店模板区块（start_newest_articles）
  • 扩展商店管理员模板区块（admin_user_main_form - 仅扩展区块，没有功能）

提示：只有在没有其他方法（如监听和处理商店事件、装饰/替换某些DI服务）的情况下，才扩展商店核心。您的模块可能是类链中的许多模块之一，您应该相应地行事（始终确保调用父方法并返回结果）。在扩展带有附加方法的商店类时，最好使用前缀这些方法，以避免另一个模块选择相同的名称并造成混乱。如果除了扩展现有商店方法外没有其他方法，请尝试最小侵入原则。将模块业务逻辑放在服务中（这使其更容易测试），并在扩展的商店类中调用该服务。如果您需要通过覆盖来扩展商店类链，请尽量坚持使用公共方法。

有时我们需要带来自己的

  • 自己的模块控制器（oemtgreeting带有自己的模板和自己的翻译）
  • 自己的模块管理员控制器（oemt_admin_greeting带有自己的模板和自己的翻译）
  • 模块设置（oemoduletemplate_GreetingMode）
  • 事件订阅者（OxidEsales\ModuleTemplate\Tracker\Subscriber\BeforeModelUpdate）
  • 带有数据库的模型（OxidEsales\ModuleTemplate\Tracker\Model\GreetingTracker）
  • DI服务示例
  • oxNew对象工厂示例（OxidEsales\ModuleTemplate\Greeting\Infrastructure\UserModelFactory）

无论您做什么，都要确保它有测试覆盖

  • 单元/集成测试
  • Codeception测试
  • GitHub Actions流水线
  • 所有这些质量工具

尚未在此处，但可能稍后会出现

  • 支付网关扩展示例
  • 模块控制器的SEO URL ;)
  • 是否从商店核心内部重定向
  • GraphQL查询/突变示例
  • 扩展内部部分

需要注意的事项

模块模板旨在作为教程模块，因此请密切关注代码中的注释。

NOTES

  • 如果可以在模板中将相关字段和按钮放在ID上，则接受测试将更容易编写。
  • 如果可能，请尝试在OXID eShop Enterprise Edition上进行开发，以从一开始就正确处理商店相关的内容。

模块迁移

  • 迁移的目的是将数据库（以及可能存在的数据）提升到新模块版本（这也适用于首次安装）。
  • 确保迁移对重新运行稳定

必须通过控制台命令运行迁移（./vendor/bin/oe-eshop-doctrine_migration）

./vendor/bin/oe-eshop-doctrine_migration migrations:migrate oe_moduletemplate

注意：现有的迁移不能更改。如果数据库需要更改，请添加一个新的迁移文件，并按照您的需求进行更改

./vendor/bin/oe-eshop-doctrine_migration migrations:generate oe_moduletemplate

有关更多信息，请参阅开发者文档。

模块命名空间指向的位置

如上所述，在OXID eShop的7.x版本中，模块代码仅位于vendor目录中，因此命名空间需要指向那里。在我们的例子中，它看起来像这样

   "autoload": {
        "psr-4": {
            "OxidEsales\\ModuleTemplate\\": "src/",
            "OxidEsales\\ModuleTemplate\\Tests\\": "tests/"
        }
    },

运行测试和质量工具

检查模块composer.json中的scripts部分，以获取有关预配置质量工具的更多信息。例如

$ composer phpcs
$ composer phpstan
$ composer phpmd

集成/验收测试

  • 将此模块安装到运行的OXID eShop中
  • 在模块根目录中运行composer update
$ cd vendor/oxid-esales/module-template
$ composer update

完成此操作后，检查模块composer.json文件中的“scripts”部分，以查看我们如何运行测试。

$ composer tests-unit
$ composer tests-integration
$ composer tests-codeception

注意：从OXID eShop 7.0.x开始，需要使用此命令（请填写您的凭据）进行数据库重置

$ bin/oe-console oe:database:reset --db-host=mysql --db-port=3306 --db-name=example --db-user=root --db-password=root --force

如果您需要，管理员用户现在也可以通过命令行创建

$ bin/oe-console oe:admin:create-user --admin-email <admin-email> --admin-passowrd <admin-password>

例如

$ bin/oe-console oe:admin:create-user --admin-email admin@admin.com --admin-password admin

编写Codeception测试

一般来说，使用codeception测试来确保前端按预期运行。Codeception测试需要一些时间来运行，因此请尝试在覆盖相关案例和过度测试之间找到平衡。

如果模块影响前端，例如在我们的例子中，我们绝对需要一些验收测试。如果模块破坏了前端，我们需要立即看到它。

在我们的例子中，我们涵盖了起始页对不同可能性的反应

  • 通用问候模式（有/没有已登录用户）
  • 个性化问候模式（有/没有已登录用户）
  • 更新问候模式
  • 确保模块可以在不破坏商店的情况下激活/禁用
  • 确保边缘情况的安全性，例如未登录用户直接调用模块控制器

Codeception测试的优点是，它们可以在失败情况下创建截图和html输出，因此您可以直观地看到失败的情况（tests/Coreception/_output/）。

开发环境 - Docker SDK

您可以在任何适合您需求的系统上安装商店，但请检查OXID Docker SDK配方。这就是我们在OXID开发中快速设置所需任何开发环境的方法，我们一直在努力改进它们。

Github Actions工作流程

模块模板完全配备了github actions工作流程。无需设置单独的持续集成基础设施来运行测试，所有这些都在github中。您将在.github/workflow目录中看到三个文件。来自.github/workflow/trigger.yaml的工作流程在每次push和pull_request时启动，以运行代码质量检查和所有模块测试。

根据我们的经验，有时运行带有已安装和激活的模块的商店测试是有用的。当然，那些商店测试仅考虑了商店本身。您的模块，根据其功能，可能会完全改变商店的行为。这意味着带有模块的商店测试可能会在您面前爆炸。这完全正常，只要您总能解释为什么那些测试失败。

实际案例：存在一个商店验收测试用例 OxidEsales\EshopCommunity\Tests\Acceptance\Frontend\ShopSetUpTest，该用例用于测试前端商店设置。如果存在扩展类链的模块，这个测试用例有很大概率会失败。这个测试用例是从零开始设置商店的，所以它不会期望存在模块。我们只需要我们的模块安全地与一个运行的商店一起工作。我们肯定会决定跳过这个 ShopSetUpTest，因为我们有很好的解释说明为什么它不会工作。并且，这个特殊的测试用例与我们的模块一起工作也不会带来任何好处。

这只是一个例子，可能还有其他测试用例与您的模块一起失败，但失败的原因是您的模块改变了商店。在这种情况下，建议排除原始测试用例的github actions运行，将测试用例复制到您的模块测试中，并更新以适应您的模块。例如，我们使用的反向代理模块策略是强制性的，以确保不使商店的验收测试失败。除非这些测试用例在某种程度上绕过了反向代理缓存失效。为了安全起见，我们将这些少数测试用例纳入了模块，并计划尽快改进商店测试。我们也很乐意接受您改进商店测试的PR；)

然后，还有一些商店测试被标记为 @group quarantine 的文档注释。这些组的测试存在稳定性问题，因此最好也排除它们。

Ps：失败的商店测试也可能导致您的模块出现问题，在这种情况下，修复模块并让测试继续运行；)

有用链接

联系我们

如果您有任何投诉、建议、希望得到示例的业务案例，请与我们联系。我们也很乐意接受PR。我们收到的任何反馈都将帮助我们改进。