Download the PHP package danilovl/select-autocompleter-bundle without Composer

SelectAutocompleterBundle

About

This is a Symfony bundle which enables the popular Select2 component to be used as a drop-in replacement for a standard fields on a Symfony form.

The main feature of this bundle is that the list of choices is retrieved via a remote ajax call.

Requirements

• PHP 8.3 or higher
• Symfony 7.0 or higher

1. Installation

Install danilovl/select-autocompleter-bundle package by Composer:

2. Configuration

After installing the bundle, add this route to your routing:

System default options for all autocompleters, which will be used if necessary.

List of available options which you can change in you project.

This options will be applied for all autocompleters. For example:

3. Customization default options for all autcompleters

3.1 Widget

By default only one widget select2_v4 is available.

3.2 Cdn

If you want to add default select2.min.js, select2.min.css and i18n.js files on page.

Links are defined in default.yaml.

Or you can choose a specific script if, for example, you already have some scripts available on the page.

Or you can define you own path for script and css files.

3.3 Select options

For customization select is available following settings.

Text defined in placeholder will be translated by twig function truns.

3.4 toString

Simple __toString format.

If to_string option is auto then __toString() method was called by Class.

3.5 Where

Simple where condition.

Generated SQL query.

3.6 Order by

Order result by.

Generated SQL query.

4. Configuring autocompleters

For Doctrine ORM you should use key orm. For Doctrine ODM you should use key odm.

The configuration is practically no different for orm or odm.

4.1. ORM autocompleters

4.1.1 Simple configuration

Simple configuration.

Identifier name will be duplicated with prefix type orm. or odm., which can be used for identification autocompleters in forms.

4.1.2 Simple search

start is LIKE 'search%'

any is LIKE '%search%'

end is LIKE 'search%'

equal is = 'search'

4.1.3 Custom search pattern

You can defined custom search pattern. Symbol % in yaml must be duplicate - %%.

You must use key word $search to insert search text into a pattern.

4.1.4 toString

If to_string option auto is true, then __toString() method will be called by Class.

You could defined custom __toString() format, sprintf function will be called.

For each variables in properties, function (string) will be called.

Symbol % in yaml must be duplicate - %%.

4.1.5 Result ordering

You can add ordering.

4.1.6 Call repository method

If you want to use a existing repository method from you project. Other parameters will be ignored.

Repository method should have public access and return QueryBuilder or Builder.

For entity App:Product will be found Repository, then method createSearchQueryBuilder will be called with AutocompleterQuery and Config as a parameters.

This means that all the search logic will be processing by the method which you defined.

4.1.7 Overriding default_option

You can override default_option for specific autocompleter.

5. Security

5.1 By roles

You could restrict access to autcompleter by user roles.

Restrict access for all autocompleters.

You can user condition or or and

If the user has no role ROLE_USER or ROLE_ADMIN, voter return false

If the user has at least one of ROLE_USER or ROLE_ADMIN, voter return true

Restrict access for some specific autocompleter.

5.2 By URL patterns

You could restrict access to autocompleters by securing URL patterns

5.3 By voter

You could create you own voter for autcompleters.

Register new voter as a service.

Set voter for all autocompleters.

Set voter for some specific autocompleter.

5.4 Use isGranted method in custom autocompleter.

6. Dependent select

Sometimes you need options of a select will be loaded/refreshed by ajax based on selection of another select.

6.1 OnyToMany

For example entity - City dependent on Country and Region.

parent_property is the name of the variable in dependent class.

Parent and dependent fields should be in form together.

parent_field - name of master field in your FormBuilder.

6.2 Simple ManyToMany

For example entity - Tag has many Cheque

6.3 Complicated ManyToMany

For example entity - Work dependent on Firm through custom entity FirmWork

7. Route

7.1 Redefine global route

You can redefine global autocomleter route and add some extra route parameters.

7.2 Redefine autocompleter route

You can redefine specific autocomleter route and add some extra route parameters.

8. Usage

Simple configuration in form.

You should use 'name' => 'orm.shop' for identification autocompleter.

You can override select_option.

If you need multi select than use MultipleAutocompleterType

9. Custom Autocompleter

9.1 Config method

You can create your own custom autocompleter.

If the standard functionality is not enough, or you want to reuse you existing code.

If you need additional parameters in request you can define extra parameter which will be available in AutocompleterQuery.

Example url: select-autocomplete/orm.customShop/autocomplete?extra[language]=en.

Then you must define new autocompleter service in you services.yaml with danilovl_select_autocompleter.autocompleter tag and alias name.

9.2 Attribute tag method(more preferable, less code in config)

You can use autocompleter attribute AsAutocompleter with require alias field.

Or you can use symfony service attribute AutoconfigureTag with require name and alias parameters.

10. Custom autocompleter widget template

Create you own custom autocompleter template which extends versions.html.twig and redefine the blocks you need.

Then you need to add path for new custom template to config.

For all autocompleters.

Or for some specific autocompleter.

License

The SelectAutocompleterBundle is open-sourced software licensed under the MIT license.