Apache Solr und TYPO3: Eine sehr gute Suche für große Internetseiten

Die normale Suche von TYPO3 durchsucht Titel und Inhalte. Das reicht für kleine Projekte. Aber für sehr große Internetseiten ist diese Suche zu schwach. Vielleicht haben Sie tausende Seiten und Dateien. Dann brauchen Sie eine eigene Technik für die Suche. Apache Solr ist genau diese Technik. Die Erweiterung EXT:solr verbindet Apache Solr sehr gut mit TYPO3.

Dieser Artikel zeigt die Arbeit mit EXT:solr. Wir erklären das neue Modul language-models ab Solr 9.8. Dieses Modul ist für die Vektorsuche zuständig. Wir zeigen Ihnen den Aufbau einer sehr guten Suche.

Inhaltsverzeichnis  

Was EXT:solr macht  

EXT:solr verbindet TYPO3 mit einem Apache Solr Server . Das Programm stellt eine komplette Suche für große Firmen bereit:

Aufbau der Suche  

Das System besteht aus 4 Teilen. Diese Teile arbeiten zusammen:

So funktioniert der Weg der Dokumente:

1. Redakteure erstellen Inhalte in TYPO3.
2. Die Kontrolle bemerkt die Änderung. Sie schreibt einen Eintrag in die Index Queue. Die Index Queue ist eine Warteschlange.
3. Ein Scheduler Task arbeitet die Warteschlange ab. Er sendet die Daten als JSON an den Server von Solr.
4. Das Suchplugin auf der Internetseite fragt den Server von Solr ab. Es zeigt die Ergebnisse an.

Übersicht der Teile  

Kompatibilität der Versionen  

composer require apache-solr-for-typo3/solr:dev-main

Start in unter 10 Minuten  

Installation über Composer  

composer require apache-solr-for-typo3/solr

Lokale Arbeit mit DDEV  

Der schnellste Weg ist das DDEV Addon :

ddev add-on get ddev/ddev-typo3-solr
ddev restart

Sie stellen die Cores in der Datei .ddev/typo3-solr/config.yaml ein. Ein Core ist ein eigener Bereich in Solr:

config: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/solr.xml'
typo3lib: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/typo3lib'
configsets:
  - name: 'ext_solr_13_1_0'
    path: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/configsets/ext_solr_13_1_0'
cores:
  - name: 'core_de'
    schema: 'german/schema.xml'
  - name: 'core_en'
    schema: 'english/schema.xml'

Und in der Datei .ddev/config.yaml erstellen Sie die Cores:

hooks:
  post-start:
    - exec-host: ddev solrctl apply

Docker für den Livebetrieb  

Für den echten Betrieb gibt es ein fertiges Image für Docker . Dieses Image hat fertige Bereiche für alle Sprachen:

services:
  solr:
    image: typo3solr/ext-solr:13.1
    ports:
      - "8983:8983"
    volumes:
      - solr-data:/var/solr
    restart: unless-stopped

volumes:
  solr-data:
    driver: local

Betreutes Hosting  

Sie wollen keinen eigenen Solr Server betreiben? Hier sind zwei Möglichkeiten:

Einstellung der Internetseite in TYPO3  

Fügen Sie die Verbindung in die Datei config.yaml ein:

solr_enabled_read: true
solr_host_read: solr
solr_port_read: '8983'
solr_scheme_read: http
solr_path_read: /
solr_core_read: core_de

Index Queue: Die Warteschlange  

Die Index Queue ist eine Warteschlange. Sie ist sehr wichtig. TYPO3 sendet darüber Inhalte an Solr.

Seiten in den Index aufnehmen  

Das System nimmt Seiten sofort in den Index auf. Sie müssen dafür nichts weiter einstellen. Das Programm liest die Seite und sendet den Text an Solr.

Beliebige Datensätze aufnehmen  

Sie können jede Tabelle aus TYPO3 in den Index aufnehmen. Sie nutzen dafür TypoScript. Hier ist ein Beispiel für Nachrichten:

plugin.tx_solr.index.queue {
    news = 1
    news {
        type = tx_news_domain_model_news

        fields {
            title = title
            abstract = teaser
            author = author

            content = SOLR_CONTENT
            content {
                cObject = COA
                cObject {
                    10 = TEXT
                    10.field = bodytext
                }
            }

            category_stringM = SOLR_RELATION
            category_stringM {
                localField = categories
                multiValue = 1
            }

            url = TEXT
            url {
                typolink.parameter = {$plugin.tx_news.settings.detailPid}
                typolink.additionalParams = &tx_news_pi1[controller]=News&tx_news_pi1[action]=detail&tx_news_pi1[news]={field:uid}
                typolink.additionalParams.insertData = 1
                typolink.returnLast = url
            }
        }
    }
}

Die drei Objekte im Überblick:

Dynamische Felder  

EXT:solr nutzt Endungen für Felder. So können Sie eigene Felder ohne Änderung am Schema anlegen :

Kontrolle  

EXT:solr erkennt Änderungen an Datensätzen. Dafür nutzt es PSR-14 Events. Es gibt zwei Arten:

• Sofort: Das System verarbeitet Änderungen sofort.
• Verzögert: Das System sammelt Änderungen in einer Warteschlange. Ein eigenes Programm arbeitet diese Liste später ab.

Strategie für den Site-Hash  

Eine Einstellung regelt den Site-Hash in den Dokumenten. Für neue Projekte mit TYPO3 13.4 empfehlen wir die Einstellung siteHashStrategy = 1. Bei einer Änderung müssen Sie alles neu in den Index aufnehmen.

Suche einstellen  

Einfache Einstellungen  

plugin.tx_solr {
    enabled = 1
    search {
        targetPage = 42
        initializeWithEmptyQuery = 1
        showResultsOfInitialEmptyQuery = 0
        trustedFields = url
    }
}

Filter und Facetten  

Facetten sind Filter. Sie machen die Suche sehr einfach für den Nutzer :

plugin.tx_solr.search {
    faceting = 1
    faceting {
        facets {
            contentType {
                label = Inhaltstyp
                field = type
            }
            category {
                label = Kategorie
                field = category_stringM
            }
            year {
                label = Jahr
                field = year_intS
                type = queryGroup
                queryGroup {
                    2026.query = [2026-01-01T00:00:00Z TO 2026-12-31T23:59:59Z]
                    2025.query = [2025-01-01T00:00:00Z TO 2025-12-31T23:59:59Z]
                }
            }
        }
    }
}

Verfügbare Arten von Facetten: options, queryGroup, hierarchy, dateRange, numericRange.

Automatische Vorschläge  

plugin.tx_solr {
    suggest = 1
    suggest {
        numberOfSuggestions = 10
        suggestField = spell
        showTopResults = 1
        numberOfTopResults = 5
    }
}

Markierungen und Prüfung auf Fehler  

plugin.tx_solr.search {
    results {
        resultsHighlighting = 1
        resultsHighlighting {
            fragmentSize = 200
            wrap = <mark>|</mark>
        }
    }
    spellchecking = 1
    sorting = 1
}

Vektorsuche und Hybridsuche ab Solr 9.8  

Seit Januar 2025 hat Solr ein neues Modul. Es heißt language-models. Damit ist eine semantische Suche direkt auf dem Solr Server möglich . Das bedeutet: Die Suche versteht den Sinn der Wörter. Sie brauchen dafür keine extra Datenbank für Vektoren.

Das Modul für Sprache  

Normale Suchen finden nur genaue Wörter. Nutzer suchen aber oft mit anderen Wörtern. Die neue Technik löst dieses Problem. Sie wandelt Texte in Vektoren um. Vektoren sind Zahlenreihen. Sie zeigen die Ähnlichkeit von Bedeutungen.

Anbieter für Vektoren (über LangChain4j ):

Gemischte Suche  

Die beste Einstellung mischt zwei Suchen. Sie sucht nach genauen Wörtern. Und sie sucht nach ähnlichen Bedeutungen mit Vektoren:

?q=Kundenbeschwerden Bearbeitung
&rq={!rerank reRankQuery=$rqq reRankDocs=50 reRankWeight=2}
&rqq={!knn_text_to_vector model=openai-embed f=vector topK=50}Kundenbeschwerden Bearbeitung

So erhalten Sie die besten Ergebnisse aus beiden Techniken.

Beispiele für die Nutzung  

Fehler finden in 6 Schritten  

Wenn die Suche nicht geht, liegt der Fehler oft an vier Orten. Das sind Verbindung, Warteschlange, Solr Server oder Ansicht. Gehen Sie mit Plan vor.

Plan zur Diagnose  

Bekannte Fehler und Lösungen  

Protokolle einschalten  

Für eine genaue Fehlersuche schalten Sie das Protokoll ein. Machen Sie das nur beim Entwickeln:

plugin.tx_solr.logging {
    debugOutput = 1
    exceptions = 1
    indexing = 1
    query.rawGet = 1
    query.queryString = 1
}

Und stellen Sie die Datei in config/system/additional.php ein:

$GLOBALS['TYPO3_CONF_VARS']['LOG']['ApacheSolrForTypo3']['Solr']['writerConfiguration'] = [
    \Psr\Log\LogLevel::DEBUG => [
        \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [
            'logFile' => \TYPO3\CMS\Core\Core\Environment::getVarPath() . '/log/solr.log',
        ],
    ],
];

ddev exec tail -f var/log/solr.log

PSR-14 Events für eigene Erweiterungen  

EXT:solr sendet an wichtigen Stellen PSR-14 Events . Sie können diese Events für eigene Programme nutzen.

Eigene Felder anfügen  

<?php

declare(strict_types=1);

namespace MyVendor\MyExt\EventListener;

use ApacheSolrForTypo3\Solr\Event\Indexing\BeforeDocumentsAreIndexedEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener(identifier: 'my-ext/enrich-solr-documents')]
final class EnrichSolrDocuments
{
    public function __invoke(BeforeDocumentsAreIndexedEvent $event): void
    {
        foreach ($event->getDocuments() as $document) {
            $document->addField(
                'custom_score_floatS',
                $this->calculateScore($document)
            );
        }
    }

    private function calculateScore(
        \ApacheSolrForTypo3\Solr\System\Solr\Document\Document $document
    ): float {
        return match ($document->getField('type')['value'] ?? '') {
            'pages' => 1.0,
            'tx_news_domain_model_news' => 0.8,
            default => 0.5,
        };
    }
}

Wichtige Events in der Übersicht  

TYPO3 v14: Änderungen für Entwickler  

Wenn Sie TYPO3 v14 nutzen, gibt es Änderungen:

• Fluid 5.0: Vorlagen für die Suche haben nun strenge Regeln. Prüfen Sie Ihre eigenen Vorlagen.
• TypoScriptFrontendController: Eigene Plugins müssen auf die neue Technik umstellen.
• TCA: Die alte Sucheinstellung entfällt. Nutzen Sie nun 'searchable' => true pro Spalte.

Liste für den Livebetrieb  

Fazit  

EXT:solr macht die Suche in TYPO3 sehr gut. Es bietet Filter, Vorschläge und eine Vektorsuche. Die Erweiterung läuft sehr stabil. Die Firma dkd Internet Service pflegt sie gut. Der Start mit DDEV dauert nur wenige Minuten.

Die 3 wichtigsten Punkte:

1. EXT:solr nimmt alles in den Index auf. Es liest Seiten, Nachrichten und Dateien.
2. Die Vektorsuche läuft auf dem Solr Server. Das Modul language-models bringt die semantische Suche direkt in Solr.
3. Die Einrichtung ist einfach. Sie installieren das DDEV Addon. Sie stellen die Cores ein. Sie erstellen eine Aufgabe. Fertig.

Vielleicht überlegen Sie noch. Reicht die normale Suche? Sobald Sie viele Seiten oder Filter haben, brauchen Sie Solr.