README

EasyAdmin 扩展为 Symfony 的 EasyAdmin 管理生成器提供了一些有用的扩展。

• 此包的 3.x 分支至少需要 PHP 7.1 和 Symfony 4.2 组件或堆栈，并且适用于 EasyAdmin ^2.2.2 (不允许 v2.2.0 和 v2.2.1 版本，因为它们没有本机菜单权限)。它允许安装 EasyAdmin 2.2.0 或更高版本以及 Symfony 5。**扩展包实现的列表过滤器与 EasyAdmin 动态列表过滤器不兼容！** 因此，我们引入了以下变更

  ❗ **向后不兼容** 此扩展包实现的列表过滤器现在使用 ext_filters 查询/表单参数，因为 filters 现在由原生 EasyAdmin 用于其本机动态列表过滤器的实现。

• 此包的 2.x 分支至少需要 PHP 7.1 和 Symfony 4.1 组件或堆栈，并且适用于 EasyAdmin 2.0.x 和 2.1.x。**不允许安装 EasyAdmin 2.2.0 或更高版本！**

• 此包的 1.x 分支至少需要 PHP 7.0 和 Symfony 3.0 组件或堆栈，并且适用于 EasyAdmin 1.x。

功能

• 列表过滤器表单
• 注册自己的表单类型和别名
• 在编辑和显示视图中嵌入列表
• 创建相关实体的自动完成选项
• 基于角色的访问权限
• 为自定义 POST 操作（无表单）提供确认模态
• 通过排除来设置表单字段
• 显示视图的垂直主题

安装

步骤 1: 下载 Bundle

$ composer require alterphp/easyadmin-extension-bundle

此命令要求您全局安装 Composer，具体请参阅 Composer 文档。

步骤 2: 启用 Bundle

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new AlterPHP\EasyAdminExtensionBundle\EasyAdminExtensionBundle(),
        );
    }

    // ...
}

步骤 3: 替换 EasyAdmin 控制器

而不是从 EasyAdminBundle EasyAdminController 加载路由，请从 EasyAdminExtensionBundle EasyAdminController 加载它们。

# config/routes/easy_admin.yaml
easy_admin_bundle:
    resource: '@EasyAdminExtensionBundle/Controller/EasyAdminController.php'
    type:     annotation
    prefix:   /admin

# ...

如果您已定义自己的管理控制器，请使它们扩展 EasyAdminExtensionBundle EasyAdminController。

功能

列表过滤器表单

通过配置在列表视图中添加过滤器。

考虑以下使用 ValueListTrait 的 Animation 实体

class Animation
{
    use ValueListTrait;

    /**
     * @var string
     *
     * @ORM\Id
     * @ORM\Column(type="guid")
     */
    private $id;

    /**
     * @var bool
     *
     * @ORM\Column(type="boolean", nullable=false)
     */
    private $enabled;

    /**
     * @var string
     *
     * @ORM\Column(type="string", length=31)
     */
    protected $status;

    /**
     * @var string
     *
     * @ORM\Column(type="string", length=31, nullable=false)
     */
    private $type;

    /**
     * @var int
     *
     * @ORM\Column(type="integer", nullable=false)
     */
    private $maxSubscriptions;

    /**
     * @var Organization
     *
     * @ORM\ManyToOne(targetEntity="App\Entity\Organization", inversedBy="animations")
     * @ORM\JoinColumn(nullable=false)
     */
    private $organization;

    const STATUS_DRAFT = 'draft';
    const STATUS_PUBLISHED = 'published';
    const STATUS_OPEN = 'open';
    const STATUS_ACTIVE = 'active';
    const STATUS_CLOSED = 'closed';
    const STATUS_ARCHIVED = 'archived';
}

在 list.form_filters 实体配置下定义您的过滤器

easy_admin:
    entities:
        Animation:
            class: App\Entity\Animation
            list:
                form_filters:
                    - enabled
                    - { property: type, type_options: { choices: { Challenge: challenge, Event: event } } }
                    - { property: status, type_options: { choices_static_callback: [getValuesList, [status, true]] } }
                    - organization

让我们看看结果！

自动列表过滤器猜测器

列表表单过滤器的猜测器基于映射的实体属性

• 布尔型：猜测的过滤器是一个选择列表（null，是，否）
• 字符串：猜测的过滤器是一个多选列表，需要 type_options 中的 choices（值/标签数组）或 choices_static_callback（实体类中的静态回调，返回值/标签数组）
• 整数，小数，大整数：猜测的过滤器是一个整数输入
• 十进制，浮点数：猜测的过滤器是一个数字输入
• *-to-one-relation：猜测的过滤器是关系目标实体的多个自动完成

过滤器表单的方法是 GET，并通过 form_filter 参数提交。它传递给用于 POST 更新/删除/创建重定向的 referer，以及用于搜索！

列表过滤器运算符

默认情况下，列表过滤器使用 equals 运算符或对多值过滤器使用 in。

但您可以使用更多运算符与 operator 属性一起使用

entities:
        Animation:
            class: App\Entity\Animation
            list:
                form_filters:
                    - { name: maxSubscriptionGTE, property: maxSubscriptions, label: 'Max subscriptions >=', operator: gte }
                    - { name: maxSubscriptionLTE, property: maxSubscriptions, label: 'Max subscriptions <=', operator: lte }

可用的内置运算符列在AlterPHP\EasyAdminExtensionBundle\Model\ListFilter类中，作为常量OPERATOR_*。

• equals：等于
• not：不等于
• in：在（期望是array或Doctrine Collection）
• notin：不在（期望是array或Doctrine Collection）
• gt：大于
• gte：大于等于
• lt：小于
• lte：小于等于
• like：LIKE %filterValue%

根据请求参数进行过滤列表和搜索

• EasyAdmin允许使用dql_filter配置项进行列表过滤。但这不是动态的，必须在easy_admin配置中作为单独的列表进行配置。

此扩展允许通过在URL参数中添加ext_filters参数来动态过滤列表。如果有一个包含发布年份字段的书籍列表在URL <url-to-admin>?action=list&entity=Book，您可以通过请求<url-to-admin>?action=list&entity=Book&ext_filters[entity.releaseDate]=2016来过滤2016年发布的书籍。它只匹配精确值，但可以链式调用。要请求2015年和2016年发布的书籍，必须请求<url-to-admin>?action=list&entity=Book&ext_filters[entity.releaseDate][]=2015&ext_filters[entity.releaseDate][]=2016。

此ext_filters参数被用于POST更新/删除/创建重定向的引用，以及用于搜索！

使用简短名称（别名）注册自己的表单类型

您有自定义表单类型想在EasyAdmin配置中使用。您已经可以使用FQCN注册它们 ... 但这相当无聊，并且会使管理员界面大幅膨胀。此功能允许您通过配置定义自己的表单类型，并使用简短名称。

让我们通过以下两个示例（enum和statusable）看看如何注册它们。

easy_admin_extension:
    custom_form_types:
        enum: Admin\Form\Type\EnumType
        statusable: Admin\Form\Type\StatusableType

在编辑和显示视图中嵌入列表

选项

嵌入式列表对于在其NEW/EDIT/FORM或SHOW视图中显示实体的关系很有用。它依赖于您想要在父EDIT/SHOW视图中嵌入的关联实体的LIST视图。必须在NEW/EDIT/FORM视图的type_options键或SHOW视图的template_options中定义选项。

可用的选项包括

• entity：实体配置名称（EasyAdmin entities配置下的键）
• ext_filters：要应用于列表的请求过滤器
• hidden_fields：要隐藏的列（字段）列表配置
• max_results：每页项目数（如果未定义，则使用list.max_results配置）
• sort：要应用的排序
• parent_entity_fqcn：父实体FQCN，以便猜测默认过滤器（仅当在SHOW视图中嵌入时，几乎不需要）
• parent_entity_property：父实体FQCN上的匹配属性名称（仅当在SHOW视图中嵌入时，如果property不是ORM字段）
• entity_fqcn：要列出实体的FQCN，以便猜测默认过滤器（仅当在SHOW视图中嵌入时，几乎不需要）

基于ORM元数据的选项猜测器

服务EmbeddedListHelper旨在猜测嵌入式列表的entity条目。它读取基于父实体（嵌入列表的那个实体）和属性名称的ORM元数据。

它还猜测默认过滤器（父实体和嵌入式列表之间的关系）在大多数情况下。

编辑视图

在表单定义中使用预配置的类型embedded_list

easy_admin:
    entities:
        Event:
            class: App\Entity\Event
        Promoter:
            class: App\Entity\Promoter
            form:
                fields:
                    # ...
                    - { type: group, label: Events, css_class: 'col-sm-12', icon: calendar }
                    - { property: events, label: '', type: embedded_list, type_options: { entity: Event, ext_filters: { 'entity.promoter': 'form:parent.data.id' } } }

但在许多情况下，EmbeddedListHelper会为您猜测type_options，您只需编写

easy_admin:
    entities:
        Event:
            class: App\Entity\Event
        Promoter:
            class: App\Entity\Promoter
            form:
                fields:
                    # ...
                    - { type: group, label: Events, css_class: 'col-sm-12', icon: calendar }
                    - { property: events, label: '', type: embedded_list }

让我们看看结果！

显示视图

使用猜测器进行经典的*ToMany关系

easy_admin:
    entities:
        Event:
            class: App\Entity\Event
        Promoter:
            class: App\Entity\Promoter
            show:
                fields:
                    # ...
                    - { property: events, label: '', type: embedded_list }

使用以下template_options传递选项。

禁用嵌入列表底部的“在新标签页打开”链接

• 全局在config/packages/easy_admin_extension.yaml中

      easy_admin_extension:
          embedded_list:
              open_new_tab: false

• 按实体在config/packages/easy_admin.yaml中

      easy_admin:
          entities:
              YourEntity:
                  class: App\Entity\YourEntity
                  embeddedList:
                      open_new_tab: false

自动完成：在新建和编辑模态框中添加新选项'创建'

配置表单类型'easyadmin_autocomplete'，添加type_options: { attr: { create: true } }

easy_admin:
    entities:
        Promoter:
            class: App\Entity\Promoter
        Event:
            class: App\Entity\Event
            form:
                fields:
                    # ...
                    - { property: 'promoter', type: 'easyadmin_autocomplete', type_options: { attr: { create: true } } }

定义访问权限

全局最小角色访问

您可以为访问EasyAdmin控制器（控制器处理的任何操作）定义最小角色

easy_admin_extension:
    minimum_role: ROLE_ADMIN

这只是全局限制，应与安全防火墙一起存在，如Symfony文档所述。

按实体操作角色权限

您还可以按实体操作定义角色权限

easy_admin:
    entities:
        Product:
            class: App\Entity\Product
            list:
                role: ROLE_ADMIN_PRODUCT_LIST
            search:
                role: ROLE_ADMIN_PRODUCT_SEARCH
            new:
                role: ROLE_ADMIN_PRODUCT_NEW
            edit:
                role: ROLE_ADMIN_PRODUCT_EDIT
            show:
                role: ROLE_ADMIN_PRODUCT_SHOW
            delete:
                role: ROLE_ADMIN_PRODUCT_DELETE

上述配置为Product实体操作定义了所需的角色。这太啰嗦了，不是吗？让我们按以下方式总结

easy_admin:
    entities:
        Product:
            class: App\Entity\Product
            role_prefix: ROLE_ADMIN_PRODUCT

实体role_prefix通过将操作名称附加到前缀来定义所有所需的角色。

表单中的按实体字段角色权限

您还可以在表单中按实体字段定义角色权限

easy_admin:
    entities:
        Product:
            class: App\Entity\Product
            form:
                fields:
                    - { property: enabled, role: ROLE_ADMIN }

如果用户没有所需的角色，表单字段将禁用。

无表单的自定义POST操作的确认模态框

一个通用的确认模态框要求确认（或任何自定义消息），针对具有data-confirm属性（可能包含自定义消息）和data-href属性中的URL的链接。

通过添加一个confirm键来轻松配置自定义列表操作

easyadmin:
    entities:
        User:
            list:
                actions:
                    - { name: disable, icon: ban, title: Disable user, label: false, target: _blank, confirm: User will lose any access to the platform ! }

为了在创建自定义操作模板时保持确认模态框的行为，您需要使用此捆绑包提供的操作模板，将{{ include('@EasyAdmin/default/action.html.twig') }}替换为 {{ include('@EasyAdminExtension/default/action.html.twig') }}。

在表单中排除字段

easyadmin:
    entities:
        User:
            form:
                exclude_fields: ['references']

在这种情况下实体

<?php

class User
{
    public $name;

    public $title;

    public $references;
}

它将显示所有字段，但排除exclude_fields中提到的那些，相当于以下配置

easyadmin:
    entities:
        User:
            form:
                fields: ['name', 'title']

使用模板显示垂直bootstrap

设计EasyAdmin配置

easy_admin:
    design:
        templates:
            show: '@EasyAdminExtension/default/show_vertical.html.twig'

运行测试

运行以下命令

$ ./vendor/phpunit/phpunit/phpunit

或者使用Docker和Docker Compose

$ docker-compose run --rm phpunit

运行代码质量工具

PHP CS Fixer

在本地使用Docker

docker-compose run --rm php /app/vendor/bin/php-cs-fixer fix --config=/app/.php_cs /app/src

PHPStan

在本地使用Docker

docker-compose run --rm php /app/vendor/bin/phpstan analyse -c /app/phpstan.neon --level=5 /app/src

许可证

此软件根据MIT许可证发布。