配置项管理文档

本文档详细介绍了基于 xbcode 框架的配置管理系统，包括全局配置、插件配置等多种配置方式。

全局配置

webman 的配置文件统一存放在 config/ 目录下，可以通过 config() 函数来获取对应的配置项。

基础用法

获取所有配置

config();

获取指定配置文件的所有配置

获取 config/app.php 里的所有配置：

config('app');

获取指定配置项

获取 config/app.php 里的 debug 配置：

config('app.debug');

获取数组配置的子项

如果配置是数组，可以通过 . 来获取数组内部元素的值：

config('file.key1.key2');

Composer配置

框架的 Composer 配置遵循以下路径规范：

路径结构： /config/plugin/{插件配置目录}

插件配置

插件配置提供了多种灵活的配置方式，可根据不同场景选择合适的配置类型。

文件配置

插件的配置与普通 webman 项目一样，插件的配置一般只对当前插件有效，对主项目一般无影响。

配置文件位置： /plugin/{插件名称}/config

特点：

• 仅对当前插件生效
• 不影响主项目配置
• 使用 config() 函数读取

面板配置

插件安装后，可在后台管理界面进行配置。

配置路径： 插件管理 → 本地插件 → 已安装插件 → 配置

实现方式：

需要在 /plugin/{插件名称}/api/Install.php 中添加 config 方法：

public function config()
{
  return ->getPanelConfig(->name);
}

面板配置图

系统配置

系统配置用于在后台系统设置页面添加全局性的配置选项。

配置展示位置： 后台 → 系统配置 → 系统设置 → 标签选项卡

实现步骤：

1. 在 /plugin/{插件名称}/config/xbcode.php 中的 setting 配置项添加配置文件名称
2. 在 /plugin/tabs/{文件名称}.php 中定义具体的配置表单

示例：

return [
  'setting' => [
    'your_config_tab'
  ]
];

系统选项卡标签配置图

普通配置

普通配置用于展示简单的配置项表单，适合单页面的配置管理。

实现步骤：

1. 在 /plugin/{插件名称}/app/{模块名称}/controller/ 添加控制器
2. 创建方法，方法名即配置项的文件名
3. 在 {插件目录}/setting/config/{文件名称}.php 定义配置表单

代码示例：

public function user()
{
  return ->configNormal();
}

说明：

• 方法名 user 对应配置文件 user.php
• 自动扫描路径：{插件目录}/setting/config/user.php

普通配置预览图

选项卡配置

选项卡配置用于展示多标签页的配置项表单，适合配置项较多且需要分类的场景。

实现步骤：

1. 在 /plugin/{插件名称}/app/{模块名称}/controller/ 添加控制器
2. 创建方法，方法名即配置项的文件名
3. 在 {插件目录}/setting/tabs/{文件名称}.php 定义配置表单

代码示例：

public function user()
{
  return ->configTabs();
}

说明：

• 方法名 user 对应配置文件 user.php
• 自动扫描路径：{插件目录}/setting/tabs/user.php

侧边栏配置

侧边栏配置用于展示带侧边导航的配置项表单，适合配置项目众多且需要多级分类的场景。

实现步骤：

1. 在 /plugin/{插件名称}/app/{模块名称}/controller/ 添加控制器
2. 创建方法，方法名即配置项的文件名
3. 在 {插件目录}/setting/tabs/{文件名称}.php 定义配置表单

代码示例：

public function user()
{
  return ->configSidebar();
}

说明：

• 方法名 user 对应配置文件 user.php
• 自动扫描路径：{插件目录}/setting/tabs/user.php

配置方式对比

最佳实践

1. 配置分层：根据配置的作用范围选择合适的配置类型
2. 命名规范：配置文件名、方法名保持一致，使用小写字母和下划线
3. 配置隔离：插件配置应避免影响主项目配置
4. 文档说明：为每个配置项添加清晰的说明和默认值
5. 验证机制：在配置保存前进行数据验证，确保配置的正确性