b2pweb/bdf-form-filter-prime

Helper library for BDF Form to create Prime filters

v1.2.2 2024-02-26 15:08 UTC

Requires

• php: ~7.1 || ~8.0.0 || ~8.1.0 || ~8.2.0 || ~8.3.0
• b2pweb/bdf-form: ~1.0
• b2pweb/bdf-prime: ~1.0|~2.0

Requires (Dev)

• giggsey/libphonenumber-for-php: ~8.0
• phpunit/phpunit: ~7.0|~8.0|~9.0
• vimeo/psalm: ~4.4

MIT

• Vincent Quatrevieux

README

Helper library for BDF Form to create Prime filters.

See :

• BDF Form
• Prime

Installation using composer

composer require b2pweb/bdf-form-filter-prime

Basic usage

To create a form filter, simply extends the class FilterForm and implements method FilterForm::configureFilters() :

<?php

namespace App\Form;

use Bdf\Form\Filter\FilterForm;
use Bdf\Form\Filter\FilterFormBuilder;

class MyFilters extends FilterForm
{
    public function configureFilters(FilterFormBuilder $builder): void
    {
        // Build filter fields
        // Will add a "foo LIKE xxx%"
        $builder->searchBegins('foo');

        // Will add a "age BETWEEN ? AND ?"
        $builder->embedded('age', function ($builder) {
            $builder->integer('0')->setter();
            $builder->integer('1')->setter();
        })->between();
        
        // Define a custom attribute name and operator
        $builder->string('foo')->criterion('bar')->operator('>=');
    }
}

Now, you can submit data to the form, apply filters to the query :

<?php

// Instantiate the form (a container can be use for handle dependency injection)
$form = new MyFilters();

// Submit form
// Note: if some constraints has been added, call `$form->valid()` and `$form->error()` to check errors
$form->submit($request->query->all());

// Get generated criteria
$criteria = $form->value();

// Call prime with criteria
$list = MyEntity::where($criteria->all())->paginate();

Query helpers

Two helpers methods are available to handle Prime query without use directly the Criteria object :

• FilterForm::apply() will apply the filters to the query instance
• FirstForm::query() will create the query with filters

<?php

namespace App\Form;

use Bdf\Form\Filter\FilterForm;
use Bdf\Form\Filter\FilterFormBuilder;

class MyFilters extends FilterForm
{
    public function configureFilters(FilterFormBuilder $builder): void
    {
        // Set the entity class (note: use $this instead of $builder)
        $this->setEntity(Person::class);

        // Define filters
        $builder->searchBegins('firstName');
        $builder->searchBegins('lastName');
        $builder->embedded('age', function ($builder) {
            $builder->integer('0')->setter();
            $builder->integer('1')->setter();
        })->between();
    }
}

To use the helpers methods, it's necessary to inject the Prime's ServiceLocator instance on the constructor.

<?php

// Get the form instance, using a container to inject prime
$form = $container->get(MyFilters::class);

// Submit form
$form->submit($request->query->all());

// Use apply to modify the query
$query = Person::builder();
$entities = $form->apply($query)->all(); // Apply filters and execute query

// Use directly query() method to create the filter query
$entities = $form->query();

Usage with mongodb

This library also supports Prime MongoDB filter. It requires b2pweb/bdf-prime-mongodb version 2.0. To use, simply use Bdf\Form\Filter\MongoFilterForm instead of Bdf\Form\Filter\FilterForm, and change $form->setEntity(...) to $form->setDocument().

<?php

namespace App\Form;

use Bdf\Form\Filter\MongoFilterForm;
use Bdf\Form\Filter\FilterFormBuilder;

class MyFilters extends MongoFilterForm
{
    public function configureFilters(FilterFormBuilder $builder): void
    {
        // Set the document class (note: use $this instead of $builder)
        $this->setEntity(Person::class);

        // Define filters
        $builder->searchBegins('firstName');
        $builder->searchBegins('lastName');
        $builder->embedded('age', function ($builder) {
            $builder->integer('0')->setter();
            $builder->integer('1')->setter();
        })->between();
    }
}

The usage is identical to basic prime entity usage.