TYPO3 Plugin:
vdc_search
vdc_search Einrichtung
Diese Readme erklärt, wie Sie die auf der elastischen Suche basierende Suchfunktionalität einrichten, warten und nutzen.
Die Erweiterung funktioniert mit der elasticsearch Version 2.x
Der Worttyp
in dieser Readme ist immer der Dokumententyp der elastischen Suche.
1 Allgemeines
Diese Erweiterung besteht aus 3 verschiedenen Bereichen:
- cli-Befehl
- index-Phase
- suchphase
Die cli-Befehle werden zur Verwaltung des Suchindex verwendet. Während der Indexphase werden konfigurierbare Dokumente analysiert und in den elasticseach index geschrieben. Schließlich akzeptiert die Suchphase eine Suchanfrage, findet die passenden Dokumente und gibt die Suchergebnisse zurück.
2 Konfiguration
Die Konfiguration erfolgt hauptsächlich in den Erweiterungen ext_localconf.php
, mit Ausnahme der allgemeinen elastischen Suche -
dies muss in der .env-Datei
mit den folgenden Variablen konfiguriert werden:
TYPO3__EXTCONF__vdc_search__elastische Suche__index
TYPO3__EXTCONF__vdc_search__elastische Suche__Server__A__Host
TYPO3__EXTCONF__vdc_search__elastische Suche__Server__A_port
TYPO3__EXTCONF__vdc_search__elastische Suche__Einstellungen__Anzahl_der_Splitter
TYPO3__EXTCONF__vdc_search__elastische Suche__Einstellungen__Anzahl_der_Repliken
Die Konfiguration der Erweiterung in ext_localconf.php
erfolgt im Array:
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['vdc_search']['config']]
Dieses Array enthält mehrere Strukturen. Im Detail sind die Strukturen:
2.1 Standardwerte
Diese Struktur enthält die Standardsuchparameter, die verwendet werden, wenn die Suchanfrage nur aus einigen (nicht allen) Werten besteht.
2.2 Doktypen
In dieser Sektion werden die Doktype-Mappings für Finder definiert.
2.3 Highlights
Diese Konfiguration kann verwendet werden, um den Suchmarker einzurichten.
2.4 Raupenfahrwerke
Die Crawler-Struktur ist ein Array, das alle Crawler enthält, die während der Indexphase verwendet werden sollen.
Um jede Art von Datenstruktur zu indizieren, muss ein Eintrag in diesem Array vorhanden sein.
Mit dieser Array-Struktur wird ein Crawler definiert:
news' => (Objekt) [
className' => \Vdc\VdcSearch\Crawler\Type\Type\News::class,
'enabled' => true,
]
Dabei ist der Schlüssel ein eindeutiger Name und der Klassenname zeigt auf eine Klasse, die einen Crawler repräsentiert. Diese Klasse muss das Vdc\VdcSearch\Crawler\Crawler\CrawlerInterface
implementieren.
Es ist am besten, von Vdc\VdcSearch\Crawler\AbstractCrawler
zu erweitern, da dies die Schnittstelle implementiert und einige Komfortmethoden hat, die häufig bei Crawlern verwendet werden
Das enabled Flag kann verwendet werden, um einen Crawler zu aktivieren/deaktivieren.
2.5 Finder
Ein Findereintrag ist vergleichbar mit einem Crawler-Eintrag. Während der Suchphase werden Finder verwendet.
Der einzige obligatorische Schlüssel ist der Klassenname
, der auf eine Klasse zeigt, die die Vdc\VdcSearch\Search\Search\Search\SearchInterface
implementiert. Es ist am besten, von Vdc\VdcSearch\Search\Search\AbstractSearch
zu erweitern, da es die genannte Schnittstelle implementiert. Darüber hinaus hat AbstractSearch
einige Hilfsmethoden für Finder.
Eine Finderkonfiguration kann die folgenden zusätzlichen Schlüssel haben:
2.5.1 Blacklist
Ein Array, das aus den Feldern besteht, die im Suchergebnis nicht zurückgegeben werden dürfen.
2.5.2 Verstärkung
Schlüssel-Wert-Paare, die eine Verstärkung pro Feld definieren.
Felder, die nicht in dieser Liste enthalten sind, erhalten eine Standardanhebung von 1.
Felder in dieser Liste werden bei der Volltextsuche verwendet.
Wenn ein Feld markiert werden muss ([siehe Kapitel 2.5.3 Highlight](#2.5.3 Highlight)), muss es ebenfalls in die Boost-Liste aufgenommen werden.
2.5.3 Hervorhebung
Um die Such-Highlighting-Funktion der elastischen Suche zu nutzen, können Sie die zu markierenden Felder definieren.
news' => (Objekt) [
className' => \Vdc\VdcSearch\Search\Search\Type\News::class,
Blacklist' => [ [
"uid",
"Bodytext",
],
boost' => [ [
Titel' => 3,
bodytext' => 2,
"tx_flexiblenews_teaser" => 1,
"tx_vdcnews_type" => 1,
],
highlight' => [ [
title' => (object) [],
tx_flexiblenews_teaser' => (Objekt) [],
tx_vdcnews_type' => (Objekt) [],
],
]
2.6 Filter, Analysator, Tokenizer, Tokenizer
In diesen Konfigurationselementen können die verfügbaren elastischen Suchfilter/Analysatoren/Tokenizer definiert werden.
Die Syntax ist eine 1:1-Konvertierung von der elasticsearch JSON-Konfiguration in ein PHP-Array.
Diese Konfigurationen werden in der getMapping-Methode
der Crawler referenziert.
siehe auch https://www.elastic.co/guide/en/elasticsearch/guide/current/custom-analyzers.html
3 Hinzufügen neuer Dokumenttypen
Um eine neue Dokumentart anzulegen, müssen Sie einen Crawler und einen Finder implementieren und fügen Sie es der Konfiguration hinzu ([siehe Kapitel 2.4 Crawler](#2.4 Crawler) und[siehe Kapitel 2.5 Finder](#2.5 Finder)).
3.1 einen Crawler implementieren
Ein Crawler muss die folgenden Methoden implementieren:
öffentliche Funktion hasType(): bool;
public function getType(): string;
öffentliche Funktion getMapping(): array;
public function crawl(): array;
Die Crawler-Klasse muss sich im Namensraum Vdc\VdcSearch\Crawler\Type
befinden
Wenn Sie von Vdc\VdcSearch\Crawler\AbstractCrawler
ausgehen, müssen Sie den geschützten $type = "Events"
setzen;
mit einem Wert, der Ihrem Typ entspricht.
3.1.1 hasType
Muss zurückkehren, wenn der Crawler einen Typensatz hat.
Wenn Sie von Vdc\VdcSearch\Crawler\AbstractCrawler\AbstractCrawler
ausgehen, müssen Sie diese Methode nicht implementieren.
3.1.2 getType
Muss die Dokumentart zurückgeben.
Wenn Sie von Vdc\VdcSearch\Crawler\AbstractCrawler\AbstractCrawler
ausgehen, müssen Sie diese Methode nicht implementieren.
3.1.3 getMapping
Muss das Mapping für elasticsearch indexer zurückgeben.
Diese Methode muss ein Array zurückgeben, das das elasticsearch mapping enthält. Die Syntax ist eine 1:1-Konvertierung von der elasticsearch JSON-Konfiguration in ein PHP-Array.
Siehe https://www.elastic.co/guide/en/elasticsearch/guide/current/mapping-intro.html
3.1.4 kriechen
Muss die zu indizierenden Dokumente zurückgeben.
Diese Methode muss ein Array mit der folgenden Struktur zurückgeben:
[documentId] = [ [
taste1 => Wert1,
taste2 => Wert2,
...
]
wobei documentId zur elasticsearch document id wird und die Anordnung der Schlüssel/Wertpaare das zu indexierende Dokument darstellt
3.2 einen Finder implementieren
Ein Finder muss die folgenden Methoden implementieren:
öffentliche Funktion hasType(): bool;
public function getType(): string;
öffentliche Funktion getQuery(\stdClass $query): array;
öffentliche Funktion getFieldBlacklist(): array;
öffentliche Funktion processResultSet(array $resultSet): \stdClass;
öffentliche Funktion getFilter(\stdClass $search): array;
öffentliche Funktion getHighlight(): array;
Die Crawler-Klasse muss sich im Namensraum Vdc\VdcSearch\Search\Search\Type
befinden
Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch
ausgehen, müssen Sie geschützten $type = "Events"
setzen;
mit einem Wert, der Ihrem Typ entspricht.
3.2.1 hasType
Muss zurückkehren, wenn der Finder eine Dokumentart hat.
Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch
ausgehen, müssen Sie diese Methode nicht implementieren.
3.2.2 getType
Muss die Dokumentart zurückgeben.
Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch
ausgehen, müssen Sie diese Methode nicht implementieren.
3.2.3 getQuery
Muss die Abfrage nach elasticsearch zurückgeben.
Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch
ausgehen, müssen Sie diese Methode nicht implementieren.
3.2.4 getFieldBlacklist
Muss ein Array von Feldnamen zurückgeben, die bei der Abfrage nicht zurückgegeben werden dürfen
Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch
ausgehen, müssen Sie diese Methode nicht implementieren.
Die Daten werden aus der Finderkonfiguration abgerufen ([siehe Kapitel 2.5.1 Blacklist](#2.5.1 Blacklist))
3.2.5 ProzessErgebnisSatz
Muss ein Objekt mit Eigenschaften zurückgeben:
- treffer: Anzahl der gefundenen Dokumente
- dokumente: gefundene Dokumente
Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch
ausgehen, müssen Sie diese Methode nicht implementieren.
3.2.6 getFilter
Muss die Filter zurückgeben, die bei einer Abfrage verwendet werden sollen.
Auch wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch
ausgehen, müssen Sie diese Methode implementieren.
Dieses Verfahren muss ein Array zurückgeben, das den elastischen Suchfilter definiert, der bei der Abfrage des Index verwendet werden soll.
Die Syntax ist eine 1:1-Konvertierung von der elasticsearch JSON-Konfiguration in ein PHP-Array.
Siehe https://www.elastic.co/guide/en/elasticsearch/guide/current/combining-filters.html
3.2.7 getHighlight
Muss die Markierungsfelder zurückgeben, die bei einer Abfrage verwendet werden sollen
Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch
ausgehen, müssen Sie diese Methode nicht implementieren.
Die Daten werden aus der Sucherkonfiguration abgerufen ([siehe Kapitel 2.5.3 Highlight](#2.5.3 Highlight))
4 Client-Befehle
Die Erweiterung bietet einen komfortablen Befehl für die Verwendung mit der typo3cms Client-Konsole:
- suche:deleteindex
- search:indexall
- suche:rebuildall
- search:setupindex
4.1 Suche:deleteindex
Löscht den Index und alle darin abgelegten Dokumente.
4.2 Suche:setupindex
Erstellt und initialisiert die Mappings und Einstellungen des elasticsearch index.
4.3 Suchen:indexall
Schleifen über alle aktivierten Crawler, die in der Erweiterung konfiguriert sind.
Für jeden Crawler wird die Crawl-Methode
aufgerufen und die zurückgegebenen Dokumente werden in den elasticsearch index geschrieben.
4.4 suchen:rebuildall
Dies ist ein Wrapper-Aufruf an:
- löschen
- erstellen
- indexall
5 Suchen nach Dokumenten
Die Suche nach Dokumenten erfolgt über einen HTTP POST-Aufruf an /index.php?type=1488360328
Um den Master zu verwenden, müssen Sie einen Proxy zu Ihrer nginx-Konfiguration hinzufügen:
standort /Suche/ { {
proxy_pass http://master.vdc-fellbach.de.dev0.itplusx.de/index.php?type=1488360328;
}
Der POST-Body muss eine JSON-Zeichenkette haben, die wie folgt aussieht:
5.1 minimaler Suchbegriff
{
" Typ": " Neuigkeiten"
}
Es muss nur die Dokumentart definiert werden (dies ist obligatorisch). Das Ergebnis ist eine Liste aller Dokumente im Index, die dem angegebenen Typ entsprechen.
5.2 maximale Suchbegriffe
{
" Typ": " Neuigkeiten",
" Abfrage": " Palette",
" Größe": 10,
"von": 0,
" Lang": "de",
" Sortieren": {
" Verabredung": "Abstieg",
" Titel": " Aufstieg"
},
"Filter": {
" Typen": [1,2],
" Kategorien": [
[52, 26],
[163, 132]
],
"von": "07.12.17",
"Bis": "08.12.17"
}
}
Ein vollständiger Suchbegriff besteht aus mehreren Teilen, die in den folgenden Kapiteln erläutert werden.
5.2.1 Abfrage
Dieser Parameter kann einen Suchbegriff für die Volltextsuche enthalten.
Die zu durchsuchenden Felder werden in der Einstellung Finder / Boost konfiguriert ([siehe Kapitel 2.5.2 Boost](#2.5.2 Boost)))
5.2.2 Größe
Mit dem Größenparameter können Sie die maximale Anzahl der Treffer konfigurieren, die zurückgegeben werden sollen.
5.2,3 von
Der Parameter from definiert den Offset vom ersten Ergebnis, das Sie holen möchten.
5.2.4 lang
noch nicht implementiert
Der Parameter lang legt die Sprache für die zu durchsuchenden Dokumente fest.
5.2.5 Sortierung
Sort ist eine Liste von Schlüssel/Wertpaaren, die die Sortierung des Suchergebnisses definieren.
Der erste Parameter ist das zu sortierende Feld, der zweite ist die Sortierrichtung.
5.2.6 filter
Die Filterstruktur kann zum Filtern des Suchergebnisses verwendet werden.
Zur Zeit können folgende Felder gefiltert werden
- typen
- kategorien
- datumsbereich (nur für Ereignisse)
5.2.6.1 typen
Der Typ-Filter ist ein Array von Typ-IDs.
Es werden nur die Dokumente zurückgegeben, die einem der definierten Typen entsprechen.
5.2.6.2 Kategorien
Der Kategorienfilter ist ein Array von Arrays mit der folgenden Logik.
Die im inneren Array definierten Werte werden durch ein logisches ODER verknüpft, dann werden diese durch ein logisches UND verknüpft.
Werfen Sie einen Blick auf dieses Beispiel:
" Kategorien": [
[52, 26],
[163, 132]
]
Dies führt zu Dokumenten mit Kategorie-ID:
(52 ODER 26) UND (163 ODER 132)
5.2.6.3 Datumsbereich
Der Datumsbereichsfilter ist derzeit nur für den Typ "Events" implementiert.
Es besteht aus zwei Zeichenkettenfeldern "von" und "bis", die jeweils ein Datum im Format d.m.y halten
Es muss mindestens einer der Datumsbereichsfilter gesetzt sein.
Die Suche liefert Dokumente, die jünger als das Feld "von" und / oder älter als das Feld "bis" sind.
5.3 Ergebnisdatenstruktur
Die Suche gibt einen JSON-String zurück, der aus zwei Teilen besteht:
- meta
- ergebnisse
5.3.1 meta
Die Metadaten zeigen zusätzliche Informationen zum Suchergebnis:
- typ: der bei der Suche verwendete Typ
- query: die Abfragestruktur
- lang: die Sprache
- treffer: Gesamtzahl der gefundenen Dokumente
- anzeige: Anzahl der zurückgegebenen Dokumente
- mehr: Flag, das anzeigt, dass mehr Dokumente abgerufen werden können
- größe: Anzahl der zurückzugebenden Dokumente
- von: Paging-Start
- sortierung: Sortierung angewendet
5.3.2 ergebnisse
Die Ergebnisse enthalten die resultierenden Dokumente aus der letzten Suche.
Benötigen Sie schnelle Hilfe mit dieser Extension? Unser Team von erfahrenen TYPO3-Entwicklern löst Probleme unkompliziert und zum Stundensatz.
[DependciesAndConflicts]