如何在Symfony 5 + EasyAdmin 3中自定义表单？旧配置不生效怎么办？

按照官方文档提供的示例操作：
https://symfony.com/doc/2.x/bundles/EasyAdminBundle/book/edit-new-configuration.html

# config/packages/easy_admin.yaml
easy_admin:
    # ...
    entities:
        Customer:
            class: App\Entity\Customer
            form:
                fields:
                    - id
                    - { type: 'section', label: 'User Details' }
                    - name
                    - surname
                    - { type: 'section', label: 'Contact information', icon: 'phone',
                        help: 'Phone number is preferred' }
                    - email
                    - phoneNumber

问题详情：

• 我原本没有对应配置文件，因此按照示例的路径在相同目录下创建了easyadmin.yaml文件；
• 哪怕是最基础的示例配置也无法正常生效；
• 我推测问题根源是版本差异，如果确实是版本导致的，咨询EasyAdmin 3中应当如何编辑自定义表单？

配置不生效排查步骤 #

1. 核对配置文件名
   官方示例的配置文件名为easy_admin.yaml（中间带下划线），如果创建的是easyadmin.yaml（无下划线），Symfony会因文件名不符合包配置命名规则，完全不会加载该文件内容。
2. 校验YAML语法
   YAML对缩进要求严格，必须使用2空格缩进、禁止使用制表符（Tab），跨行的help字段需和上级字段保持相同缩进，否则会直接触发配置解析失败，所有配置静默不生效。
3. 清除配置缓存
   修改配置后执行php bin/console cache:clear，生产环境需追加--env=prod参数。
4. 验证配置加载状态
   执行php bin/console debug:config easy_admin，如果输出的配置中未包含自定义的Customer实体配置，说明上述步骤存在问题。

版本差异核心说明 #

EasyAdmin 3已完全废弃EasyAdmin 2的全局YAML定义实体表单的模式，改用CRUD控制器类定义表单、列表、详情页的字段配置，YAML文件仅保留全局基础参数（如站点名称、通用布局配置）的设置能力。

EasyAdmin 3自定义表单实现方式 #

1. 生成对应实体的CRUD控制器：

   php bin/console make:admin:crud App\Entity\Customer
   

2. 在生成的CustomerCrudController中重写configureFields()方法，对应需求的配置写法如下：

   <?php
   namespace App\Controller\Admin;
   
   use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractCrudController;
   use EasyCorp\Bundle\EasyAdminBundle\Field\IdField;
   use EasyCorp\Bundle\EasyAdminBundle\Field\TextField;
   use EasyCorp\Bundle\EasyAdminBundle\Field\EmailField;
   use EasyCorp\Bundle\EasyAdminBundle\Field\TelephoneField;
   use EasyCorp\Bundle\EasyAdminBundle\Field\SectionField;
   use EasyCorp\Bundle\EasyAdminBundle\Config\Crud;
   
   class CustomerCrudController extends AbstractCrudController
   {
       public static function getEntityFqcn(): string
       {
           return \App\Entity\Customer::class;
       }
   
       public function configureFields(string $pageName): iterable
       {
           return [
               // 表单页隐藏ID字段，和EasyAdmin 2默认行为一致
               IdField::new('id')->hideOnForm(),
               // 用户详情分块
               SectionField::new('')->setLabel('User Details'),
               TextField::new('name'),
               TextField::new('surname'),
               // 联系信息分块，配置图标和帮助文本
               SectionField::new('contact')->setLabel('Contact information')
                   ->setIcon('phone')
                   ->setHelp('Phone number is preferred'),
               EmailField::new('email'),
               TelephoneField::new('phoneNumber'),
           ];
   
           // 如需区分新建、编辑、列表页的字段逻辑，可通过$pageName判断
           // 示例：仅在新建页显示某字段
           // if ($pageName === Crud::PAGE_NEW) {
           //     yield TextField::new('customField');
           // }
       }
   }
   

3. 在Dashboard控制器的configureMenuItems()方法中注册该CRUD控制器对应的菜单项，配置即可正常生效。

内容的提问来源于stack exchange，提问作者Luis Vallejos