Introduce field description factory

UPGRADE-3.x.md

@@ -4,13 +4,25 @@ UPGRADE 3.x
 UPGRADE FROM 3.89 to 3.90
 =========================
 
+### Deprecated `Sonata\AdminBundle\Guesser\TypeGuesserInterface` interface.
+
+Use `Sonata\AdminBundle\FieldDescription\TypeGuesserInterface` interface instead.
+
+### Deprecated `Sonata\AdminBundle\Guesser\TypeGuesserChain` class.
+
+Use `Sonata\AdminBundle\FieldDescription\TypeGuesserChain` class instead.
+
 ### Deprecated `Sonata\AdminBundle\Model\ModelManagerInterface::getModelInstance()` method.
 
 Use `Sonata\AdminBundle\Admin\AbstractAdmin::createNewInstance()` method instead.
 
 UPGRADE FROM 3.88 to 3.89
 =========================
 
+### Deprecated `Sonata\AdminBundle\Model\ModelManager::getNewFieldDescriptionInstance()` method.
+
+This method has been deprecated in favor of `FieldFactoryInterface::create()`.
+
 ### Deprecated overriding `AbstractAdmin::getNewInstance()`.
 
 Use `AbstractAdmin::alterNewInstance()` instead.

src/Admin/AbstractAdmin.php

@@ -746,10 +746,8 @@ public function buildDatagrid()
             if ($this->hasListFieldDescription($filterParameters['_sort_by'])) {
                 $filterParameters['_sort_by'] = $this->getListFieldDescription($filterParameters['_sort_by']);
             } else {
-                $filterParameters['_sort_by'] = $this->getModelManager()->getNewFieldDescriptionInstance(
-                    $this->getClass(),
-                    $filterParameters['_sort_by'],
-                    []
+                $filterParameters['_sort_by'] = $this->createFieldDescription(
+                    $filterParameters['_sort_by']
                 );
 
                 $this->getListBuilder()->buildField(null, $filterParameters['_sort_by'], $this);
@@ -2892,6 +2890,26 @@ final public function hasTemplateRegistry(): bool
         return null !== $this->templateRegistry;
     }
 
+    final public function createFieldDescription(string $propertyName, array $options = []): FieldDescriptionInterface
+    {
+        $fieldDescriptionFactory = $this->getFieldDescriptionFactory();
+
+        // NEXT_MAJOR: Remove the "if" block and leave the "else" one.
+        if (null === $fieldDescriptionFactory) {
+            $fieldDescription = $this->getModelManager()->getNewFieldDescriptionInstance(
+                $this->getClass(),
+                $propertyName,
+                $options
+            );
+        } else {
+            $fieldDescription = $fieldDescriptionFactory->create($this->getClass(), $propertyName, $options);
+        }
+
+        $fieldDescription->setAdmin($this);
+
+        return $fieldDescription;
+    }
+
     /**
      * @phpstan-return T
      */
@@ -3096,8 +3114,7 @@ protected function buildList()
         $mapper = new ListMapper($this->getListBuilder(), $this->list, $this);
 
         if (\count($this->getBatchActions()) > 0 && $this->hasRequest() && !$this->getRequest()->isXmlHttpRequest()) {
-            $fieldDescription = $this->getModelManager()->getNewFieldDescriptionInstance(
-                $this->getClass(),
+            $fieldDescription = $this->createFieldDescription(
                 'batch',
                 [
                     'label' => 'batch',
@@ -3107,7 +3124,6 @@ protected function buildList()
                 ]
             );
 
-            $fieldDescription->setAdmin($this);
             // NEXT_MAJOR: Remove this line and use commented line below it instead
             $fieldDescription->setTemplate($this->getTemplate('batch'));
             // $fieldDescription->setTemplate($this->getTemplateRegistry()->getTemplate('batch'));
@@ -3122,8 +3138,7 @@ protected function buildList()
         }
 
         if ($this->hasRequest() && $this->getRequest()->isXmlHttpRequest()) {
-            $fieldDescription = $this->getModelManager()->getNewFieldDescriptionInstance(
-                $this->getClass(),
+            $fieldDescription = $this->createFieldDescription(
                 'select',
                 [
                     'label' => false,
@@ -3133,7 +3148,6 @@ protected function buildList()
                 ]
             );
 
-            $fieldDescription->setAdmin($this);
             // NEXT_MAJOR: Remove this line and use commented line below it instead
             $fieldDescription->setTemplate($this->getTemplate('select'));
             // $fieldDescription->setTemplate($this->getTemplateRegistry()->getTemplate('select'));

src/Admin/AdminInterface.php

@@ -51,6 +51,7 @@
  * @method string|null                     getParentAssociationMapping()
  * @method void                            reorderFormGroup(string $group, array $keys)
  * @method void                            defineFormBuilder(FormBuilderInterface $formBuilder)
+ * @method FieldDescriptionInterface       createFieldDescription(string $propertyName, array $options = [])
  *
  * @phpstan-template T of object
  * @phpstan-extends AccessRegistryInterface<T>
@@ -789,6 +790,9 @@ public function getListMode();
 //     * the getFormBuilder is only call by the main admin class.
 //     */
 //    public function defineFormBuilder(FormBuilderInterface $formBuilder): void;
+
+//    NEXT_MAJOR: uncomment this method in 4.0
+//    public function createFieldDescription(string $propertyName, array $options = []): FieldDescriptionInterface;
 }
 
 class_exists(\Sonata\Form\Validator\ErrorElement::class);

src/Admin/BaseFieldDescription.php

@@ -63,6 +63,8 @@
  *
  * @author Thomas Rabaix <[email protected]>
  *
+ * @psalm-import-type FieldDescriptionOptions from FieldDescriptionInterface
+ *
  * @method void setFieldMapping(array $fieldMapping)
  * @method void setAssociationMapping(array $associationMapping)
  * @method void setParentAssociationMappings(array $parentAssociationMappings)
@@ -141,6 +143,9 @@ abstract class BaseFieldDescription implements FieldDescriptionInterface
 
     /**
      * NEXT_MAJOR: Remove the null default value for $name and restrict param type to `string`.
+     *
+     * @psalm-param FieldDescriptionOptions $options
+     * @phpstan-param array<string, mixed> $options
      */
     public function __construct(
         ?string $name = null,

src/Admin/FieldDescriptionInterface.php

@@ -14,10 +14,46 @@
 namespace Sonata\AdminBundle\Admin;
 
 use Sonata\AdminBundle\Exception\NoValueException;
+use Symfony\Component\Form\DataTransformerInterface;
+use Symfony\Component\PropertyAccess\PropertyPathInterface;
 
 /**
  * @author Thomas Rabaix <[email protected]>
  *
+ * @psalm-type FieldDescriptionOptions = array{
+ *  accessor?: string|callable|PropertyPathInterface,
+ *  actions?: array,
+ *  admin_code?: string,
+ *  associated_property?: string,
+ *  block_name?: string,
+ *  catalogue?: string,
+ *  data_transformer?: DataTransformerInterface,
+ *  edit?: string,
+ *  editable?: bool,
+ *  field_name?: string,
+ *  field_options?: array,
+ *  field_type?: string,
+ *  header_class?: string,
+ *  identifier?: bool,
+ *  inline?: string,
+ *  label?: bool|string|null,
+ *  link_parameters?: array,
+ *  multiple?: bool,
+ *  placeholder?: string,
+ *  required?: bool,
+ *  role?: string|string[],
+ *  route?: array,
+ *  safe?: bool,
+ *  sort_field_mapping?: array,
+ *  sort_parent_association_mappings?: array,
+ *  sortable?: bool,
+ *  template?: string,
+ *  timezone?: string|\DateTimeZone,
+ *  translation_domain?: string,
+ *  type?: string,
+ *  virtual_field?: bool
+ * }
+ *
  * @method string|null getTargetModel()
  * @method bool        hasAdmin()
  * @method bool        hasParent()
@@ -105,13 +141,19 @@ public function setOption($name, $value);
      *   - template.
      *
      * Then the value are copied across to the related property value
+     *
+     * @psalm-param FieldDescriptionOptions $options
+     * @phpstan-param array<string, mixed> $options
      */
     public function setOptions(array $options);
 
     /**
      * Returns options.
      *
      * @return array<string, mixed> options
+     *
+     * @psalm-return FieldDescriptionOptions
+     * @phpstan-return array<string, mixed>
      */
     public function getOptions();
 

src/Datagrid/DatagridMapper.php

@@ -114,11 +114,19 @@ public function add(
                 $filterOptions['field_name'] = substr(strrchr('.'.$name, '.'), 1);
             }
 
-            $fieldDescription = $this->admin->getModelManager()->getNewFieldDescriptionInstance(
-                $this->admin->getClass(),
-                $name,
-                array_merge($filterOptions, $fieldDescriptionOptions)
-            );
+            // NEXT_MAJOR: Remove the check and use `createFieldDescription`.
+            if (method_exists($this->admin, 'createFieldDescription')) {
+                $fieldDescription = $this->admin->createFieldDescription(
+                    $name,
+                    array_merge($filterOptions, $fieldDescriptionOptions)
+                );
+            } else {
+                $fieldDescription = $this->admin->getModelManager()->getNewFieldDescriptionInstance(
+                    $this->admin->getClass(),
+                    $name,
+                    array_merge($filterOptions, $fieldDescriptionOptions)
+                );
+            }
         } else {
             throw new \TypeError(
                 'Unknown field name in datagrid mapper.'

src/Datagrid/ListMapper.php

@@ -144,11 +144,19 @@ public function add($name, $type = null, array $fieldDescriptionOptions = [])
                 ));
             }
 
-            $fieldDescription = $this->admin->getModelManager()->getNewFieldDescriptionInstance(
-                $this->admin->getClass(),
-                $name,
-                $fieldDescriptionOptions
-            );
+            // NEXT_MAJOR: Remove the check and use `createFieldDescription`.
+            if (method_exists($this->admin, 'createFieldDescription')) {
+                $fieldDescription = $this->admin->createFieldDescription(
+                    $name,
+                    $fieldDescriptionOptions
+                );
+            } else {
+                $fieldDescription = $this->admin->getModelManager()->getNewFieldDescriptionInstance(
+                    $this->admin->getClass(),
+                    $name,
+                    $fieldDescriptionOptions
+                );
+            }
         } else {
             throw new \TypeError(
                 'Unknown field name in list mapper.'

src/DependencyInjection/Admin/AbstractTaggedAdmin.php

@@ -22,6 +22,7 @@
 use Sonata\AdminBundle\Builder\ShowBuilderInterface;
 use Sonata\AdminBundle\Datagrid\Pager;
 use Sonata\AdminBundle\Exporter\DataSourceInterface;
+use Sonata\AdminBundle\FieldDescription\FieldDescriptionFactoryInterface;
 use Sonata\AdminBundle\Filter\Persister\FilterPersisterInterface;
 use Sonata\AdminBundle\Model\ModelManagerInterface;
 use Sonata\AdminBundle\Route\RouteGeneratorInterface;
@@ -202,6 +203,11 @@ abstract class AbstractTaggedAdmin implements TaggedAdminInterface
      */
     protected $labelTranslatorStrategy;
 
+    /**
+     * @var FieldDescriptionFactoryInterface|null
+     */
+    private $fieldDescriptionFactory;
+
     /**
      * NEXT_MAJOR: Change signature to __construct(string $code, string $class, string $baseControllerName).
      *
@@ -423,6 +429,32 @@ public function getDataSource(): ?DataSourceInterface
         return $this->dataSource;
     }
 
+    final public function setFieldDescriptionFactory(FieldDescriptionFactoryInterface $fieldDescriptionFactory): void
+    {
+        $this->fieldDescriptionFactory = $fieldDescriptionFactory;
+    }
+
+    /**
+     * NEXT_MAJOR: Change typehint for FieldDescriptionFactoryInterface.
+     */
+    public function getFieldDescriptionFactory(): ?FieldDescriptionFactoryInterface
+    {
+        if (null === $this->fieldDescriptionFactory) {
+            // NEXT_MAJOR: Remove this deprecation and uncomment the following exception
+            @trigger_error(sprintf(
+                'Calling %s() when no field description factory is set is deprecated since sonata-project/admin-bundle 3.x'
+                .' and will throw a LogicException in 4.0',
+                __METHOD__,
+            ), \E_USER_DEPRECATED);
+//            throw new \LogicException(sprintf(
+//                'Admin "%s" has no field description factory.',
+//                static::class
+//            ));
+        }
+
+        return $this->fieldDescriptionFactory;
+    }
+
     /**
      * @final since sonata-admin/admin-bundle 3.84
      */

src/DependencyInjection/Admin/TaggedAdminInterface.php

@@ -21,6 +21,7 @@
 use Sonata\AdminBundle\Builder\RouteBuilderInterface;
 use Sonata\AdminBundle\Builder\ShowBuilderInterface;
 use Sonata\AdminBundle\Exporter\DataSourceInterface;
+use Sonata\AdminBundle\FieldDescription\FieldDescriptionFactoryInterface;
 use Sonata\AdminBundle\Filter\Persister\FilterPersisterInterface;
 use Sonata\AdminBundle\Model\ModelManagerInterface;
 use Sonata\AdminBundle\Route\RouteGeneratorInterface;
@@ -41,25 +42,27 @@
  *     - The first and third argument are automatically injected by the AddDependencyCallsCompilerPass.
  *     - The second one is used as a reference of the Admin in the Pool, with the `setAdminClasses` call.
  *
- * @method void                          initialize()
- * @method void                          setLabel(?string $label)
- * @method void                          showMosaicButton(bool $isShown)
- * @method void                          setPagerType(string $pagerType)
- * @method string                        getPagerType()
- * @method void                          setManagerType(string $managerType)
- * @method void                          setSecurityInformation(array $information)
- * @method void                          setFilterPersister(?FilterPersisterInterface $filterPersister = null)
- * @method FilterPersisterInterface|null getFilterPersister()
- * @method bool                          hasFilterPersister()
- * @method void                          setModelManager(ModelManagerInterface $modelManager)
- * @method void                          setDataSource(DataSourceInterface $dataSource)
- * @method DataSourceInterface           getDataSource()
- * @method FormContractorInterface       getFormContractor()
- * @method void                          setShowBuilder(ShowBuilderInterface $showBuilder)
- * @method ShowBuilderInterface          getShowBuilder()
- * @method Pool                          getConfigurationPool()
- * @method void                          setRouteGenerator(RouteGeneratorInterface $routeGenerator)
- * @method RouteGeneratorInterface       getRouteGenerator()
+ * @method void                             initialize()
+ * @method void                             setLabel(?string $label)
+ * @method void                             showMosaicButton(bool $isShown)
+ * @method void                             setPagerType(string $pagerType)
+ * @method string                           getPagerType()
+ * @method void                             setManagerType(string $managerType)
+ * @method void                             setSecurityInformation(array $information)
+ * @method void                             setFilterPersister(?FilterPersisterInterface $filterPersister = null)
+ * @method FilterPersisterInterface|null    getFilterPersister()
+ * @method bool                             hasFilterPersister()
+ * @method void                             setModelManager(ModelManagerInterface $modelManager)
+ * @method void                             setDataSource(DataSourceInterface $dataSource)
+ * @method DataSourceInterface              getDataSource()
+ * @method void                             setFieldDescriptionFactory(FieldDescriptionFactoryInterface $fieldDescriptionFactory)
+ * @method FieldDescriptionFactoryInterface getFieldDescriptionFactory()
+ * @method FormContractorInterface          getFormContractor()
+ * @method void                             setShowBuilder(ShowBuilderInterface $showBuilder)
+ * @method ShowBuilderInterface             getShowBuilder()
+ * @method Pool                             getConfigurationPool()
+ * @method void                             setRouteGenerator(RouteGeneratorInterface $routeGenerator)
+ * @method RouteGeneratorInterface          getRouteGenerator()
  */
 interface TaggedAdminInterface
 {
@@ -168,6 +171,16 @@ public function getModelManager();
      */
 //    public function getDataSource(): DataSourceInterface;
 
+    /**
+     * NEXT_MAJOR: Uncomment this method.
+     */
+//    public function setFieldDescriptionFactory(FieldDescriptionFactoryInterface $fieldDescriptionFactory): void;
+
+    /**
+     * NEXT_MAJOR: Uncomment this method.
+     */
+//    public function getFieldDescriptionFactory(): FieldDescriptionFactoryInterface;
+
     /**
      * @return void
      */