Merge 0eab2d8 into 6b78b01

UPGRADE-3.x.md

@@ -1,6 +1,14 @@
 UPGRADE 3.x
 ===========
 
+## Deprecated AbstractAdmin::$persistFilters
+
+The `AbstractAdmin::$persistFilters` is deprecated and should not be used anymore.
+The problem was that it was not easy to change the way filters are persisted.
+Instead of a simple boolean var (whether to persist or not filters) you can now inject a service,
+that will be responsible for doing the job (see `FilterPersisterInterface`).
+An implementation was added, which falls back to the previous behavior : `SessionFilterPersister`.
+
 UPGRADE FROM 3.32 to 3.33
 =========================
 

docs/cookbook/recipe_persisting_filters.rst

@@ -0,0 +1,133 @@
+Persisting Filters
+==================
+
+Persisting filters allow your application to save the filters the authenticated
+user has submitted.
+Then the saved filters will be reused if the page is displayed again.
+
+
+Enable Filters Persistence
+--------------------------
+
+By default, filters persistence is disabled.
+You can enable it in your ``sonata_admin`` configuration :
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+
+        sonata_admin:
+            persist_filters: true
+
+
+Choose the persistence strategy
+-------------------------------
+
+When you enable the filters persistence by setting ``persist_filters``
+to ``true``.
+SonataAdmin will use the default filter persister :
+``Sonata\AdminBundle\Filter\Persister\SessionFilterPersister``
+(which is, by now, the only one provided).
+
+You can implement your own filter persister by creating a new class that
+implements the ``Sonata\AdminBundle\Filter\Persister\FilterPersisterInterface``
+interface and registering it as a service.
+Then the only thing to do is to tell SonataAdmin to use this service as
+filter persister.
+
+
+Globally :
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+
+        sonata_admin:
+            persist_filters: true
+            filter_persister: filter_persister_service_id
+
+
+Per Admin :
+
+.. configuration-block::
+
+    .. code-block:: xml
+
+        <!-- src/AppBundle/Resources/config/admin.xml -->
+
+        <service id="app.admin.user" class="AppBundle\Admin\UserAdmin">
+            <tag name="sonata.admin" manager_type="orm" filter_persister="filter_persister_service_id" />
+            <argument />
+            <argument>AppBundle\Entity\User</argument>
+            <argument />
+        </service>
+
+    .. code-block:: yaml
+
+        # src/AppBundle/Resources/config/admin.yml
+
+        services:
+            app.admin.user:
+                class: AppBundle\Admin\UserAdmin
+                tags:
+                    -
+                        name: sonata.admin
+                        manager_type: orm
+                        filter_persister: filter_persister_service_id
+                arguments:
+                    - null
+                    - AppBundle\Entity\User
+                    - null
+
+
+Disable filters persistence for some Admin
+------------------------------------------
+
+When you enable the filters persistence by setting ``persist_filters``
+to ``true``.
+All registered Admins will have the feature enabled.
+
+You can disable it per Admin if you want.
+
+
+.. configuration-block::
+
+    .. code-block:: xml
+
+        <!-- src/AppBundle/Resources/config/admin.xml -->
+
+        <service id="app.admin.user" class="AppBundle\Admin\UserAdmin">
+            <tag name="sonata.admin" manager_type="orm" persist_filters="false" />
+            <argument />
+            <argument>AppBundle\Entity\User</argument>
+            <argument />
+        </service>
+
+    .. code-block:: yaml
+
+        # src/AppBundle/Resources/config/admin.yml
+
+        services:
+            app.admin.user:
+                class: AppBundle\Admin\UserAdmin
+                tags:
+                    -
+                        name: sonata.admin
+                        manager_type: orm
+                        persist_filters: false
+                arguments:
+                    - null
+                    - AppBundle\Entity\User
+                    - null
+
+
+.. note::
+
+    Both ``persist_filters`` and ``filter_persister`` can be used globally
+    and per-admin, which provide you the most flexible way to configure
+    this feature.
+

docs/index.rst

@@ -94,3 +94,4 @@ The demo website can be found at http://demo.sonata-project.org.
    cookbook/recipe_delete_field_group
    cookbook/recipe_data_mapper
    cookbook/recipe_custom_view
+   cookbook/recipe_persisting_filters

docs/reference/configuration.rst

@@ -236,6 +236,7 @@ Full Configuration Options
                     instanceof:           []
                     uses:                 []
             persist_filters:      false
+            filter_persister:     sonata.admin.filter_persister.session
             show_mosaic_button:   true
             global_search:
                 show_empty_boxes: show

src/Admin/AbstractAdmin.php

@@ -25,6 +25,7 @@
 use Sonata\AdminBundle\Datagrid\ListMapper;
 use Sonata\AdminBundle\Datagrid\Pager;
 use Sonata\AdminBundle\Datagrid\ProxyQueryInterface;
+use Sonata\AdminBundle\Filter\Persister\FilterPersisterInterface;
 use Sonata\AdminBundle\Form\FormMapper;
 use Sonata\AdminBundle\Form\Type\ModelHiddenType;
 use Sonata\AdminBundle\Model\ModelManagerInterface;
@@ -195,7 +196,11 @@ abstract class AbstractAdmin implements AdminInterface, DomainObjectInterface, A
     /**
      * Whether or not to persist the filters in the session.
      *
+     * NEXT_MAJOR: remove this property
+     *
      * @var bool
+     *
+     * @deprecated since 3.x, to be removed in 4.0.
      */
     protected $persistFilters = false;
 
@@ -545,6 +550,13 @@ abstract class AbstractAdmin implements AdminInterface, DomainObjectInterface, A
      */
     private $breadcrumbsBuilder;
 
+    /**
+     * Component responsible for persisting filters.
+     *
+     * @var FilterPersisterInterface|null
+     */
+    private $filterPersister;
+
     /**
      * @param string $code
      * @param string $class
@@ -734,12 +746,20 @@ public function getFilterParameters()
         if ($this->hasRequest()) {
             $filters = $this->request->query->get('filter', []);
 
-            // if persisting filters, save filters to session, or pull them out of session if no new filters set
-            if ($this->persistFilters) {
-                if ($filters == [] && 'reset' != $this->request->query->get('filters')) {
-                    $filters = $this->request->getSession()->get($this->getCode().'.filter.parameters', []);
+            // if filter persistence is configured
+            // NEXT_MAJOR: remove `$this->persistFilters !== false` from the condition
+            if (false !== $this->persistFilters && null !== $this->filterPersister) {
+                // if reset filters is asked, remove from storage
+                if ('reset' === $this->request->query->get('filters')) {
+                    $this->filterPersister->reset($this->getCode());
+                }
+
+                // if no filters, fetch from storage
+                // otherwise save to storage
+                if (empty($filters)) {
+                    $filters = $this->filterPersister->get($this->getCode());
                 } else {
-                    $this->request->getSession()->set($this->getCode().'.filter.parameters', $filters);
+                    $this->filterPersister->set($this->getCode(), $filters);
                 }
             }
 
@@ -1363,12 +1383,29 @@ public function getLabel()
 
     /**
      * @param bool $persist
+     *
+     * NEXT_MAJOR: remove this method
+     *
+     * @deprecated since 3.x, to be removed in 4.0.
      */
     public function setPersistFilters($persist)
     {
+        @trigger_error(
+            'The '.__METHOD__.' method is deprecated since version 3.x and will be removed in 4.0.',
+            E_USER_DEPRECATED
+        );
+
         $this->persistFilters = $persist;
     }
 
+    /**
+     * @param FilterPersisterInterface|null $filterPersister
+     */
+    public function setFilterPersister(FilterPersisterInterface $filterPersister = null)
+    {
+        $this->filterPersister = $filterPersister;
+    }
+
     /**
      * @param int $maxPerPage
      */

src/Controller/HelperController.php

@@ -401,7 +401,7 @@ public function retrieveAutocompleteItemsAction(Request $request)
             return new JsonResponse(['status' => 'KO', 'message' => 'Too short search string.'], 403);
         }
 
-        $targetAdmin->setPersistFilters(false);
+        $targetAdmin->setFilterPersister(null);
         $datagrid = $targetAdmin->getDatagrid();
 
         if (null !== $callback) {

src/DependencyInjection/Compiler/AddDependencyCallsCompilerPass.php

@@ -308,13 +308,20 @@ public function applyDefaults(ContainerBuilder $container, $serviceId, array $at
 
         $definition->addMethodCall('setLabel', [$label]);
 
+        $persistFilters = $container->getParameter('sonata.admin.configuration.filters.persist');
+        // override default configuration with admin config if set
         if (isset($attributes['persist_filters'])) {
-            $persistFilters = (bool) $attributes['persist_filters'];
-        } else {
-            $persistFilters = (bool) $container->getParameter('sonata.admin.configuration.filters.persist');
+            $persistFilters = $attributes['persist_filters'];
+        }
+        $filtersPersister = $container->getParameter('sonata.admin.configuration.filters.persister');
+        // override default configuration with admin config if set
+        if (isset($attributes['filter_persister'])) {
+            $filtersPersister = $attributes['filter_persister'];
+        }
+        // configure filters persistence, if configured to
+        if ($persistFilters) {
+            $definition->addMethodCall('setFilterPersister', [new Reference($filtersPersister)]);
         }
-
-        $definition->addMethodCall('setPersistFilters', [$persistFilters]);
 
         if (isset($overwriteAdminConfiguration['show_mosaic_button'])) {
             $showMosaicButton = $overwriteAdminConfiguration['show_mosaic_button'];

src/DependencyInjection/Configuration.php

@@ -463,6 +463,7 @@ public function getConfigTreeBuilder()
                 ->end()
 
                 ->scalarNode('persist_filters')->defaultFalse()->end()
+                ->scalarNode('filter_persister')->defaultValue('sonata.admin.filter_persister.session')->end()
 
                 ->booleanNode('show_mosaic_button')
                     ->defaultTrue()

src/DependencyInjection/SonataAdminExtension.php

@@ -290,6 +290,7 @@ public function load(array $configs, ContainerBuilder $container)
 
         // set filter persistence
         $container->setParameter('sonata.admin.configuration.filters.persist', $config['persist_filters']);
+        $container->setParameter('sonata.admin.configuration.filters.persister', $config['filter_persister']);
 
         $container->setParameter('sonata.admin.configuration.show.mosaic.button', $config['show_mosaic_button']);
 

src/Filter/Persister/FilterPersisterInterface.php

@@ -0,0 +1,54 @@
+<?php
+
+/*
+ * This file is part of the Sonata Project package.
+ *
+ * (c) Thomas Rabaix <thomas.rabaix@sonata-project.org>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Sonata\AdminBundle\Filter\Persister;
+
+/**
+ * Filter persister are components responsible for storing filters for given admin.
+ * So filters are not lost when you navigate.
+ *
+ * @author Yann Eugoné <eugone.yann@gmail.com>
+ */
+interface FilterPersisterInterface
+{
+    /**
+     * Get persisted filters for given admin.
+     *
+     * @param string $adminCode The admin code
+     *
+     * @return array The persisted filters
+     */
+    public function get($adminCode);
+
+    /**
+     * Set persisted filters for given admin.
+     *
+     * @param string $adminCode The admin code
+     * @param array  $filters   The filters to persist. Structure :
+     *                          {string filter field} => array(
+     *                          "type" => {int filter type},
+     *                          "value" => {mixed filter value},
+     *                          ),
+     *                          ...,
+     *                          "_page" => {int page num},
+     *                          "_sort_by" => {string sort property},
+     *                          "_sort_order" => {string sort order (ASC|DESC)},
+     *                          "_per_page" => {int count rows per page}
+     */
+    public function set($adminCode, array $filters);
+
+    /**
+     * Reset persisted filters for given admin.
+     *
+     * @param string $adminCode The admin code
+     */
+    public function reset($adminCode);
+}