README

Search replaces the native Flarum search functionality which relies on MySQL badly performing fulltext search with one that is completely relying on the proven elasticsearch engine.

Features

Sync discussions and posts to Elasticsearch using your queue, unobtrusively for the user.
Reduces search loading times to well below 400ms (local tests with 50,000 discussions: 260ms)
Uses Flarum's group permissions and tags system.
Compatible with Friends of Flarum Byōbu.

Requirements

Elasticsearch 7.x or OpenSearch 1.x+
A non-sync queue driver with a running worker (php flarum queue:work) is strongly recommended for production. The extension works with the default sync driver, but index jobs run inline which adds latency to user-facing changes like posting.

Installation

composer require blomstra/search:*

Enable the extension in the admin area and configure the Elasticsearch endpoint and index name in the extension settings.

Setting up the index

First install

Run the build command once. It creates a timestamped concrete index, immediately aliases your configured index name to it, and begins queuing documents. Search is available and improves as the queue processes:

php flarum blomstra:search:index build
php flarum queue:work

Subsequent rebuilds (zero-downtime)

When you need to rebuild the full index (e.g. after a mapping change):

# Simple rebuild — promotes automatically once all jobs are queued
php flarum blomstra:search:index build

# Or keep a backup of the old index in case you need to roll back
php flarum blomstra:search:index build --keep-backup

After the queue drains, fill any gaps from content posted during the build:

php flarum blomstra:search:index fill

If you kept a backup and want to roll back:

php flarum blomstra:search:index rollback

Once satisfied with the new index, drop the backup:

php flarum blomstra:search:index discard --backup

Blue-green rebuild (manual promotion)

Use --staging to keep the old index live until you explicitly promote:

# 1. Build into a staging index — live index is untouched
php flarum blomstra:search:index build --staging

# 2. Drain the queue
php flarum queue:work --stop-when-empty

# 3. Promote the staging index to live
php flarum blomstra:search:index promote
# Or keep the old index as a backup:
php flarum blomstra:search:index promote --keep-backup

Resuming or cancelling an interrupted build

If a build is interrupted, re-run it with the appropriate flag:

# Resume each seeder from where it left off
php flarum blomstra:search:index build --resume

# Drop the staging index and start completely fresh
php flarum blomstra:search:index build --fresh

# Cancel the build without starting a new one
php flarum blomstra:search:index discard --pending

Filling gaps in an existing index

If documents are missing from the live index (e.g. due to queue failures):

php flarum blomstra:search:index fill

Updating the mapping only

To push a mapping change to the live index without rebuilding:

php flarum blomstra:search:index mapping

Command reference

Command	Description
`build`	Rebuild the index and promote automatically once all jobs are queued. On first install, aliases immediately so search is live during seeding.
`build --keep-backup`	Rebuild and promote, retaining the old index as a backup for rollback.
`build --staging`	Build into a staging index without promoting — use `promote` when ready (blue-green workflow).
`build --resume`	Resume an interrupted build from where each seeder left off.
`build --fresh`	Drop the staging index and start completely fresh.
`promote`	Atomically swap the alias to the staging index. Prompts for confirmation (blue-green workflow).
`promote --keep-backup`	Promote and retain the replaced live index as a backup for rollback.
`rollback`	Restore the backup index to live. Deletes the index that was live.
`discard --pending`	Drop the staging index without promoting (cancels an in-progress build).
`discard --backup`	Drop the backup index (cleanup after `--keep-backup`).
`mapping`	Push updated mapping to the live index without rebuilding or reseeding.
`fill`	Seed only documents missing from the live index.
`build --only=discussions`	Seed only the specified document type (`discussions` or `posts`).
`build --throttle=N`	Wait N seconds between batches (reduces queue pressure).
`build --max-id=N`	Limit seeding to documents with ID ≤ N.
`promote --i-am-sure`	Skip the promotion confirmation prompt (for scripts and CI).

FAQ

Queue configuration

"Can I dispatch indexing jobs to a specific queue?"

Yes:

\Blomstra\Search\Jobs\Job::$onQueue = 'search';

"I have a different question"

Reach out ot us via https://support.on-floxum.com/t/ext-search . If you have an active subscription, please mention what plan you are on.

Floxum provides managed Flarum hosting.
https://floxum.com
https://support.on-floxum.com/t/ext-search

Icon made by Freepik from Flaticon.

blomstra / search

Maintainers

Package info

Statistics

Security