typo3-solr

Apache Solr for TYPO3

Source: https://github.com/dirnbauer/webconsulting-skills

Compatibility: Target TYPO3 14.3 and match EXT:solr, server and configset using the official Version Matrix and actual package metadata. Stable EXT:solr 14 is available; recheck compatible stable releases at execution time. All custom PHP examples use TYPO3 v14 conventions (PHP 8.2+, constructor promotion, #[AsEventListener] where shown).

TYPO3 API First: Always use TYPO3's built-in APIs and EXT:solr's TypoScript/PSR-14 events before creating custom implementations. Do not reinvent what EXT:solr already provides.

Sources

This skill is based on the following authoritative sources:

1. Architecture Overview

EXT:solr connects TYPO3 CMS to an Apache Solr search server for full-text search, facets and autocomplete. Treat vector/semantic features as a separate version- and configuration-specific integration; server support alone does not mean the TYPO3 plugin enables them.

graph LR
    subgraph typo3 [TYPO3 CMS]
        Editor[Editor creates/edits content]
        Monitor[Monitoring detects changes]
        Queue[Index Queue]
        Scheduler[Scheduler Worker]
        Plugin[Search Plugin]
    end
    subgraph solr [Apache Solr Server]
        Core[Solr Core]
        Schema[Schema / Configset]
    end
    Editor --> Monitor
    Monitor --> Queue
    Queue --> Scheduler
    Scheduler -->|HTTP POST documents| Core
    Plugin -->|HTTP GET query| Core
    Core --> Plugin

Document Lifecycle

sequenceDiagram
    participant E as Editor
    participant T as TYPO3
    participant M as Monitor
    participant Q as Index Queue
    participant S as Scheduler
    participant Solr as Solr Server

    E->>T: Create/edit record
    T->>M: DataHandler triggers PSR-14 event
    M->>Q: Add/update queue item
    Note over Q: tx_solr_indexqueue_item
    S->>Q: Poll for pending items
    Q->>S: Return items to index
    S->>Solr: POST document (JSON)
    Solr-->>S: 200 OK
    S->>Q: Mark item as indexed

Component Overview

Component	Package	Purpose	Required?
EXT:solr	`apache-solr-for-typo3/solr`	Core search integration	Yes
EXT:tika	`apache-solr-for-typo3/tika`	Text/metadata extraction from files	Only for file indexing
EXT:solrfal	Funding extension	FAL file indexing into Solr	Only for file indexing
EXT:solrconsole	Funding extension	Backend management console	Optional
EXT:solrdebugtools	Funding extension	Query debugging, score analysis	Optional (recommended for dev)

2. Version compatibility matrix (upstream)

Target for this skill: TYPO3 v14.x with the EXT:solr release row that matches your Core on the official Version Matrix. Older rows are reference only for legacy sites.

EXT:solr	TYPO3	Apache Solr	Configset	PHP	EXT:tika	EXT:solrfal
14.0.x (see matrix / Packagist)	14.x	per matrix	`ext_solr_14_0_0` (when used)	^8.2	per matrix	per matrix
13.1.x	(not a target for this collection)	9.10.1	`ext_solr_13_1_0`	^8.2	13.1	13.0

Stable 14.0.1 was published on 2026-09-03 and requires Core ^v14.3.0 and PHP ^8.2. Use compatible stable constraints; the old beta-only guidance is retired.

TYPO3 v14 Readiness

The Version Matrix targets TYPO3 14.3 + EXT:solr 14.0 + Apache Solr 10.0.0 + ext_solr_14_0_0 (Solr 9.10.1 belongs to EXT:solr 13.1/12.1). Upstream development is on main:

main requires typo3/cms-core: ^v14.3.0 (see composer.json on main)
branch alias dev-main -> 14.0.x-dev
Composer reality check: Packagist lists stable 14.0.0 and 14.0.1. Prefer stable; a development fork/branch needs a specific reason and explicit approval, not a stale assumption that v14 is unreleased.

Resolve against the selected local project's lock:

ddev composer require apache-solr-for-typo3/solr:^14.0

Verify the chosen lock, server, Java and configset together. Do not infer Docker-image availability from a Composer release, and do not move an incompatible v14 project back to EXT:solr 13.1.

CVE-2025-24814 Migration

Apache Solr 9.8.0+ disables loading jar files via lib directive in configsets. CVE-2025-24814 is a remote-code-execution class issue: if an attacker can replace or supply a configset file that Solr treats as trusted, Solr may load attacker-controlled JARs from that configset (including via the lib directive), which can lead to arbitrary code execution. The stricter default blocks that classpath loading from configsets. The solr-typo3-plugin must be moved from /configsets/ext_solr_*/typo3lib/ to /typo3lib/ at the Solr server root. Docker users: use the EXT:solr container image 13.0.1+ (image tag, not TYPO3 Core) so this migration runs automatically.

3. Installation & Setup

Composer

composer require apache-solr-for-typo3/solr

DDEV Setup

The recommended local development setup uses the ddev-typo3-solr addon:

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

Solr image version: inspect the installed add-on's SOLR_BASE_IMAGE; its default is not proof of compatibility. The matrix checked on 2026-09-26 pairs EXT:solr 14.0 and ext_solr_14_0_0 with Apache Solr 10.0.0. Check the selected EXT:solr release's composer.json / info:solr-versions script for its full supported range. Set the matching image via .ddev/.env.typo3-solr, then rebuild and verify the running version. Do not retain a Solr 9 image just because it was the old add-on default.

Configure .ddev/typo3-solr/config.yaml:

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_14_0_0'
    path: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/configsets/ext_solr_14_0_0'
    cores:
      - name: 'core_en'
        schema: 'english/schema.xml'
      - name: 'core_de'
        schema: 'german/schema.xml'

Auto-initialize cores on boot in .ddev/config.yaml:

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

Useful DDEV commands:

Command	Description
`ddev solrctl apply`	Create cores from config
`ddev solrctl wipe`	Delete all cores
`ddev exec -s typo3-solr solr --version`	Check Solr version inside the Solr service
`ddev launch :8984`	Open Solr Admin UI
`ddev logs -s typo3-solr`	View Solr logs

Docker (Production)

services:
  solr:
    # Resolve the matching stable server/configset image and record its digest first.
    image: ${SOLR_IMAGE:?Set a reviewed compatible image tag or digest}
    # Reach from the application over a private Docker network; no public host port.
    expose:
      - "8983"
    volumes:
      - solr-data:/var/solr
    restart: unless-stopped

volumes:
  solr-data:
    driver: local

expose does not implement authentication or a firewall. Restrict network membership and configure the selected server's authentication/authorization and TLS where needed. Never publish the administrative API to the internet. Confirm UID, storage path and core provisioning against the selected image; generic Solr images do not supply TYPO3 language cores automatically.

Standalone Solr

Deploy the matching configset and TYPO3 plugin using the installed EXT:solr release's server instructions. Do not recursively copy the entire resource tree over an existing installation: Solr majors differ in plugin loading and directory layout. Back up configuration and indexes first.

Create cores via core.properties files, solrctl, or the Solr Admin API. Payload shape differs by Solr major (v8 vs v9 “v2” APIs) — treat any one-liner curl as illustrative and follow the Solr version you run.

# Illustrative only — confirm against your Solr admin API docs / use bin/solr or ddev solrctl for local setups
curl -sS -X POST "http://localhost:8983/solr/admin/cores?action=CREATE&name=core_en&configSet=ext_solr_14_0_0"

Managed Hosting: Mittwald

Check Mittwald's current Solr service documentation and verify server/configset support before provisioning. An old Solr 9 deployment example is not a validated EXT:solr 14 stack. Keep administrative access on a restricted management path.

Managed Hosting: hosted-solr.com

hosted-solr.com provides hosted Solr services for EXT:solr. Verify current supported versions, capacity, pricing and access restrictions directly with the provider before ordering. Configure TYPO3 with the actual provisioned host, port and core path.

TYPO3 Site Configuration

In config/sites/<identifier>/config.yaml:

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

For DDEV, use the DDEV hostname and HTTPS port:

solr_host_read: <project>.ddev.site
solr_port_read: '8984'
solr_scheme_read: https

Environment Configuration (helhum/dotenv-connector)

Never hardcode Solr connection details. Use helhum/dotenv-connector for per-environment configuration:

composer require helhum/dotenv-connector

.env (gitignored):

SOLR_HOST=solr
SOLR_PORT=8983
SOLR_SCHEME=http
SOLR_PATH=/
SOLR_CORE_EN=core_en
SOLR_CORE_DE=core_de

.env.example (committed to VCS):

SOLR_HOST=solr
SOLR_PORT=8983
SOLR_SCHEME=http
SOLR_PATH=/
SOLR_CORE_EN=core_en
SOLR_CORE_DE=core_de

In config/system/additional.php, override site config values programmatically or use a post-processing approach. For simple setups, keep .env values and reference them in deployment scripts that generate site config YAML per environment.

4. EXT:tika -- When You Need It (and When Not)

EXT:tika integrates Apache Tika for metadata extraction, language detection, and text extraction from over 1,000 file formats.

graph TD
    Question{"Do you index files?<br/>(PDF, DOCX, XLSX)"}
    Question -->|Yes| NeedTika[Install EXT:tika + EXT:solrfal]
    Question -->|No| SkipTika[Skip -- EXT:solr handles<br/>pages and records natively]
    NeedTika --> TikaServer["Run Tika Server 3.2.3+<br/>(Docker recommended)"]

Three backends (choose one):

Backend	Recommended?	Setup
Tika Server	Yes	Standalone Docker container, newest Tika version
Solr Cell	Acceptable	Uses Tika built into Solr, no extra service needed
Tika App	Deprecated	Requires Java on webserver, do not use

When you NEED EXT:tika:

File indexing via EXT:solrfal (search inside PDFs, Word documents, etc.)
Automatic FAL metadata enrichment (EXIF, XMP, document properties)
Language detection on uploaded files

When you DON'T need it:

Only indexing pages and structured records (news, events, products) via Index Queue
EXT:solr handles page content and record fields natively without Tika

Version: The official matrix checked on 2026-09-26 lists EXT:tika 14.0 and EXT:solrfal 14.0 for TYPO3 14.3 / EXT:solr 14.0. The previous “not yet available” statement is obsolete. Resolve the actual packages and Tika server requirements together; an old 13.1 example is not a target pin. Check Apache Solr security and Apache Tika advisories before deploying the server images.

See SKILL-SOLRFAL.md for complete file indexing setup.

Detailed Reference

Read the full guide when the task needs detailed examples, long templates, troubleshooting matrices, appendices, or sections not included above. Keep this file unloaded for narrow tasks so the skill follows progressive disclosure.