Download the PHP package cywolf/semantic-suggestion-solr without Composer

Semantic Suggestion Solr

TYPO3 extension that displays related content suggestions using Solr. Supports two similarity algorithms: MLT (lexical) and SMLT (semantic hybrid, combining MLT + KNN vector search server-side).

Similarity modes

MLT — More Like This

Solr's built-in MLT compares term frequency (TF-IDF) across configurable fields (title, content, keywords). Fast, no external model needed.

SMLT — Semantic More Like This

A custom Solr SearchComponent that combines classical MLT with KNN vector search server-side in a single Solr request. Normalizes both score sets to [0,1] and merges them:

Default weights: 0.3 MLT / 0.7 vector (configurable per request).

Three internal sub-modes: hybrid (default), vector_only, mlt_only (useful for A/B testing).

Results are returned in a separate semanticMoreLikeThis response section, independent of the main search query.

Auto mode (default)

When similarityMode = auto, the algorithm is chosen automatically based on EXT:solr's TypoScript:

• plugin.tx_solr.search.query.type >= 1 -> SMLT (embeddings are indexed)
• plugin.tx_solr.search.query.type = 0 -> MLT (no vectors available)

How it works

Cross-content-type suggestions

Suggestions can mix pages and news (or any indexed content type). By default, no type filter is applied, so a page about leather sewing machines may suggest both related pages and news articles about leather.

Use the allowedTypes setting (or FlexForm) to restrict suggestions to specific types if needed.

Language handling

EXT:solr maintains one core per site language. The plugin reads the current frontend language from the request and connects to the matching Solr core via ConnectionManager->getConnectionByRootPageId($rootPageId, $languageUid). Results are always in the same language as the current page.

Context detection

The plugin detects the current content type automatically:

• Standard page: lookup by type:pages AND uid:{pageUid}
• News detail (EXT:news): if tx_news_pi1[news] is present in the request, lookup by type:tx_news_domain_model_news AND uid:{newsUid}

Image enrichment

When showImage = 1, the extension resolves the first media file for each suggestion:

• Pages: pages.media field (FAL)
• News: tx_news_domain_model_news.fal_media field (FAL)

Requirements

• TYPO3 13.4+
• EXT:solr 13.0+ with a working index
• For SMLT mode: the SMLT JAR deployed in Solr + embeddings indexed via the textToVector update chain

Installation

Flush TYPO3 caches, then include the extension's static TypoScript in the site template.

SMLT setup (Semantic More Like This)

1. Build and deploy the SMLT JAR

The Java source is in .ddev/typo3-solr/smlt-plugin/. Build with Maven:

Copy the JAR to the Solr typo3lib directory (alongside solr-typo3-plugin-6.0.0.jar):

2. Register the SearchComponent in solrconfig.xml

Add to vendor/.../configsets/ext_solr_13_1_0/conf/solrconfig.xml:

And add <str>smlt</str> to the /select handler's <arr name="last-components">.

3. Set vector field to stored=true

In general_schema_fields.xml, ensure the vector field has stored="true":

4. Enable vector indexing and re-index

Re-initialize the Index Queue and run the scheduler. Each document will be sent to the OpenAI embedding API during indexing.

Note: query.type = 1 also enables native KNN for the frontend search. If KNN doesn't work in your setup, set it back to 0 after re-indexing. The SMLT component works independently — it reads pre-indexed vectors directly, regardless of query.type.

5. Set the similarity mode

Or use auto (default) to let the extension detect query.type automatically.

News indexing

To include news articles in Solr (required for cross-type suggestions), add the index queue configuration in your sitepackage TypoScript:

Then initialize the news index queue and run the Solr indexer.

Usage

As a content element

Insert the plugin "Similar content (Solr)" via the backend. The FlexForm provides per-instance settings:

• Similarity algorithm: Auto, MLT, or SMLT
• Maximum number of suggestions
• Allowed content types (checkboxes: Pages, News — if none checked, all types shown)
• Restrict to pages/storage folders (PID filter)
• Show/hide content type badge
• Show/hide relevance score (also shows the active mode as a badge)
• Show/hide image

In a Fluid template

Via TypoScript (auto-render on all pages)

Then render {semanticSuggestionsSolr -> f:format.raw()} in your page layout.

Use includePageTrees / excludePageTrees to control which page trees show suggestions (see Visibility below).

Configuration

TypoScript constants

All settings under plugin.tx_semanticsuggestionsolr_suggestions.settings.

Similarity algorithm

MLT parameters

SMLT parameters

Relevance filtering

Applies to both MLT and SMLT. Use these to drop weakly-related suggestions.

Visibility

Control which page trees show suggestions. Both settings accept comma-separated parent page UIDs. A page "matches" a tree when the parent UID appears anywhere in its rootline (the page itself or any ancestor). This works identically across all site languages.

Example: show suggestions only in the News section (page 130) and Blog (page 42), but never on the Legal page (135):

Display

FlexForm vs TypoScript

FlexForm settings (per content element) override TypoScript settings for the same keys.

Multi-language support

The extension is fully multi-language aware:

• Solr cores: EXT:solr maintains one core per site language. The plugin reads the current frontend language from the request and connects to the matching core automatically. Results are always in the same language as the current page.
• Visibility settings: includePageTrees / excludePageTrees use page UIDs which are identical across all languages (TYPO3 translations are overlays on the same page records).
• Frontend labels: Translated into English, French, German, Spanish and Italian. Add your own by creating Resources/Private/Language/{iso}.locallang.xlf.

Architecture

SMLT Solr SearchComponent

Solr API parameters:

Solr access chain

Suggestion data structure

Each suggestion returned by the service:

Template customization

Override the template path via TypoScript:

Then create Suggestions/List.html in that directory. Available template variables: {suggestions} (array) and {settings} (merged TypoScript + FlexForm).

License

GPL-2.0-or-later