Download the PHP package tag1/scolta-laravel without Composer

Scolta for Laravel

Built and maintained by Tag1 Consulting — technology leadership since 2007.

Laravel 11/12/13 package — Artisan commands, Searchable trait for Eloquent models, and AI-powered search built on Pagefind.

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 a pre-built static index.

This package is the Laravel adapter. It provides Artisan commands for building and maintaining the index, a Searchable trait for Eloquent models, a <x-scolta::search /> Blade component, change tracking via an observer pattern, and REST API endpoints for the AI features. The actual scoring, indexing logic, memory management, and AI communication live in scolta-php, which this package depends on. Scoring runs client-side via the scolta.js browser asset and the pre-built WASM module shipped with scolta-php.

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 (Anthropic, OpenAI, or a self-hosted Ollama endpoint). The base search tier shares nothing with any third party.

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 genuine cross-dialect mismatches:

• 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, and Steak Frites.

Here is how to model and index the recipe catalog in Laravel:

Register the model in config/scolta.php:

Build the index:

Then add <x-scolta::search /> to any Blade template and visit the page. A search for aubergine parmesan surfaces Eggplant Parmigiana because the body HTML includes both the American term "eggplant" and the Italian name. Scolta's title boost lifts it above pages that mention aubergine only in passing.

The recipe fixture HTML files live in scolta-php at tests/fixtures/recipes/ if you want a pre-built data set to index without a database.

Quick Install

In .env:

With an API key configured, search queries are automatically expanded with related terms, results include an AI summary, and visitors can ask follow-up questions.

Verify It Works

This verifies PHP version, index directories, indexer selection, AI provider configuration, and binary availability.

The health endpoint also reports current state: GET /api/scolta/v1/health

What Scolta Is Built For

Scolta is designed for content search on Laravel applications: articles, documentation, product catalogs, knowledge bases, and other Eloquent model content indexed at build time. Laravel powers SaaS products, enterprise applications, API platforms, and content-driven sites — and Scolta is tuned for the content search needs of these applications.

The static-index architecture means no Elasticsearch or Solr server to provision. Scolta replaces hosted search SaaS (Algolia, Coveo, SearchStax) and Solr/Elasticsearch backends for Laravel applications where the search use case is full-text relevance, recency, and phrase matching. It runs on managed hosting where binary execution is restricted, using the PHP indexer automatically.

Migrating from Laravel Scout

Scout and Scolta solve different problems. Scout drives external search servers (Algolia, Meilisearch, Typesense). Scolta runs Pagefind, which produces a static browser-side index — no search server required. Scolta then re-ranks Pagefind's results and optionally adds an AI layer.

Replace toSearchArray() with toSearchableContent() and scopeSearch() with scopeSearchable(). Remove Scout from composer.json, publish Scolta's config and migrations, and replace Scout search calls with <x-scolta::search />.

What you gain: no external search service bill, AI query expansion and summarization, works on shared and managed hosting. What you give up: Scout's per-record real-time index updates and its driver flexibility.

Memory and Scale

The default memory profile is conservative, which targets a peak RSS under 96 MB and works on shared hosting with a 128 MB PHP memory_limit. Scolta never silently upgrades to a larger profile.

The admin interface shows the detected PHP memory_limit and suggests a profile. The profile selection is always left to the admin.

Pass the profile via the Artisan CLI:

Available profiles: conservative (default, ≤96 MB), balanced (≤200 MB), aggressive (≤384 MB). Higher budget means fewer, larger index chunks and faster builds.

Or set it in .env:

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

Deploying to PaaS Platforms

On PaaS platforms — including Laravel Cloud, Forge with push-to-deploy, Vapor, Railway, and Render — the filesystem is rebuilt from your repository on every deploy. Any files written outside the repo at install time are wiped, including assets published by vendor:publish.

php artisan vendor:publish --tag=scolta-assets must run as part of your build pipeline, not just during initial setup.

Wiring it automatically via post-autoload-dump

Add it to your application's composer.json scripts:

Composer runs post-autoload-dump on every composer install and composer update, which PaaS platforms execute automatically on each deploy. The --force flag is required so assets are refreshed even when the destination directory already exists from a previous build cache.

Important: Composer only runs scripts from the root package — your application. Scripts in a dependency's composer.json (including Scolta's own) are never executed for consumers. You must add the script to your own composer.json.

Platform-specific steps

Laravel Cloud: Runs composer install on each deployment. The post-autoload-dump script above runs automatically.

Laravel Vapor: Runs composer install in the Lambda package build step. The post-autoload-dump script above runs automatically.

Laravel Forge (push-to-deploy): Add the publish command to your Forge deployment script, after the composer install line:

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 SCOLTA_AI_PROVIDER setting: anthropic, openai, or a self-hosted endpoint via SCOLTA_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 static index files.

Configuration

All settings live in config/scolta.php with .env overrides. After editing config/scolta.php, run php artisan config:clear.

AI Provider

In .env:

For multilingual sites:

Search Scoring

Scoring settings live under the scoring key in config/scolta.php.

Defaults and the full reference: scolta-php docs/CONFIG_REFERENCE.md.

News site (recency matters a lot):

Documentation site (recency doesn't matter, titles matter a lot):

Recipe catalog (no recency, title precision matters):

Display

Display settings are top-level keys in config/scolta.php.

Defaults and the full reference: scolta-php docs/CONFIG_REFERENCE.md.

Site Identity

Custom Prompts

Override prompts via the top-level keys prompt_expand_query, prompt_summarize, and prompt_follow_up in config/scolta.php, or use an event listener:

Register in EventServiceProvider:

Preset

Getting fewer results than you expect on a recipe, product, or catalog site? Set SCOLTA_PRESET=content_catalog and rebuild your index — the Recipe & Content Catalog preset widens search breadth so ingredient, technique, and product-attribute searches return the fuller set of matches you'd expect.

A preset is the recommended way to tune scoring: pick the one that matches your site instead of setting individual numbers. Set SCOLTA_PRESET in .env (or edit config/scolta.php) to apply one. Any explicit values in the scoring array still override the preset.

For the evidence behind each preset — the scoring sweeps and per-parameter data — see scolta-php's docs/TUNING.md.

Indexer and Memory

Pagefind

Caching and Rate Limiting

Routes and Middleware

Auto Rebuild

Sort and Filter Fields

Amazee.ai Integration

Amazee.ai provides a managed LiteLLM proxy with a free trial. Scolta auto-provisions a trial on the first AI request when no SCOLTA_API_KEY is configured.

CLI provisioning:

Admin UI: The admin settings UI at /scolta/amazee (configurable via amazee_route_prefix) provides the multi-step connection flow. Its routes can disconnect stored AI credentials, so they are disabled by default — they are only registered when you configure amazee_middleware with protection beyond the bare ['web'] group:

With the shipped default (['web']), requests to these routes return 404. CLI provisioning and first-request auto-provisioning work without the admin UI.

Routes (when enabled):

Migrations

Scolta uses two database tables. Publish and run migrations during installation:

Debugging

"Pagefind binary not found"

On managed hosting where exec() is disabled, the package falls back to the PHP indexer automatically. The PHP indexer works on WP Engine, Kinsta, Flywheel, Pantheon, and any host where exec() is unavailable. It supports 14 languages via Snowball stemming. The search experience is identical to using the binary.

To install the binary on a host that supports it:

Set SCOLTA_INDEXER=binary in .env and rebuild.

"AI features not working"

1. Verify API key: php artisan scolta:check-setup
2. Clear stale cache: php artisan scolta:clear-cache
3. Clear config cache: php artisan config:clear
4. Confirm the model name in config/scolta.php

"AI summary says 'I don't have enough context'"

The defaults (10 results, 4000 chars) are already tuned for curation. If still insufficient, increase further:

"AI responses are in the wrong language"

Set ai_languages to match your site's language(s):

"Expanded queries return irrelevant results"

Raise expand_primary_weight (default: 0.5) to make original query terms dominate more, or disable expansion:

"No search results"

1. Check index status: php artisan scolta:status
2. Run a full rebuild: php artisan scolta:build
3. Verify published assets: php artisan vendor:publish --tag=scolta-assets --force
4. Confirm the Pagefind output directory is web-accessible (must be under public/)

"Models not being indexed"

Run php artisan scolta:discover to find Searchable models not registered in config/scolta.php. The observer only tracks models listed there.

Add the Searchable Trait

Register the model in config/scolta.php:

Artisan Commands

API Endpoints

Route prefix and middleware are configurable via route_prefix and middleware in config/scolta.php.

The build-progress and rebuild-now endpoints require Sanctum authentication and are intended for admin dashboards. The AI endpoints (expand-query, summarize, followup) use the configurable middleware array and are typically public-facing.

Health detail authorization

GET /api/scolta/v1/health always answers monitoring tools: anonymous requests get {"status": "ok"} (or "degraded"), HTTP 200. The full diagnostic payload (AI provider, index integrity, tracker counts, asset staleness) requires the scolta.health-detail Gate. By default any authenticated user passes. To change who sees the detail, redefine the gate in your AuthServiceProvider:

Note: Amazee.ai admin routes (/scolta/amazee/*) use web middleware and are documented in the Amazee.ai Integration section below.

Searchable Trait API

Optional Upgrades

Upgrade to the Pagefind binary indexer

On hosts with Node.js ≥ 18 or binary execution support, the Pagefind binary is 5–10× faster than the PHP indexer:

Set SCOLTA_INDEXER=binary in .env and rebuild. The PHP indexer continues to work on managed hosts (WP Engine, Kinsta, Pantheon, etc.) where binary execution is disabled.

Keeping the Index Fresh

When auto_rebuild is enabled (SCOLTA_AUTO_REBUILD=true in .env), a ScoltaObserver watches the models listed in config/scolta.php and dispatches a debounced TriggerRebuild job whenever a model is saved or deleted (default delay: 5 minutes). This requires a queue worker running.

Three paths are available, in order of reliability:

Path A: Queue worker / Supervisor (recommended)

Enable auto_rebuild and run a persistent queue worker:

For production, use Supervisor or Laravel Forge to keep the worker running. Forge configures this automatically.

Content saves trigger ScoltaObserver, which dispatches a TriggerRebuild job after the configured delay. The queue worker processes that job in the background.

Path B: Laravel Scheduler

Add a scheduled rebuild to your app. One system cron entry handles all Laravel scheduled tasks:

Then schedule the build in routes/console.php (Laravel 11+):

Or in app/Console/Kernel.php (Laravel 10):

--incremental only processes tracked changes, so runs are fast when nothing has changed.

Path C: System cron (direct)

Call scolta:build directly from system cron, bypassing the Scheduler:

Simpler than the Scheduler but without Laravel's logging integration and overlap protection.

Requirements

• Laravel 11, 12, or 13
• PHP 8.1+

The Pagefind binary is optional — the PHP indexer works without it.

Laravel 11 and end-of-life versions

Scolta runs on Laravel 11, 12, and 13, and its test suite covers all three so apps on older releases aren't stranded. Be aware of what that means for Laravel 11 specifically:

Laravel 11 reached end of life on 12 March 2026. The Laravel team no longer ships security patches for it, so advisories against laravel/framework 11.x stay open with no fix. To see which advisories affect the version you're actually running, run composer audit in your project — it reports the affected and fixed version ranges from the same database Scolta's CI uses. The published list is maintained at Laravel's security advisories.

Scolta installs and tests cleanly on Laravel 11 because it deliberately allows these upstream framework advisories in its own CI, which keeps the 11.x compatibility check green. That does not make your application secure — the Laravel version your app runs is your responsibility, and on 11.x you are running an unsupported framework with known, unpatched holes.

If you are on Laravel 11, upgrade to Laravel 12 (security-supported through 24 February 2027) or Laravel 13. If you must stay on 11 for now, treat it as temporary and plan the upgrade.

Testing

Unit tests (no Laravel bootstrap required):

Integration tests (requires DDEV):

Coding standards:

Architecture

This package handles Laravel-specific concerns: Artisan commands, Eloquent model observation, Blade components, route registration, publishable config/migrations, and middleware. It depends on scolta-php and never on scolta-core directly. Scoring runs client-side via WebAssembly loaded by scolta.js.

External Services

Scolta connects to external services under specific conditions. No data is sent automatically — all connections are triggered by developer action or explicit configuration.

GitHub API (api.github.com)

When: A developer runs php artisan scolta:download-pagefind to download the Pagefind binary. What is sent: A standard HTTPS GET request to https://api.github.com/repos/CloudCannon/pagefind/releases/latest. No personally identifiable information is transmitted beyond standard HTTP request headers (IP address, user agent). Service: GitHub, operated by GitHub, Inc. (a subsidiary of Microsoft Corporation). Terms of Service: https://docs.github.com/en/site-policy/github-terms/github-terms-of-service Privacy Statement: https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement

Pagefind Binary (GitHub Releases / Pagefind)

When: php artisan scolta:download-pagefind downloads the Pagefind binary from GitHub Releases after querying the GitHub API above. What is sent: A standard HTTPS GET request to download the release archive. No personally identifiable information is transmitted beyond standard HTTP request headers. Service: Pagefind is an open-source project (MIT license) maintained by the Pagefind project. Pagefind: https://pagefind.app/ CloudCannon: https://cloudcannon.com/ Pagefind License: https://github.com/Pagefind/pagefind/blob/main/LICENSE

AI Provider APIs

When: A visitor performs a search and AI features are enabled (SCOLTA_AI_EXPAND=true or SCOLTA_AI_SUMMARIZE=true in .env). AI features are disabled by default and require an API key to be configured. What is sent: The user's search query text and selected page content excerpts (for result summarization) are sent to the configured AI provider's API endpoint. See AI Features and Privacy for full details on what is and is not transmitted. Providers: The specific provider depends on the SCOLTA_AI_PROVIDER setting:

• Anthropic (Claude) — processes search queries and page excerpts. Terms of Service: https://www.anthropic.com/legal/consumer-terms Privacy Policy: https://www.anthropic.com/legal/privacy
• OpenAI — processes search queries and page excerpts. Terms of Use: https://openai.com/policies/terms-of-use Privacy Policy: https://openai.com/policies/privacy-policy
• OpenAI-compatible endpoints (including self-hosted Ollama and other providers) — any endpoint configured via SCOLTA_AI_BASE_URL. Review the terms and privacy policy of your chosen provider.

No AI API calls are made unless SCOLTA_API_KEY is set and AI features are enabled.

About Tag1 Consulting

Scolta is designed, built, and maintained by Tag1 Consulting. Tag1 has been delivering technology leadership since 2007 and is one of the leading open-source consulting firms in the world.

Tag1 offers AI strategy, architecture, and implementation consulting — from evaluating whether AI search is right for your organization, to production deployment and ongoing tuning. If you need help integrating Scolta, customizing scoring for your content model, or connecting it to your AI provider of choice, get in touch.

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-php — PHP library that indexes content into Pagefind-compatible indexes, plus the shared orchestration and AI client.
• scolta-drupal — Drupal 10/11 Search API backend with Drush commands, admin settings form, and a search block.
• scolta-wp — WordPress 6.x plugin with WP-CLI commands, Settings API page, and a [scolta_search] shortcode.