README

Please note that this extension is still in the alpha phase! Until version 1.0, there will be fundamental changes even with minor updates and patch updates. If you really want to use this extension, you should pin the version at patch level.

This extension integrates meilisearch into your TYPO3.

Requirements

TYPO3 ^12.4
PHP ^8.2

Installation

Use composer to add the extension to your project.

composer require psvneo/typo3-extension-meilisearch

You can also download the extension from the TER here.

Setup / Configuration

Add the following to the site settings.yaml where you want to use meilisearch.

meilisearch:
    # Search result - Attributes to highlight.
    attributesToHighlight: [ '*' ]
    # Search result - Attributes to crop.
    attributesToCrop: [ 'title:1', 'searchContent:5' ]
    # URL to your meilisearch service.
    serviceUrl: http://localhost:7700
    # Search API Key. Please use a readonly key here!
    searchApiKey: '%env(MEILISEARCH_SEARCH_APIKEY)%'
    # Admin API Key. This key is used to index yur data.
    adminApiKey: '%env(MEILISEARCH_ADMIN_APIKEY)%'
    # Define the index columns for pages and tt_content.
    pageIndexer:
        pageIndexColumns:
            - title
            - seo_title
            - keywords
            - abstract
            - description
        contentIndexColumns:
            - header
            - bodytext
            - subheader

How to index

This command will execute every indexer found by the system.

vendor/bin/typo3 meilisearch:index MY_SITE_IDENTIFIER

To also flush the index before indexing new run:

vendor/bin/typo3 meilisearch:index MY_SITE_IDENTIFIER -f

How to create your own indexer

Indexers are automatically collected via dependency injection. The extension uses a CompilerPass to automatically register indexers, so you don't need to register them manually. You only need to ensure your indexer is available as a service.

To create an indexer you can:

implement \PSVNEO\Meilisearch\Domain\Indexer\IndexerInterface or
extend from \PSVNEO\Meilisearch\Domain\Indexer\AbstractIndexer (recommended).

Create your own indexer extending the AbstractIndexer class (recommended)

declare(strict_types=1);

namespace Vendor\ExtensionName\Domain\Indexer;

use PSVNEO\Meilisearch\Domain\Indexer\AbstractIndexer;
use TYPO3\CMS\Core\Site\Entity\Site;

final class XyzIndexer extends AbstractIndexer
{
    public function getType(): string
    {
        return 'tx_myextension_xyz';
    }

    public function collectDocuments(Site $site): array
    {
        $rows = $this->getQueryBuilder('tx_myextension_domain_model_xyz')
            ->select('*')
            ->from('tx_myextension_domain_model_xyz')
            ->executeQuery()
            ->fetchAllAssociative();
        // We need to add a prefix to the uid field to make sure we have a unique uids among the other types.
        return array_map(fn($row) => array_merge($row, ['uid' => $this->prefixUid((string) $row['uid'])]), $rows);
    }
}

The AbstractIndexer provides sensible defaults for getPrimaryKeyName(), getFilterableAttributes(), and getFacetingAttributes() methods, as well as the getQueryBuilder() method for database queries and prefixUid() for creating unique document identifiers.

Available CLI Commands

# Index management
vendor/bin/typo3 meilisearch:index SITE_IDENTIFIER [-f|--flush]
vendor/bin/typo3 meilisearch:indexes

# Document management
vendor/bin/typo3 meilisearch:documents INDEX_NAME [--count]

# Search testing
vendor/bin/typo3 meilisearch:search QUERY [--index=INDEX_NAME]

# Service information
vendor/bin/typo3 meilisearch:version
vendor/bin/typo3 meilisearch:stats
vendor/bin/typo3 meilisearch:keys

Frontend Integration

The extension provides JavaScript components for frontend search:

InstantSearch.js: Ready-to-use search widgets
Vue.js components: For Vue-based applications
Search widget: Configurable search component

Templates are located in Resources/Private/Templates/Search/.

Proxy Architecture

The frontend communicates with Meilisearch through a backend proxy (MeilisearchProxyMiddleware) to avoid exposing API keys in the browser. This middleware intercepts requests to /meilisearch-proxy and forwards them to your Meilisearch instance with proper authentication.

Middleware Registration

The proxy middleware is automatically registered in Configuration/RequestMiddlewares.php:

<?php

declare(strict_types=1);

use PSVNEO\Meilisearch\Middleware\MeilisearchProxyMiddleware;

return [
    'frontend' => [
        MeilisearchProxyMiddleware::IDENTIFIER => [
            'target' => MeilisearchProxyMiddleware::class,
            'before' => ['typo3/cms-frontend/timetracker'],
        ],
    ],
];


## Development

Use the provided composer scripts for development:

Install dependencies

composer install

Linting (individual commands)

composer lint:php # Lint PHP code using phplint composer lint:cs # Lint code style using php-cs-fixer composer lint:ec # Lint editorconfig using editorconfig-cli composer lint:t3s # Scan for TYPO3 compatibility issues composer lint:typoscript # Lint TypoScript code composer lint:debug # Search for debug statements composer lint:yaml # Lint YAML files composer lint # Run all linting checks

Code fixing

composer fix:cs # Fix code style using php-cs-fixer composer fix:ec # Fix editorconfig issues composer fix # Run all fixing commands

Quality analysis

composer qa:analyze # Run PHPStan analysis composer qa:phpmd # Run PHPMD analysis composer qa # Run all quality analysis

Refactoring

composer refactoring:rector1 # Refactor using Rector v1 composer refactoring:fractor # Refactor using Fractor composer refactoring # Run all refactoring tools

Testing

composer test:unit # Run unit tests composer test:functional # Run functional tests composer test:e2e # Run end-to-end tests with Cypress

Building

composer build # Build extension using Docker container


## License

This extension is licensed under GPL-2.0-or-later.

psvneo / typo3-extension-meilisearch

Maintainers

Details