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 ^14.1
• 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:
    searchResult:
        # Search result - Attributes to highlight.
        attributesToHighlight: [ '*' ]
        # Search result - Attributes to crop.
        attributesToCrop: [ 'title:1', 'searchContent:5' ]
    api:
        # 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)%'
    pageIndexer:
        # Define the index columns for pages.
        pageIndexColumns:
            - title
            - seo_title
            - keywords
            - abstract
            - description
        # Define the index columns for tt_content.
        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

# Indexing
vendor/bin/typo3 meilisearch:index SITE_IDENTIFIER [-f|--flush-index]

# Index management
vendor/bin/typo3 meilisearch:indexes SITE_IDENTIFIER [-l|--list-indexes]
vendor/bin/typo3 meilisearch:indexes SITE_IDENTIFIER [-g|--get-index=INDEX_UID]
vendor/bin/typo3 meilisearch:indexes SITE_IDENTIFIER [-d|--delete-index=INDEX_UID]
vendor/bin/typo3 meilisearch:indexes SITE_IDENTIFIER [--delete-all-indexes]

# Document management
vendor/bin/typo3 meilisearch:documents SITE_IDENTIFIER [-a|--action=GET|DELETE] [-i|--index=INDEX_UID] [-d|--document=DOC_ID] [-o|--offset=N] [-l|--limit=N]

# Search testing
vendor/bin/typo3 meilisearch:search SITE_IDENTIFIER SEARCHTERM [-i|--index=INDEX_UID]

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

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:rector   # Refactor using Rector
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.