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：下载扩展包

$ composer require alterphp/easyadmin-extension-bundle

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

步骤 2：启用扩展包

<?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。

功能

列表过滤器表单

通过配置添加列表视图上的过滤器。

请考虑使用以下 Animation 实体ValueListTrait

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中包含releaseYear字段的书籍列表，您可以通过请求<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元数据的选项猜测器

嵌入式列表助手服务旨在猜测嵌入式列表的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' } } }

但是在许多情况下，嵌入式列表助手为您猜测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

上面的配置为 产品 实体中的每个操作定义了一个所需的 角色。这不是太啰嗦了吗？让我们总结如下

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 属性的链接。

通过添加 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 许可证 发布