Effortless Search Integration
for Symfony Projects

Install the bundle via Composer:

composer require mezcalito/ux-search

If you're not using Symfony Flex, you'll need to manually register the bundle in config/bundles.php:

// config/bundles.php
return [
    // ...
    Mezcalito\UxSearchBundle\MezcalitoUxSearchBundle::class => ['all' => true],
];

Quick Start

1. Configure an Adapter

Create a configuration file config/packages/mezcalito_ux_search.yaml:

mezcalito_ux_search:
    default_adapter: 'default'
    adapters:
        default: '%env(MEZCALITO_UX_SEARCH_DEFAULT_DSN)%'

Add the DSN to your .env file (choose one):

# For Algolia
MEZCALITO_UX_SEARCH_DEFAULT_DSN=algolia://YOUR_API_KEY@YOUR_APP_ID

# For Meilisearch
MEZCALITO_UX_SEARCH_DEFAULT_DSN=meilisearch://YOUR_MASTER_KEY@localhost:7700

# For Doctrine ORM
MEZCALITO_UX_SEARCH_DEFAULT_DSN=doctrine://default

2. Create Your First Search

Use the maker command to generate a search class:

php bin/console make:search

The command will ask you for:

• Index name: For Algolia/Meilisearch, the index name. For Doctrine, the entity FQCN (e.g., App\Entity\Product)
• Search name (optional): Custom name for your search (defaults to class name without "Search" suffix)
• Adapter (optional): Which adapter to use (defaults to default_adapter)

This creates a search class in src/Search/ that you can customize.

3. Render the Search in Your Template

In any Twig template:

{# Using Twig component syntax #}
<twig:Mezcalito:UxSearch:Layout name="product"/>

{# Or using component function #}
{{ component('Mezcalito:UxSearch:Layout', { name: 'product' }) }}

That's it! You now have a working search with facets, pagination, and live updates. 🎉

Choosing an Adapter

Three adapters are available, each with different strengths:

Adapter DSN Format

Need another provider? You can create your own adapter.

Customizing Your Search

Adding Facets, Sorting, and More

Once you've created a search class, customize it by editing the build() method:

use Mezcalito\UxSearchBundle\Search\AbstractSearch;
use Mezcalito\UxSearchBundle\Attribute\AsSearch;
use Mezcalito\UxSearchBundle\Twig\Components\Facet\RangeInput;

#[AsSearch(index: 'products', adapter: 'default')]
class ProductSearch extends AbstractSearch
{
    public function build(array $options = []): void
    {
        // Add facets for filtering
        $this->addFacet('brand', 'Brand');
        $this->addFacet('category', 'Category');
        $this->addFacet('price', 'Price', RangeInput::class);

        // Add sorting options
        $this->addAvailableSort('name', 'Name');
        $this->addAvailableSort('price', 'Price');
        $this->addAvailableSort('created_at', 'Newest');

        // Configure pagination
        $this->setAvailableHitsPerPage([12, 24, 48]);

        // Adapter-specific parameters
        $this->setAdapterParameters([
            // Adapter-specific options here
        ]);
    }
}

📖 Full customization guide

Customizing the UI

The bundle provides a complete set of UI components that you can use individually or override:

Core Components

Facet Components

Utility Components

Overriding Templates

You can override any component template by creating a file in your app's templates/ directory:

templates/
└── components/
    └── Mezcalito/
        └── UxSearch/
            ├── Layout.html.twig          # Override the main layout
            ├── SearchInput.html.twig     # Override search input
            ├── Hits.html.twig            # Override results display
            └── Facet/
                └── RefinementList.html.twig

Custom Hit Template

The most common customization is the hit (result item) template. Override Hits.html.twig:

{# templates/components/Mezcalito/UxSearch/Hits.html.twig #}
<div {{ attributes }}>
    {% for hit in this.resultSet.hits %}
        <article class="product-card">
            <img src="{{ hit.image }}" alt="{{ hit.name }}">
            <h3>{{ hit.name }}</h3>
            <p class="price">{{ hit.price|format_currency('EUR') }}</p>
            <a href="{{ path('product_show', {id: hit.id}) }}">View details</a>
        </article>
    {% endfor %}
</div>

Advanced Usage

Event System

Customize search behavior with event subscribers:

use Mezcalito\UxSearchBundle\Event\PreSearchEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class SearchSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            PreSearchEvent::class => 'onPreSearch',
        ];
    }

    public function onPreSearch(PreSearchEvent $event): void
    {
        $query = $event->getQuery();
        // Modify the query before search execution
        $query->addFilter('status', 'published');
    }
}

📖 Event system documentation

Multiple Search Configurations

You can have multiple search configurations in one application:

// Product search with Algolia
#[AsSearch(index: 'products', adapter: 'algolia')]
class ProductSearc