插件设置和配置

介绍

有两种配置插件的方法 - 使用后端设置表单和配置文件。 使用具有后端页面的数据库设置可提供更好的用户体验，但它们会为初始开发带来更多开销。 基于文件的配置适用于很少修改的配置。

数据库设置

您可以通过在模型类中实现SettingsModel行为来创建用于在数据库中存储设置的模型。 此模型可以直接用于创建后端设置表单。 您无需创建数据库表和控制器，以根据设置模型创建后端设置表单。

设置模型类应该扩展Model类并实现System.Behaviors.SettingsModel行为。 与任何其他模型一样，设置模型应在插件目录的models子目录中定义。 下一个示例中的模型应该在plugins/acme/demo/models/Settings.php脚本中定义。

  1. <?php namespace Acme\Demo\Models;
  3. use Model;
  5. class Settings extends Model
  6. {
  7.     public $implement = ['System.Behaviors.SettingsModel'];
  9.     // A unique code
  10.     public $settingsCode = 'acme_demo_settings';
  12.     // Reference to field configuration
  13.     public $settingsFields = 'fields.yaml';
  14. }

设置模型需要$settingsCode属性。 它定义了唯一设置键，用于将设置保存到数据库。

如果要根据模型构建后端设置表单，则需要$settingsFields属性。 该属性指定包含表单字段定义的YAML文件的名称。 表单字段在后端表单文章中描述。 应将YAML文件放在名称与小写的模型类名称匹配的目录中。 对于上一个示例中的模型，目录结构如下所示：

  1. plugins/
  2.   acme/
  3.     demo/
  4.       models/
  5.         settings/        <=== Model files directory
  6.           fields.yaml    <=== Model form fields
  7.         Settings.php     <=== Model script

设置模型可以注册显示在后端设置页面上，但不是必需的 - 您可以像设置任何其他模型一样设置和读取设置值。

写入设置模型

设置模型具有静态“set”方法，允许保存单个或多个值。 您还可以使用标准模型功能来设置模型属性并保存模型。

  1. use Acme\Demo\Models\Settings;
  3. ...
  5. // Set a single value
  6. Settings::set('api_key', 'ABCD');
  8. // Set an array of values
  9. Settings::set(['api_key' => 'ABCD']);
  11. // Set object values
  12. $settings = Settings::instance();
  13. $settings->api_key = 'ABCD';
  14. $settings->save();

从设置模型中读取

设置模型具有静态get方法，使您可以加载单个属性。 此外，当您使用instance方法实例化模型时，它会从数据库加载属性，您可以直接访问它们。

  1. // Outputs: ABCD
  2. echo Settings::instance()->api_key;
  4. // Get a single value
  5. echo Settings::get('api_key');
  7. // Get a value and return a default value if it doesn't exist
  8. echo Settings::get('is_activated', true);

后端设置页面

后端包含用于容纳设置和配置的专用区域，可通过单击主菜单中的设置</ strong>链接进行访问。 “设置”页面包含指向系统和其他插件注册的配置页面的链接列表。

设置链接注册

可以通过覆盖Plugin注册类中的registerSettings方法来扩展后端设置导航链接。 创建配置链接时，您有两个选项 - 创建指向特定后端页面的链接，或创建指向设置模型的链接。 下一个示例显示如何创建指向后端页面的链接。

  1. public function registerSettings()
  2. {
  3.     return [
  4.         'location' => [
  5.             'label'       => 'Locations',
  6.             'description' => 'Manage available user countries and states.',
  7.             'category'    => 'Users',
  8.             'icon'        => 'icon-globe',
  9.             'url'         => Backend::url('acme/user/locations'),
  10.             'order'       => 500,
  11.             'keywords'    => 'geography place placement'
  12.         ]
  13.     ];
  14. }

注意: 后端设置页面应设置设置上下文，以便在系统页面侧栏中标记相应的设置菜单项。 自动检测设置模型的设置上下文。

以下示例创建指向设置模型的链接。 设置模型是上面在数据库设置部分中描述的设置API的一部分。

  1. public function registerSettings()
  2. {
  3.     return [
  4.         'settings' => [
  5.             'label'       => 'User Settings',
  6.             'description' => 'Manage user based settings.',
  7.             'category'    => 'Users',
  8.             'icon'        => 'icon-cog',
  9.             'class'       => 'Acme\User\Models\Settings',
  10.             'order'       => 500,
  11.             'keywords'    => 'security location',
  12.             'permissions' => ['acme.users.access_settings']
  13.         ]
  14.     ];
  15. }

设置搜索功能使用可选的keywords参数。 如果未提供关键字，则搜索仅使用设置项标签和说明。

设置页面导航上下文

就像在控制器中设置导航上下文一样，后端设置页面应该设置设置导航上下文。 为了将系统页面侧栏中的当前设置链接标记为活动，需要它。 使用System\Classes\SettingsManager类设置设置上下文。 通常可以在控制器构造函数中完成：

  1. public function __construct()
  2. {
  3.     parent::__construct();
  5.     [...]
  7.     BackendMenu::setContext('October.System', 'system', 'settings');
  8.     SettingsManager::setContext('You.Plugin', 'settings');
  9. }

setContext方法的第一个参数是以下格式的设置项所有者：author.plugin。 第二个参数是设置名称，与注册后端设置页面时提供的相同。

基于文件的配置

插件可以在插件目录的config子目录中有一个配置文件config.php。 配置文件是PHP脚本，用于定义和返回数组。 示例配置文件plugins/acme/demo/config/config.php:

  1. <?php
  3. return [
  4.     'maxItems' => 10,
  5.     'display' => 5
  6. ];

使用Config类访问配置文件中定义的配置值。 `Config::get($name, $default = null)``方法接受以下格式的插件和参数名称：Acme.Demo::maxItems。 第二个可选参数定义了在配置参数不存在时要返回的默认值。 例：

  1. use Config;
  3. ...
  5. $maxItems = Config::get('acme.demo::maxItems', 50);

应用程序可以通过创建配置文件config/author/plugin/config.php来覆盖插件配置，例如config/acme/todo/dev/config.php，或config/acme/todo/config.php适用于不同的环境。 在重写的配置文件中，您只能返回要覆盖的值：

  1. <?php
  3. return [
  4.     'maxItems' => 20
  5. ];

如果你想在不同的环境中使用单独的配置(例如：dev，production)，只需在config/author/plugin/environment/config.php中创建另一个文件。 用环境名称替换环境。 这将与config/author/plugin/config.php合并。

例如:

config/author/plugin/production/config.php:

  1. <?php
  3. return [
  4.     'maxItems' => 25
  5. ];

当APP_ENV设置为 production(生产环境) 时，这会将maxItems设置为25。