Download the PHP package tag1/scolta-php without Composer

Scolta PHP

PHP library that indexes content into Pagefind-compatible search indexes, plus the shared orchestration, memory-budget management, and AI client used by Scolta's CMS adapters.

Status

Scolta 1.0 — the API documented here is stable. Breaking changes follow semantic versioning: no removal or signature change without a major version bump and a deprecation cycle. File bugs at the repo issue tracker.

What Is Scolta?

Scolta is a scoring, ranking, and AI layer built on Pagefind. Pagefind is the search engine: it builds a static inverted index at publish time, runs a browser-side WASM search engine, produces word-position data, and generates highlighted excerpts. Scolta takes Pagefind's result set and re-ranks it with configurable boosts — title match weight, content match weight, recency decay curves, and phrase-proximity multipliers. No search server required. Queries resolve in the visitor's browser against the pre-built static index.

This package is the PHP foundation for all three CMS adapters. It handles the parts that are the same regardless of platform: indexing content to Pagefind-compatible HTML files, AI provider communication, configuration management, memory budgeting, and the shared browser assets (scolta.js, scolta.css, and the pre-built WASM module). The CMS adapters (scolta-drupal, scolta-laravel, scolta-wp) depend on this package and add only their platform-specific concerns.

The LLM tier — query expansion, result summarization, follow-up questions — is optional. When enabled, it sends the query text and selected result excerpts to a configured LLM provider. The base search tier shares nothing with any third party; it runs entirely in the visitor's browser.

Running Example

The examples in this README and the other Scolta repos use a recipe catalog as the concrete data set. Recipes are a good showcase because recipe vocabulary has cross-dialect mismatches that basic keyword search handles poorly:

• A search for aubergine parmesan should surface Eggplant Parmigiana.
• A search for chinese noodle soup should surface Lanzhou Beef Noodles, Wonton Soup, and Dan Dan Noodles.
• A search for gluten free pasta should surface Zucchini Spaghetti with Pesto and Rice Noodle Stir-Fry.
• A search for quick dinner under 30 min should surface Pad Kra Pao, Dan Dan Noodles, Steak Frites, and others.

The recipe fixture lives at tests/fixtures/recipes/ — 20 HTML files in Pagefind-compatible format, one per recipe.

Here is how to index the recipe catalog outside any CMS, using the IndexBuildOrchestrator directly:

After indexing, the /var/www/html/pagefind/ directory contains a Pagefind-compatible static index. Point a browser at it and load scolta.js to get a working search UI with vocabulary-mismatch handling.

Installation

Requirements: PHP 8.1+, ext-mbstring, ext-openssl. Recommended: ext-intl (improves Unicode diacritic normalization; falls back to a built-in mapping without it).

The only package dependencies are guzzlehttp/guzzle (^7.0|^8.0) and psr/log (^3.0). Both Guzzle majors are supported and tested, so installing into an application that already has Guzzle 8 (Laravel 13 ships it) does not downgrade the host's HTTP client.

Platform adapters install this package automatically. Install it directly only when building a custom adapter or a non-CMS integration.

Configuration and Quickstart

All Scolta configuration flows through Tag1\Scolta\Config\ScoltaConfig. Construct it with ScoltaConfig::fromArray():

For the full list of config keys and their defaults, see docs/CONFIG_REFERENCE.md.

To render results with your own markup instead of Scolta's built-in card — a platform view mode, server-rendered fragments swapped in lazily, anything richer than title/excerpt/URL — see docs/RENDER_SEAM.md, which documents the render lifecycle events, Scolta.setResultRenderer(), and the non-destructive mount.

Selecting an AI provider is always manual

Scolta ships with no AI provider selected. ai_provider is empty until somebody sets it, and while it is empty AI features are simply off: search works, no provider is assumed, and Anthropic in particular is not silently assumed. There is no default anywhere.

An operator picks a provider in an adapter's admin UI; a developer sets ai_provider in code for the frameworks that have no admin UI. Both are explicit acts. This is a going-forward rule: a site that already persisted a provider keeps it, and nothing rewrites an existing value.

Amazee.ai is never enabled on its own. No credential is provisioned and no outbound Amazee call is made on a request, cron, install or activation path for a site that has not opted in. AutoProvisioner::ensureAiAvailable() — whose name predates the policy — establishes nothing: it only re-resolves gateway model names against a key already on disk, which is reachable only for a site that already connected. A connection is established solely by an explicit call to AmazeeTrialProvisioner::provision() (the free demo, no email required) or AmazeeAccountUpgrader (the email → verification code → region flow that attaches an amazee.ai account). Amazee support is email-only, mirroring amazee.ai's own ai_provider_amazeeio module; there is no paste-your-API-key path.

Which of those two established a connection is recorded at the time it happens, through ProvenanceAwareConfigStorageInterface, so ApiKeySource can report amazee:demo or amazee:account from a stored fact instead of a guess. Credentials with no recorded origin — anything connected before 1.2.0 — report the plain amazee source and claim nothing.

The AI API key can come from an environment variable, a platform settings file or store, or stored Amazee.ai credentials. Tag1\Scolta\Config\ApiKeyResolver decides which one wins and returns the key together with its source, so an adapter's settings form, health payload and CLI cannot describe the key differently from the client that sends it. The order, the source vocabulary, and the rules adapters follow are in docs/API_KEY_PRECEDENCE.md.

HealthChecker builds the payload every adapter serves from its health endpoint. status is ok or degraded, and status_reasons names each fault behind a degraded for the operator who can see the detail payload. A deployment that selected no AI provider is not degraded — search works without one — while a provider that is configured and failing is. The AI fields, and in particular how to read ai_auth_failing — a cached marker reported with its age, cleared by the first successful AI call, and clearable by hand when no call can succeed — are documented in docs/HEALTH_REFERENCE.md.

Search as you type is on by default: typing opens a dropdown of suggestions and recent searches, while the full pipeline still runs only on Enter or on selecting a suggestion. Turn it off with sayt_enabled: false. See docs/SAYT.md for the ten settings, the two suggestion modes, the AI expansion budget, the render events and the theming custom properties.

What Scolta Is Built For

Scolta is designed for content search on publishing platforms: pages, posts, documentation, product catalogs, and other human-authored content indexed at build time. This package is the PHP foundation shared by the Drupal, WordPress, and Laravel adapters — the platforms behind enterprise content operations, government and university portals, media publishing, and product-driven businesses.

The static-index architecture eliminates the search server. No Solr, no Elasticsearch, no hosted SaaS subscription to operate or pay for. Scolta replaces those for content sites where the search use case is full-text relevance, recency, and phrase matching. Teams on managed hosting (WP Engine, Kinsta, Pantheon, Flywheel) where exec() is disabled will find the PHP indexer runs there without any configuration change.

Memory and Scale

Memory profiles control Scolta's internal allocation budget — the memory Scolta itself adds on top of what the PHP process already uses. Total process RSS is higher: it includes the PHP runtime baseline for your platform plus the Scolta budget plus ~15 MB I/O overhead.

Typical platform baselines (before any indexing work):

The default profile is conservative (96 MB internal budget). On WordPress, expect total peak RSS around 175 MB; on Drupal, around 240 MB. Scolta never silently upgrades to a larger profile. To opt in to a larger profile:

The trade-off: a larger budget means fewer, larger index chunks and faster builds. The conservative profile is always the default and always safe to use.

Tested ceiling at the conservative profile: 50,000 pages. Higher counts likely work; not certified yet.

You can also pass the profile string at the CLI via --memory-budget=balanced if the CMS adapter supports the flag.

AI Features and Privacy

Scolta's AI tier is optional. When enabled:

• The LLM receives: the query text, and the titles and excerpts of the top N results (default: 10, configurable via ai_summary_top_n).
• The LLM does not receive: the full index contents, full page text, user session data, or visitor identity.
• Which provider receives the query data depends on your ai_provider setting: anthropic, openai, or a self-hosted endpoint via ai_base_url.

The base search tier — Pagefind index lookup and Scolta WASM scoring — runs entirely in the visitor's browser with no server-side involvement beyond serving the static index files.

Optional Upgrades

Indexer options

Both indexers produce the same Pagefind-compatible index. The search experience is identical either way. Choose based on your hosting constraints.

PHP indexer (the default): runs everywhere, no binary required. Around 3–4 seconds per 1,000 pages. Supports 14 languages via Snowball stemming (Catalan, Danish, Dutch, English, Finnish, French, German, Italian, Norwegian, Portuguese, Romanian, Russian, Spanish, Swedish).

Pagefind binary indexer: 5–10× faster. Requires Node.js ≥ 18 or a direct binary download. Supports 33+ languages. Better for large sites or environments where the binary is installable.

On managed hosting (WP Engine, Kinsta, Flywheel, Pantheon), exec() is disabled. The PHP indexer runs there automatically with no configuration change.

To install the binary:

indexer: auto (the default) uses the binary when available and falls back to PHP automatically.

Language support for the PHP indexer

For languages outside the 14 supported by Snowball, search works but inflected forms ("running", "ran") will not match a stemmed base ("run"). CJK languages (Chinese, Japanese, Korean) use character-level tokenization and do not require stemming. For full 33+ language stemming coverage, use the Pagefind binary indexer.

Debugging

"ext-intl not found"

Verify: php -m | grep intl

"PhpIndexer produces empty output"

Verify ext-intl is loaded and that the ContentItem objects passed to the indexer have non-empty bodyHtml. The indexer skips items where the cleaned text is shorter than 50 characters.

"AI calls failing"

1. Confirm the API key: check SCOLTA_API_KEY env var or the platform-specific constant.
2. Check the model identifier — model names change with provider releases. Default: claude-sonnet-4-5-20250929.
3. Enable request logging: set SCOLTA_DEBUG=1 to log raw request/response bodies via Guzzle.

"Scoring results look wrong"

The browser-side WASM scorer (scolta-core) runs via wasm-bindgen. If results appear unscored or identically ranked, confirm both pagefind.js and scolta_core_bg.wasm are loading without 404 errors in the browser console.

Configuration Reference

All Scolta configuration flows through Tag1\Scolta\Config\ScoltaConfig. Platform adapters map their native config systems into this object via ScoltaConfig::fromArray(), which accepts snake_case keys.

Every configuration property — its type, default value, per-platform key mapping, and the scoring presets — is documented in docs/CONFIG_REFERENCE.md. That file is the single source of truth for defaults and is verified against ScoltaConfig in CI (tests/Documentation/ConfigReferenceDocTest.php), so the values there never drift from the code. Defaults are intentionally not restated here.

Architecture

What lives here:

• ScoltaConfig — platform-agnostic configuration with scoring defaults
• AiClient — provider-agnostic HTTP client for Anthropic and OpenAI APIs
• AiEndpointHandler — shared expand / summarize / follow-up logic
• ContentExporter — exports content items to Pagefind-compatible HTML files
• IndexBuildOrchestrator — single authoritative chunk-loop entry point for all adapters
• MemoryBudget / MemoryBudgetSuggestion — memory profile management
• PhpIndexer — pure PHP indexer producing Pagefind-compatible index files
• HtmlCleaner — HTML cleaning for content extraction
• DefaultPrompts — prompt templates with variable resolution (pure PHP, no WASM)
• PagefindBinary — binary resolver and downloader
• Shared assets — scolta.js, scolta.css, browser WASM

Scoring runs entirely in the browser via the WASM module loaded by scolta.js. The PHP server handles content indexing, AI API proxying, and configuration only.

Testing

Credits

Scolta is built on Pagefind by CloudCannon. Without Pagefind, Scolta has no search to score — the index format, WASM search engine, word-position data, and excerpt generation are all Pagefind's. Scolta's contribution is the layer that sits on top: configurable scoring, multi-adapter ranking parity, AI features, and platform glue.

License

MIT

Related Packages

• scolta-core — Rust/WASM scoring, ranking, and AI layer that runs in the browser.
• scolta-drupal — Drupal 10/11 Search API backend with Drush commands, admin settings form, and a search block.
• scolta-laravel — Laravel 11/12/13 package with Artisan commands, a Searchable trait for Eloquent models, and a Blade search component.
• scolta-wp — WordPress 6.x plugin with WP-CLI commands, Settings API page, and a [scolta_search] shortcode.