Narrow Datagrid API

phpstan-baseline.neon

@@ -1,11 +1,5 @@
 parameters:
     ignoreErrors:
-        -
-            # will be fixed in v4. Currently BC break
-            message: "#^Call to an undefined method Sonata\\\\AdminBundle\\\\Datagrid\\\\PagerInterface\\:\\:getPage\\(\\)\\.$#"
-            count: 1
-            path: src/Action/SearchAction.php
-
 # next 6 errors are due to not installed Doctrine ORM\ODM
         -
             message: "#^Class Doctrine\\\\ODM\\\\MongoDB\\\\PersistentCollection not found\\.$#"

src/Datagrid/Datagrid.php

@@ -31,12 +31,12 @@ final class Datagrid implements DatagridInterface
     /**
      * The filter instances.
      *
-     * @var array
+     * @var array<string, FilterInterface>
      */
     private $filters = [];
 
     /**
-     * @var array
+     * @var array<string, mixed>
      */
     private $values = [];
 
@@ -71,10 +71,15 @@ final class Datagrid implements DatagridInterface
     private $form;
 
     /**
-     * @var array|null
+     * Results are null prior to its initialization in `getResults()`.
+     *
+     * @var object[]|null
      */
     private $results;
 
+    /**
+     * @param array<string, mixed> $values
+     */
     public function __construct(
         ProxyQueryInterface $query,
         FieldDescriptionCollection $columns,
@@ -89,12 +94,12 @@ public function __construct(
         $this->formBuilder = $formBuilder;
     }
 
-    public function getPager()
+    public function getPager(): PagerInterface
     {
         return $this->pager;
     }
 
-    public function getResults()
+    public function getResults(): array
     {
         $this->buildPager();
 
@@ -199,17 +204,17 @@ public function addFilter(FilterInterface $filter): void
         $this->filters[$filter->getName()] = $filter;
     }
 
-    public function hasFilter($name)
+    public function hasFilter(string $name): bool
     {
         return isset($this->filters[$name]);
     }
 
-    public function removeFilter($name): void
+    public function removeFilter(string $name): void
     {
         unset($this->filters[$name]);
     }
 
-    public function getFilter($name)
+    public function getFilter(string $name): FilterInterface
     {
         if (!$this->hasFilter($name)) {
             throw new \InvalidArgumentException(sprintf(
@@ -221,7 +226,7 @@ public function getFilter($name)
         return $this->filters[$name];
     }
 
-    public function getFilters()
+    public function getFilters(): array
     {
         return $this->filters;
     }
@@ -231,20 +236,20 @@ public function reorderFilters(array $keys): void
         $this->filters = array_merge(array_flip($keys), $this->filters);
     }
 
-    public function getValues()
+    public function getValues(): array
     {
         return $this->values;
     }
 
-    public function setValue($name, $operator, $value): void
+    public function setValue(string $name, ?string $operator, $value): void
     {
         $this->values[$name] = [
             'type' => $operator,
             'value' => $value,
         ];
     }
 
-    public function hasActiveFilters()
+    public function hasActiveFilters(): bool
     {
         foreach ($this->filters as $name => $filter) {
             if ($filter->isActive()) {
@@ -255,7 +260,7 @@ public function hasActiveFilters()
         return false;
     }
 
-    public function hasDisplayableFilters()
+    public function hasDisplayableFilters(): bool
     {
         foreach ($this->filters as $name => $filter) {
             $showFilter = $filter->getOption('show_filter', null);
@@ -267,17 +272,17 @@ public function hasDisplayableFilters()
         return false;
     }
 
-    public function getColumns()
+    public function getColumns(): FieldDescriptionCollection
     {
         return $this->columns;
     }
 
-    public function getQuery()
+    public function getQuery(): ProxyQueryInterface
     {
         return $this->query;
     }
 
-    public function getForm()
+    public function getForm(): FormInterface
     {
         $this->buildPager();
 

src/Datagrid/DatagridInterface.php

@@ -23,90 +23,66 @@
  */
 interface DatagridInterface
 {
-    /**
-     * @return PagerInterface
-     */
-    public function getPager();
+    public function getPager(): PagerInterface;
 
-    /**
-     * @return ProxyQueryInterface
-     */
-    public function getQuery();
+    public function getQuery(): ProxyQueryInterface;
 
     /**
-     * @return array
+     * @return object[]
      */
-    public function getResults();
+    public function getResults(): array;
 
-    public function buildPager();
+    public function buildPager(): void;
 
-    /**
-     * @return void
-     */
-    public function addFilter(FilterInterface $filter);
+    public function addFilter(FilterInterface $filter): void;
 
     /**
-     * @return array
+     * @return array<string, FilterInterface>
      */
-    public function getFilters();
+    public function getFilters(): array;
 
     /**
      * Reorder filters.
+     *
+     * @param string[] $keys
      */
-    public function reorderFilters(array $keys);
+    public function reorderFilters(array $keys): void;
 
     /**
-     * @return array
+     * @return array<string, mixed>
      */
-    public function getValues();
+    public function getValues(): array;
 
-    /**
-     * @return FieldDescriptionCollection
-     */
-    public function getColumns();
+    public function getColumns(): FieldDescriptionCollection;
 
     /**
-     * @param string      $name
-     * @param string|null $operator
-     * @param mixed       $value
+     * @param mixed $value
      */
-    public function setValue($name, $operator, $value);
+    public function setValue(string $name, ?string $operator, $value): void;
 
-    /**
-     * @return FormInterface
-     */
-    public function getForm();
+    public function getForm(): FormInterface;
 
-    /**
-     * @param string $name
-     *
-     * @return FilterInterface
-     */
-    public function getFilter($name);
+    public function getFilter(string $name): FilterInterface;
 
-    /**
-     * @param string $name
-     *
-     * @return bool
-     */
-    public function hasFilter($name);
+    public function hasFilter(string $name): bool;
 
-    /**
-     * @param string $name
-     */
-    public function removeFilter($name);
+    public function removeFilter(string $name): void;
 
-    /**
-     * @return bool
-     */
-    public function hasActiveFilters();
+    public function hasActiveFilters(): bool;
+
+    public function hasDisplayableFilters(): bool;
 
     /**
-     * @return bool
+     * TODO: avoid returning an array with one element and return its contents instead.
+     *
+     * @return array{filter: array<string, mixed>}
      */
-    public function hasDisplayableFilters();
-
     public function getSortParameters(FieldDescriptionInterface $fieldDescription): array;
 
+    /**
+     * TODO: avoid returning an array with one element and return its contents instead.
+     *
+     * @return array{filter: array<string, mixed>}
+     */
     public function getPaginationParameters(int $page): array;
 }

src/Datagrid/DatagridMapper.php

@@ -49,6 +49,9 @@ public function __construct(
 
     /**
      * @param FieldDescriptionInterface|string $name
+     * @param array<string, mixed>             $filterOptions
+     * @param array<string, mixed>|null        $fieldOptions
+     * @param array<string, mixed>             $fieldDescriptionOptions
      *
      * @throws \LogicException
      */
@@ -60,11 +63,11 @@ public function add(
         ?array $fieldOptions = null,
         array $fieldDescriptionOptions = []
     ): self {
-        if (\is_array($fieldOptions)) {
+        if (null !== $fieldOptions) {
             $filterOptions['field_options'] = $fieldOptions;
         }
 
-        if ($fieldType) {
+        if (null !== $fieldType) {
             $filterOptions['field_type'] = $fieldType;
         }
 

src/Datagrid/ListMapper.php

@@ -53,6 +53,7 @@ public function __construct(
 
     /**
      * @param FieldDescriptionInterface|string $name
+     * @param array<string, mixed>             $fieldDescriptionOptions
      */
     public function addIdentifier($name, ?string $type = null, array $fieldDescriptionOptions = []): self
     {
@@ -72,6 +73,7 @@ public function addIdentifier($name, ?string $type = null, array $fieldDescripti
 
     /**
      * @param FieldDescriptionInterface|string $name
+     * @param array<string, mixed>             $fieldDescriptionOptions
      *
      * @throws \LogicException
      */
@@ -164,11 +166,17 @@ public function remove(string $key): self
         return $this;
     }
 
+    /**
+     * @return string[]
+     */
     final public function keys(): array
     {
         return array_keys($this->list->getElements());
     }
 
+    /**
+     * @param string[] $keys
+     */
     public function reorder(array $keys): self
     {
         $this->list->reorder($keys);