clean documentation (#23)

authored-by: Gilles Gauthier <[email protected]>
SpiriitLabs · Jul 31, 2024 · ab29c2e · ab29c2e
1 parent 3337d9b
commit ab29c2e
Show file tree

Hide file tree

Showing 7 changed files with 153 additions and 337 deletions.
diff --git a/README.md b/README.md
@@ -21,7 +21,14 @@ The idea is:
 (*): In fact you can use any type, but if you want to apply a filter by not using a XxxFilterType::class type you will 
 have to create a custom listener class to apply the filter for this type.
 
+## Installation
+================
 
+The bundle can be installed using Composer or the [Symfony binary](https://symfony.com/download):
+
+```
+composer require spiriitlabs/form-filter-bundle
+```
 
 Documentation
 =============

diff --git a/Resources/doc/basics.md b/Resources/doc/basics.md
@@ -80,35 +80,42 @@ Then in an action, create a form object from the ItemFilterType. Let's say we fi
 // DefaultController.php
 namespace Project\Bundle\SuperBundle\Controller;
 
-use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Form\FormFactoryInterface;
 use Project\Bundle\SuperBundle\Filter\ItemFilterType;
+use Project\Bundle\SuperBundle\Entity\MyEntity;
+use Spiriit\Bundle\FormFilterBundle\Filter\FilterBuilderUpdater;
 
-class DefaultController extends Controller
+class DefaultController extends AbstractController
 {
-    public function testFilterAction(Request $request)
+    public function __invoke(
+    Request $request, 
+    FormFactoryInterface $formFactory,
+    EntityManagerInterface $em,
+    FilterBuilderUpdater $filterBuilderUpdater
+    ): Response
     {
-        $form = $this->get('form.factory')->create(ItemFilterType::class);
+        $form = $formFactory->create(ItemFilterType::class);
 
-        if ($request->query->has($form->getName())) {
-            // manually bind values from the request
-            $form->submit($request->query->get($form->getName()));
+        // manually bind values from the request
+        $form->submit($request->query->get($form->getName()));
 
-            // initialize a query builder
-            $filterBuilder = $this->get('doctrine.orm.entity_manager')
-                ->getRepository('ProjectSuperBundle:MyEntity')
-                ->createQueryBuilder('e');
+        // initialize a query builder
+        $filterBuilder = $em
+            ->getRepository(MyEntity::class)
+            ->createQueryBuilder('e');
 
-            // build the query from the given form object
-            $this->get('spiriit_form_filter.query_builder_updater')->addFilterConditions($form, $filterBuilder);
+        // build the query from the given form object
+        $filterBuilderUpdater->addFilterConditions($form, $filterBuilder);
 
-            // now look at the DQL =)
-            var_dump($filterBuilder->getDql());
-        }
+        // now look at the DQL =)
+        dump($filterBuilder->getDql());
 
-        return $this->render('ProjectSuperBundle:Default:testFilter.html.twig', array(
-            'form' => $form->createView(),
-        ));
+        return $this->render('testFilter.html.twig', [
+            'form' => $form,
+        ]);
     }
 }
 ```
@@ -126,9 +133,13 @@ Basic template
 ii. Inner workings
 ------------------
 
-Filters are applied by using events. Basically the `spiriit_form_filter.query_builder_updater` service will trigger a default event named according to the form type to get the condition for a given filter.
-Then once all conditions have been gotten another event will be triggered to add these conditions to the (doctrine) query builder according to the operators defined by the condition builder.
-We provide a event/listener that supports Doctrine ORM, DBAL and MongoDB.
+Filters are applied by using events. Basically the `FilterBuilderUpdater::class` service will trigger a default event named
+according to the form type to get the condition for a given filter.
+
+Then once all conditions have been gotten another event will be triggered to add these conditions to the (doctrine) query 
+builder according to the operators defined by the condition builder.
+
+We provide an event/listener that supports Doctrine ORM, DBAL.
 
 The default event name pattern is `spiriit_form_filter.apply.<query_builder_type>.<form_type_name>`.
 

diff --git a/Resources/doc/configuration.md b/Resources/doc/configuration.md
@@ -4,10 +4,10 @@
 Twig
 ----
 
-You only need to add the following lines in your `app/config/config.yml`. This file contains the template blocks for the filter types.
+You only need to add the following lines in your `config/packages/twig.yaml`. This file contains the template blocks for the filter types.
 
 ```yaml
-# app/config/config.yml
+# config/packages/twig.yaml
 twig:
     form_themes:
         - '@SpiriitFormFilter/Form/form_div_layout.html.twig'
@@ -21,8 +21,10 @@ Bundle's options
 The bundle provides some listener to apply conditions on Doctrine ORM, DBAL and MongoDB query builders.
 By default only Doctrine ORM listeners are enabled.
 
+You can create a file `spiriit_form_filter.yaml`
+
 ```yaml
-# app/config/config.yml
+# config/packages/spiriit_form_filter.yaml
 spiriit_form_filter:
     listeners:
         doctrine_orm: true
@@ -35,7 +37,7 @@ If your RDBMS is Postgres, case insensitivity will be forced for LIKE comparison
 If you want to avoid that, there is a configuration option:
 
 ```yaml
-# app/config/config.yml
+# config/packages/spiriit_form_filter.yaml
 spiriit_form_filter:
     force_case_insensitivity: false
     encoding: ~ # Encoding for case insensitive LIKE comparisons. For example: UTF-8
@@ -53,7 +55,7 @@ If you set it to `null` or `or`, the bundle will use the `where()` or `orWhere()
 And so if the value is `null` it will override the existing where clause (in case of you initialized one on the query builder).
 
 ```yaml
-# app/config/config.yml
+# config/packages/spiriit_form_filter.yaml
 spiriit_form_filter:
     where_method: ~  # null | and | or
 ```
@@ -63,7 +65,7 @@ spiriit_form_filter:
 This option allow you to define the default text pattern the `TextFilterType` will use.
 
 ```yaml
-# app/config/config.yml
+# config/packages/spiriit_form_filter.yaml
 spiriit_form_filter:
     condition_pattern: text.starts
 ```

diff --git a/Resources/doc/filtertypeextension.md b/Resources/doc/filtertypeextension.md
@@ -1,11 +1,13 @@
 [5] The FilterTypeExtension
 ===========================
 
-The bundle loads a custom type extension to add the `apply_filter`,  `data_extraction_method`, and `filter_condition_builder` options to **all form types**. These options are used when a filter condition is applied to the query builder.
+The bundle loads a custom type extension to add the `apply_filter`,`data_extraction_method`, and `filter_condition_builder` options to **all form types**.
+These options are used when a filter condition is applied to the query builder.
 
 ##### The `apply_filter` option:
 
-This option is set to `null` by default and aims to override the default way to apply the filter on the query builder. So you can use it if the default way to apply a filter does match to your needs.
+This option is set to `null` by default and aims to override the default way to apply the filter on the query builder.
+So you can use it if the default way to apply a filter does match to your needs.
 
 You can pass a Closure or a valid callback to this option, here is a simple example:
 
@@ -21,28 +23,29 @@ class CallbackFilterType extends AbstractType
 {
     public function buildForm(FormBuilderInterface $builder, array $options)
     {
-        $builder->add('my_text_field', Filters\TextFilterType::class, array(
-            'apply_filter' => array($this, 'textFieldCallback'),
-        ));
-
-        $builder->add('my_number_field', Filters\NumberFilterType::class, array(
+        $builder->add('my_text_field', Filters\TextFilterType::class, [
+            'apply_filter' => [$this, 'textFieldCallback'],
+        ]);
+    
+        $builder->add('my_number_field', Filters\NumberFilterType::class, [
             'apply_filter' => function(QueryInterface $filterQuery, $field, $values) {
                 if (empty($values['value'])) {
                     return null;
                 }
-
+    
                 $expr = $filterQuery->getExpr();
-
+    
                 $paramName = sprintf('p_%s', str_replace('.', '_', $field));
-
+    
                 return $filterQuery->createCondition(
-                    $expr->eq($field, ':'.$paramName),    // expression
-                    array($paramName => $values['value']) // parameters [ name => value ]
+                    $expr->eq($field, ':' . $paramName),    // expression
+                    [$paramName => $values['value']] // parameters [ name => value ]
                 );
             },
-        ));
+        ]);
     }
 
+
     public function getBlockPrefix()
     {
         return 'item_filter';
@@ -60,7 +63,7 @@ class CallbackFilterType extends AbstractType
 
         return $filterQuery->createCondition(
             $expr->eq($field, ':'.$paramName),    // expression
-            array($paramName => array($values['value'], \PDO::PARAM_STR) // parameters [ name => [value, type] ]
+            [$paramName => [$values['value'], \PDO::PARAM_STR]] // parameters [ name => [value, type] ]
         );
     }
 }
@@ -70,9 +73,9 @@ class CallbackFilterType extends AbstractType
 
 This option replaces the `translaformer_id` option. This option defines the way we extract some data from the form before the filter is applied.
 
-Available extration methods:
+Available extraction methods:
 
-* default: simply get the form data.
+* default: get the form data.
 * text: used with `TextFilterType` and `NumberFilterType` types if you choose to display the combo box of available patterns/operator, it has the data from the combo box and the text field.
 * value_keys: used with `NumberRangeFilterType`, `DateTimeRangeFilterType` and `DateRangeFilterType` types to get values form each form child.
 
@@ -88,22 +91,16 @@ use Spiriit\Bundle\FormFilterBundle\Filter\DataExtractor\Method\DataExtractionMe
 
 class RainbowExtractionMethod implements DataExtractionMethodInterface
 {
-    /**
-     * {@inheritdoc}
-     */
     public function getName()
     {
         return 'rainbow';
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function extract(FormInterface $form)
     {
-        $values = array(
-            'value' => $form->getData(), // The value used to filter, most of time the form value.
-        );
+        $values = [
+            'value' => $form->getData(), // The value used to filter, most time the form value.
+        ];
 
         // add other stuff into $values
 
@@ -135,7 +132,7 @@ public function buildForm(FormBuilderInterface $builder, array $options)
 
 ##### The `filter_condition_builder` option:
 
-This option is used to defined the operator (and/or) to use between each condition.
+This option is used to define the operator (and/or) to use between each condition.
 This option is expected to be closure and recieve one parameter which is an instance of `Spiriit\Bundle\FormFilterBundle\Filter\Condition\ConditionBuilderInterface`.
 
 See [4.iii section](working-with-the-bundle.md#iii-customize-condition-operator) for examples.

diff --git a/Resources/doc/installation.md b/Resources/doc/installation.md
@@ -1,43 +1,10 @@
 [1] Installation
 ================
 
-Add the bundle to your `composer.json` file:
+The bundle can be installed using Composer or the [Symfony binary](https://symfony.com/download):
 
-```javascript
-require: {
-    // ...
-    "spiriitlabs/form-filter-bundle": "~8.0" // check packagist.org for more tags
-    // ...
-}
 ```
-
-Or install directly through composer with:
-
-```
-composer.phar require spiriitlabs/form-filter-bundle ~8.0
-# For latest version
-composer.phar require spiriitlabs/form-filter-bundle dev-master
-```
-
-Then run a composer update:
-
-```shell
-composer.phar update
-# OR
-composer.phar update spiriitlabs/form-filter-bundle # to only update the bundle
+composer require spiriitlabs/form-filter-bundle
 ```
 
-Register the bundle with your kernel:
-
-```php
-    // in AppKernel::registerBundles()
-    $bundles = array(
-        // ...
-        new Spiriit\Bundle\FormFilterBundle\SpiriitFormFilterBundle(),
-        // ...
-    );
-```
-
-***
-
 Next: [2. Configuration](configuration.md)
diff --git a/Resources/doc/working-with-other-bundles.md b/Resources/doc/working-with-other-bundles.md
@@ -64,19 +64,22 @@ ii. PagerFanta example
 // DefaultController.php
 namespace Project\Bundle\SuperBundle\Controller;
 
-use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\Request;
 use Project\Bundle\SuperBundle\Filter\ItemFilterType;
 use Pagerfanta\Doctrine\ORM\QueryAdapter;
 use Pagerfanta\Pagerfanta;
 
-class DefaultController extends Controller
+class DefaultController extends AbstractController
 {
-    public function __construct(private FilterBuilderUpdaterInterface $filterBuilderUpdater)
+    public function __construct(
+        private FilterBuilderUpdaterInterface $filterBuilderUpdater,
+        private FormFactoryInterface $formFactory
+    )
     {
     }
 
-    public function testFilterAction(Request $request)
+    public function __invoke(Request $request)
     {
         $form = $this->formFactory->create(new ItemFilterType());
 
@@ -108,18 +111,4 @@ class DefaultController extends Controller
         ));
     }
 }
-
-// A helper class
-class ListOptions extends AbstractOptions
-{
-    protected function getDefaultsOptions(): array
-    {
-        return [
-            'page' => 1,
-            'limit' => 100,
-            'sorting' => [],
-        ];
-    }
-}
-
 ```