README

• 将设置定义为PHP类。
• 设置存储在单个表中。
• Bundle提供GUI来编辑设置，可以在设置定义类中进行自定义。
• 定义您的范围：每个范围都有自己的设置，支持设置继承。
• 您可以根据不同的设置/范围/配置定义多个集合。

您可以在Tests/TestApp中查看工作示例。

安装

请确保已全局安装Composer，如Composer文档中的安装章节中所述。

使用Symfony Flex的应用程序

打开命令行，进入项目目录并执行

composer require tzunghaor/settings-bundle

不使用Symfony Flex的应用程序

步骤 1: 下载Bundle

打开命令行，进入项目目录并执行以下命令以下载此Bundle的最新稳定版本

composer require tzunghaor/settings-bundle

步骤 2: 启用Bundle

然后，将Bundle添加到项目中config/bundles.php文件中已注册的Bundle列表中，以启用该Bundle

// config/bundles.php

return [
    // ...
    Tzunghaor\SettingsBundle\TzunghaorSettingsBundle::class => ['all' => true],
];

其他推荐包

• phpdocumentor/reflection-docblock - 安装此包后，您可以定义更多的设置
• symfony/asset - 设置编辑器twig模板使用asset() - 如果您未安装它，则必须重写editor_page.html.twig：请参阅twig自定义
• symfony/validator - 使用此功能，您可以在设置类上定义验证规则，这些规则将在设置编辑器中使用。请参阅symfony验证。
• symfony/security-core - 使用此功能，您可以为创建安全投票来管理谁可以编辑哪些设置。请参阅安全投票

设置

在您的Symfony配置中的framework.yaml - 将http_method_override设置为true，否则设置表单提交将无法工作。

数据库设置

您需要一个数据库表来存储您的设置 - 最简单的方法是使用此Bundle提供的实体定义。如果您启用了Doctrine中的自动映射，则可以跳过此配置步骤。

#config/packages/doctrine.yaml
doctrine:
  orm:
    auto_mapping: false
    mappings:
      Tzunghaor\SettingsBundle:
        type: attribute
          dir: '%kernel.project_dir%/vendor/tzunghaor/settings-bundle/src/Entity'
          prefix: 'Tzunghaor\SettingsBundle\Entity'

创建表

要实际创建表，请使用 doctrine migrations

$ bin/console doctrine:migrations:diff
$ bin/console doctrine:migrations:migrate

或在您的开发机上快速且危险的方法

$ bin/console doctrine:schema:update --force

关于数据库表的更多信息

定义设置类

您可以在PHP类中定义您的设置（我将此类称为设置部分，或简称部分），例如为您的设置创建一个目录（例如，src/Settings），并在其中创建一个BoxSettings.php

// src/Settings/BoxSettings.php
namespace App\Settings;
use Tzunghaor\SettingsBundle\Attribute\Setting;

class BoxSettings
{
    /**
     * @var int
     */
    public $padding = 0;

    /**
     * @var string[]
     */
    #[Setting(enum: ["bottom", "top", "left", "right"])]
    public $borders = [];
}

由于初始时没有设置存储在数据库中，因此在类中设置合理的默认值最佳。

关于设置类的更多信息

然后在配置中告诉Bundle您的设置类的位置

# config/packages/tzunghaor_settings.yaml
tzunghaor_settings:
  collections:
    # Each entry under "tzunghaor_settings" configures a setting collection.
    # Use "default" if you define only one collection
    default:
      mappings:
        # I used "default" as mapping name, but it is up to you.
        # You can have multiple mappings
        default:
          dir: '%kernel.project_dir%/src/Settings'
          prefix: App\Settings\

现在您可以从Bundle提供的服务中获取您的设置。

use App\Settings\BoxSettings;
use Tzunghaor\SettingsBundle\Service\SettingsService;

class MyService
{
    // ...
    
    public function __construct(SettingsService $settingsService)
    {
        /** 
         * declaring variable type for auto-complete support in IDE
         * @var BoxSettings $boxSettings 
         */
        $boxSettings = $settingsService->getSection(BoxSettings::class);
        $doublePadding = $boxSettings->padding * 2; 

有关集合和服务的更多信息

设置编辑器的配置

如果您已安装 symfony/asset，则可以跳过设置路由。否则，您首先需要覆盖一个twig模板：在您的应用程序中创建一个名为 templates/bundles/TzunghaorSettingsBundle 的新目录，将 Resources/views/editor_page.html.twig 复制到那里，删除 "ts_stylesheets" 和 "ts_javascripts" 块，并使用您的方法加载捆绑的 .js 和 .css。

将捆绑定义的路由添加到您的路由中

# config/routes.yaml

tzunghaor_settings_editor:
  resource: '@TzunghaorSettingsBundle/config/routes.xml'
  prefix: '/settings'

然后在浏览器中访问 https://your.domain/settings/edit/。

您可能需要在安全配置中为此控制器设置一些防火墙规则，并/或使用 安全投票者。

您可以通过路由定义对编辑器有更多控制，请参阅 路由。

设置缓存

强烈建议使用此捆绑的缓存，例如。

# config/packages/tzunghaor_settings.yaml

tzunghaor_settings:
  collections:
    default:
      cache: 'cache.app'

目前，您需要在设置部分类中进行更改时每次都清除缓存。

高级使用

使用作用域

如果您需要在不同的场景中对同一设置有不同的值，则可以使用作用域

# config/packages/tzunghaor_settings.yaml

tzunghaor_settings:
  collections:
    default:
      # tag aware cache needed when using nested scopes
      cache: 'cache.app.taggable'
      default_scope: day
      scopes:
        - name: day
          children:
            - name: morning
            - name: afternoon
        - name: night

作用域名称只能使用字母数字字符和下划线。

您可以构建任意深度的层次结构（子节点可以有子节点等），但如果您使用嵌套作用域（意味着您至少有一个 "children" 节点），则需要使用标记感知缓存，请参阅 Symfony\Contracts\Cache\TagAwareCacheInterface。

当不带主题调用 SettingsService::getSection() 时，它将使用 default_scope。否则，您需要传递作用域名称作为主题。

设置您的web服务器根据请求设置环境变量，并在您的配置中使用它可能很有用

# config/packages/tzunghaor_settings.yaml

tzunghaor_settings:
  collections:
    default:
      default_scope: %env(DEFAULT_SCOPE)%
      ...

对于更高级的使用（例如，每个用户有一个作用域），您可以定义自己的 作用域提供者