Ecommercen Docs

Appearance

Search Debug Admin ​

Flow ID: AD-45 | Module(s): search | Complexity: Low Last Updated: 2026-04-04

Business Context ​

The search debug tool provides Advisable-level administrators with a diagnostic interface for testing and analyzing Solr search queries. It allows entering a search term and viewing the raw search results, relevance scores, and debug output from the Solr engine.

The tool supports both Solr v1 and v2 search implementations, rendering version-specific debug views. It is only accessible when the APP_SOLR_DEBUG environment variable is enabled, making it a development/troubleshooting tool rather than a production feature.

API Reference ​

REST Endpoints ​

No REST API.

Legacy Admin Routes ​

RouteControllerMethodHTTPDescription
admin/search_debugAdv_search_debugindexGETDebug page (empty search)
admin/search_debug/{searchTerm}Adv_search_debugindexGETDebug page with pre-filled search term

Code Flow ​

Solr v1 Debug ​

  1. Admin navigates to admin/search_debug/{searchTerm}.
  2. index() checks isDebug() -- returns 404 if APP_SOLR_DEBUG is not true.
  3. Loads search_model and solr_model for v1.
  4. Calls search_model::searchProducts($searchTerm) which returns { results, numRows, debug }.
  5. Renders search/search_debug view with searchResults, numRows, and searchDebug data.

Solr v2 Debug ​

  1. Same entry point, but when solrSearch.version is v2.
  2. Loads search_model_v2 and solr_model_v2.
  3. Runs two separate searches:
    • search_model_v2::searchProducts($searchTerm) -- returns products with debug data including a debug_url to the raw Solr query.
    • search_model_v2::searchBlogArticles($searchTerm) -- returns blog article matches with separate debug data.
  4. Assembles debugResults containing both products and blogArticles sections, each with searchResults, numRows, searchDebug, and debugUrl.
  5. Renders search/search_debug_v2 view.

Domain Layer ​

No modern domain layer. Search debug is a pure legacy admin tool.

Architecture ​

ComponentPathPurpose
Adv_search_debugecommercen/search/controllers/Adv_search_debug.phpAdmin controller (86 lines)
Search_model / Search_model_v2ecommercen/search/models/Search query builders
Solr_model / Solr_model_v2ecommercen/search/models/Solr HTTP client and response parsers
Routesapplication/config/routes.php:724-727Route definitions

Data Model ​

No dedicated tables. Reads from Solr search indexes.

Configuration ​

SourceKeyDescription
EnvironmentAPP_SOLR_DEBUGMust be true to enable the debug page
ConfigsolrSearch.versionDetermines which search version (v1/v2) to use
Configapplication/config/solr.phpSolr connection settings (host, port, core)

Required roles: AUTH_ROLE_ADVISABLE only.

Double gate: Access requires both AUTH_ROLE_ADVISABLE role AND APP_SOLR_DEBUG=true environment variable.

Client Extension Points ​

  • Override controller: Extend in application/modules/search/controllers/ to add custom debug panels or export features.
  • Override models: Extend search models to include additional debug output or custom query parameters.

Business Rules ​

  1. Environment gate: The isDebug() method checks env('APP_SOLR_DEBUG') === true. If false, returns 404 even for Advisable users.
  2. Advisable-only: Only AUTH_ROLE_ADVISABLE users can access the debug tool.
  3. Version-aware: Automatically uses the correct search model and view template based on the configured Solr version.
  4. Blog articles (v2 only): The v2 debug tool also tests blog article search, not just products.
  5. Debug URL: In v2, a direct Solr debug URL is provided so developers can inspect the raw Solr query and scoring in the Solr admin UI.
  • SY-06 Solr Indexing -- Builds and maintains the Solr indexes that this tool queries
  • CF-04 Search -- Storefront search that uses the same Solr infrastructure

Wiki Guide: Solr Setup Guide -- full Solr installation, configuration, and schema management guide