README

本软件包为框架 ICanBoogie 提供模块支持。

模块就像是你应用中的一个微型应用。它提供自己的配置、路由、操作、视图、模板等，包含执行所需功能所需的一切。

安装

composer require icanboogie/module

定义一个模块

定义一个模块至少需要两个文件：一个配置片段和一个模块类。配置片段是一个位于 config 目录中的 module.php 文件。类通常位于 lib/Module.php 文件中。模块目录通常以模块标识符命名。

以下目录结构演示了如何定义一个基本的 nodes 模块

nodes
├─ config
│  └─ module.php
└─ lib
   └─ Module.php

以下目录结构演示了一个更高级的模块

nodes
├─ config
│  └─ module.php
|  └─ <configuration files>
├─ lib
|  ├─ Operation
|  |  └─ <operation classes>
|  └─ Module.php
├─ locale
|  └─ <message catalogs>
├─ public
|  └─ <public assets>
├─ tests
|  └─ <tests>
└─ templates
   └─ <view templates>

配置片段

配置片段描述了模块及其模型。至少必须定义模块的标识符和类。模块配置负责验证模块关系的完整性、计算模块权重，并根据权重对模块进行排序。

以下代码可以是 "nodes" 模块的配置片段。

<?php

namespace Acme\Nodes;

use ICanBoogie\Binding\Module\ConfigBuilder;

return fn(ConfigBuilder $config) => $config
    ->add_module(
        id: 'nodes',
        class: Module::class
    );

操作

模块操作在 "lib/Operation" 目录中定义。例如，一个 save 操作将是一个名为 SaveOperation 的类，在命名空间 <module namespace>\Operation 中声明，位于 "SaveOperation.php" 文件中。

操作被视为继承的。如果请求对 News 模块的 save 操作，框架将尝试根据继承的模块定位最佳匹配的操作类

• ..\News\Operation\SaveOperation
• ..\Contents\Operation\SaveOperation
• ..\Nodes\Operation\SaveOperation

与模块一起工作

有两种方式与模块一起工作：当你只需要加载一个模块时，提供者就足够了；如果你需要处理多个模块，如安装，则集合更好。

访问模块

你可以使用模块提供者获取一个模块

<?php

/* @var \ICanBoogie\Module\ModuleProvider $provider */

$nodes = $provider->module_for_id('nodes');

你可以使用 has_module 方法检查模块是否已定义

<?php

/* @var \ICanBoogie\Module\ModuleProvider $provider */

$provider->has_module('nodes');

你也可以遍历提供者，并获取模块

<?php

/* @var \ICanBoogie\Module\ModuleProvider $provider */

foreach ($provider as $module_id => $get) {
    $module = $get();

    // …
}

安装和卸载模块

模块通过 install() 方法进行安装，通过 uninstall() 方法卸载。如果模块未安装，is_installed() 方法将返回模块的安装状态，并收集模块未安装的原因。

<?php

use ICanBoogie\ErrorCollection;
use ICanBoogie\Module;

/* @var Module $nodes */

$errors = new ErrorCollection();

if (!$nodes->is_installed($errors)) {
    #
    # $errors might contain messages about why the module is not installed
    #

    $errors->clear();

    if (!$nodes->install($errors)) {
        #
        # $errors might contain the reasons why the module failed to install
        #
    }
}

$nodes->uninstall();

可以使用 ModuleCollection 实例一次性安装所有模块。如果安装失败，将抛出 ModuleCollectionInstallFailed 异常，所有错误和异常都将收集到一个 ErrorCollection 实例中。

<?php

use ICanBoogie\Module\ModuleCollection;use ICanBoogie\Module\ModuleInstaller\ModuleInstallFailed;

/* @var ModuleCollection $modules */

try {
    $modules->install();
} catch (ModuleInstallFailed $e) {
    echo get_class($e->errors); // ICanBoogie\ErrorCollection
}

自动配置

该软件包支持 ICanBoogie 的 autoconfig 功能。

模板解析装饰器

使用ModuleTemplateResolver实例来装饰在类TemplateResolver\AlterEvent的ICanBoogie\Render\BasicTemplateResolver::alter事件触发时定义的模板解析器实例，以支持模块定义的模板。当模板名称的路径部分与已激活的模块标识符匹配时，将使用模块及其父模块解析模板路径名称。

事件钩子

• routing.collect_routes:before：通过添加包含定义该路由的模块标识符的module键来修改模块定义的路由。

持续集成

该项目由GitHub actions进行持续测试。

行为准则

本项目遵循贡献者行为准则。通过参与本项目及其社区，您应遵守此准则。

贡献

有关详细信息，请参阅CONTRIBUTING。

许可证

icanboogie/module在BSD-3-Clause许可下发布。