README

Versions and branches

Overview

The SearchFilter plugin is a powerful and flexible solution for implementing advanced search functionality in CakePHP applications. It provides a robust set of tools for creating dynamic, user-friendly search interfaces with minimal effort.

Features

Dynamic filter generation based on database schema
Support for various filter types: string, numeric, date, datetime, boolean, and lookup (autocomplete)
Customizable filter conditions (equals, not equals, greater than, less than, between, etc.)
Vue.js based frontend for an interactive user experience
AJAX-powered autocomplete functionality for lookup filters
Easy integration with CakePHP's ORM for efficient query building
Extensible architecture allowing for custom filter types and conditions

Installation

You can install this plugin into your CakePHP application using composer:

composer require cakedc/search-filter

Then, add the following line to your application's src/Application.php file:

$this->addPlugin('CakeDC.SearchFilter');

Configuration

Basic Usage

Controller

In your controller, you can set up the search functionality like this:

use CakeDC\SearchFilter\Manager;

class PostsController extends AppController
{
    public function index()
    {
        $query = $this->Posts->find();

        $manager = new Manager($this->request);
        $collection = $manager->newCollection();

        // Add a general search filter
        $collection->add('search', $manager->filters()
            ->new('string')
            ->setConditions(new \stdClass())
            ->setLabel('Search...')
        );

        // Add a complex name filter that searches across multiple fields
        $collection->add('name', $manager->filters()
            ->new('string')
            ->setLabel('Name')
            ->setCriterion(
                $manager->criterion()->or([
                    $manager->buildCriterion('title', 'string', $this->Posts),
                    $manager->buildCriterion('body', 'string', $this->Posts),
                    $manager->buildCriterion('author', 'string', $this->Posts),
                ])
            )
        );

        // Add a datetime filter for the 'created' field
        $collection->add('created', $manager->filters()
            ->new('datetime')
            ->setLabel('Created')
            ->setCriterion($manager->buildCriterion('created', 'datetime', $this->Posts))
        );

        // Automatically add filters based on the table schema
        $manager->appendFromSchema($collection, $this->Posts);

        // Get the view configuration for the filters
        $viewFields = $collection->getViewConfig();
        $this->set('viewFields', $viewFields);

        // Apply filters if search parameters are present in the request
        if (!empty($this->getRequest()->getQuery()) && !empty($this->getRequest()->getQuery('f'))) {
            $search = $manager->formatSearchData();
            $this->set('values', $search);

            // Add a custom 'multiple' filter using the CriteriaFilter
            $this->Posts->addFilter('multiple', [
                'className' => 'CakeDC/SearchFilter.Criteria',
                'criteria' => $collection->getCriteria(),
            ]);

            $filters = $manager->formatFinders($search);
            $query = $query->find('filters', params: $filters);
        }

        // Paginate the results
        $posts = $this->paginate($this->Filter->prg($query));
        $this->set(compact('posts'));
    }
}

This example demonstrates several key features of the SearchFilter plugin:

Creating a new Manager instance and filter collection.
Adding a general search filter that can be used for quick searches.
Creating a complex filter that searches across multiple fields using OrCriterion.
Adding a datetime filter for a specific field.
Automatically generating filters based on the table schema.
Applying filters when search parameters are present in the request.
Using the CriteriaFilter for handling multiple filter criteria.

View

In your view, you can render the search component inside search form like this:

<?= $this->element('CakeDC/SearchFilter.Search/v_search'); ?>

<script>
    window._search.createMyApp(window._search.rootElemId)
</script>

Advanced Usage

Custom Filter Types

Custom Range Filter implementation and integration

Frontend Customization

The plugin uses Vue.js for the frontend. You can customize the look and feel by overriding the templates in your application:

Copy the templates/element/Search/v_templates.php file from the plugin to your application's templates/element/Search/ directory.
Modify the templates as needed.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This plugin is licensed under the MIT License.

cakedc / search-filter

Maintainers

Details