jaunas/oxiddebugbar

Oxid调试栏

维护者

详细信息

github.com/jaunas/oxiddebugbar

源代码

问题

安装: 28

依赖: 0

建议者: 0

安全性: 0

星标: 0

关注者: 1

分支: 0

开放问题: 1

类型:oxideshop-module

dev-b-7.2.x 2024-08-31 10:33 UTC

Requires

Requires (Dev)

Conflicts

GPL-3.0 d027bb06de40d6bddc22450fea5746f6eb72c395

moduleseshopOXID

This package is auto-updated.

Last update: 2024-09-23 12:16:39 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动作作为CI工具，为您预先配置了所有推荐工具。
  • 提供的解决方案可以用作您自己的模块的基础。它将帮助创建所有前述示例中的个性化模块基础。
  • 可以使用此存储库创建一个干净的骨架，仅包含为您的新的模块预配置的OXID推荐质量工具。

安装并试用

注意：此安装方法适合尝试模块开发基础知识，它不是用作您自己模块的开发基础。请检查进一步的安装/使用方法。

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

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

和激活模块。

作为自己模块的基础

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

重要 指示本节是针对您打算为OXID eShop 7.1.x开发模块的情况。对于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。决定您的新模块包名。
  • 确定您模块的命名空间 - <您的供应商名称>\<您的模块名称>，例如：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. 到此为止，您有一个作为起点的工作模块（包括测试）以实现您在OXID eShop中想要扩展的任何内容。初始化并激活模块

    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_welcome_text）

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

有时我们需要自己带来

  • 自己的模块控制器（具有自己的模板和自己的翻译的oemtgreeting）
  • 模块设置（oemoduletemplate_GreetingMode）
  • 事件订阅者（OxidEsales\ModuleTemplate\Tracker\Subscriber\BeforeModelUpdate）
  • 具有数据库的模型（OxidEsales\ModuleTemplate\Tracker\Model\GreetingTracker）
  • DI服务示例

无论您做什么，都要确保对其进行测试覆盖

  • 单元/集成测试
  • codeception测试
  • github actions流水线
  • 所有优秀质量工具

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

  • 支付网关扩展示例
  • 模块控制器的SEO URL；（
  • 从商店核心内部重定向或不重定向
  • GraphQL查询/变异示例
  • 扩展内部部分

需要注意的事项

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

NOTES

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

模块迁移

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

必须通过控制台命令（./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。该组中的测试存在稳定性问题，因此最好也将其排除。

提示：失败的商店测试也可能在您的模块中引发问题，在这种情况下，修复模块并让测试继续；）

有用链接

联系我们

如果您有任何投诉、建议、需要示例的商业案例，请与我们联系。我们也欢迎拉取请求。我们收到的每一条反馈都将帮助我们改进。