Download the PHP package imarc/craft-googlecustomsearch without Composer

Site Search plugin for Craft CMS

A Craft CMS plugin that adds external site search to your website, with three supported providers:

• Google Programmable Search Engine (Custom Search JSON API)
• Google Vertex AI Search (Discovery Engine)
• AddSearch

The provider is chosen per site, so multisite installs can mix providers. All providers return the same result shape, so your templates don't change when you switch.

This plugin was previously published as imarc/craft-googlecustomsearch. See see the craft2 branch.

Requirements

This plugin requires Craft CMS 4.x or 5.x and PHP 8.2+.

Installation

1. Open your terminal and go to your Craft project:

   cd /path/to/project

2. Then tell Composer to load the plugin:

   composer require imarc/craft-sitesearch

3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Site Search.

Configuring

Go to Settings → Plugins → Site Search, pick a provider for each site (use the site menu to switch between sites on multisite installs), and fill in that provider's credentials. Every field accepts environment variables ($MY_VAR). Credentials can also be set in config/sitesearch.php (see Config file).

Google Custom Search setup

You will need a Search Engine ID and API Key.

1. Search Engine ID — On the Programmable Search Engine control panel, create a search engine for the site you would like to integrate. Once created, copy the Search Engine ID from the Basics tab.
2. API Key — In the Google Cloud console, create (or pick) a project, enable the Custom Search API (APIs & Services → Library), then create an API key under APIs & Services → Credentials. Restrict the key to the Custom Search API.

Google Vertex AI Search setup

Vertex AI Search (in the Google Cloud console as "AI Applications", formerly Agent Builder / Discovery Engine) provides Google-quality search over a crawled website index.

1. In the Google Cloud console, create (or pick) a project and note its Project ID.
2. Enable the Discovery Engine API (APIs & Services → Library → "Discovery Engine API").
3. Go to AI Applications and create a Search app:
   • Type: Search, content: Website content (create a website data store pointing at your site's domain; verify the domain for advanced indexing if prompted).
   • Note the app's ID — this is the plugin's App / Engine ID — and its location (usually global).
4. Create credentials for the plugin:
   • Go to IAM & Admin → Service Accounts, create a service account (e.g. craft-site-search).
   • Grant it the Discovery Engine Viewer role (roles/discoveryengine.viewer).
   • Create a JSON key for it (Keys → Add key → JSON) and store the file on your server outside the web root.
   • In the plugin settings, set Service Account Key File to the file path (an env var like $GOOGLE_APPLICATION_CREDENTIALS works well).
   • On Google Cloud hosting (Cloud Run, GCE, App Engine): leave the key file blank and grant the runtime service account the Discovery Engine Viewer role — the plugin uses Application Default Credentials automatically.

Note: it can take a while after creating the app for the website index to populate.

AddSearch setup

1. Sign up at addsearch.com and create an index for your site (AddSearch crawls it for you).
2. In the AddSearch dashboard, find your index's public Site Key (Setup → Keywords & API).
3. Enter the Site Key in the plugin settings. If your index is private, also enter your secret API Key.

Config file

Copy src/config.php to config/sitesearch.php to configure per environment. Keys under siteSettings are site handles:

The legacy single-site format (top-level apiKey/searchEngineId, Google Custom Search only) is still supported.

Usage

In your twig template, retrieve search results by passing your search query, then iterate over them:

The response has the same shape for every provider:

Full signature: performSearch(terms, page = 1, perPage = 10, extra = []). extra is merged into the provider request (e.g. Vertex request fields, AddSearch or Custom Search query params).

By default an exception is thrown if the provider returns an error; call craft.siteSearch.setThrowOnFailure(false) first to log a warning and get the error response back instead.

Google Custom Search result limit: the Custom Search JSON API only serves the first 100 results of a query (and at most 10 per page), so with the gcs provider totalResults is capped at 100 to keep pagination from linking to pages Google won't serve. Google's uncapped match estimate is still available at response.raw.queries.request[0].totalResults if you want to display it (e.g. "About 52,000 results").

Here is a complete example with pagination:

Upgrading from v2

v3 renames the plugin from Google Custom Search (imarc/craft-googlecustomsearch) to Site Search (imarc/craft-sitesearch) and supports Craft CMS 4 and 5:

1. composer remove imarc/craft-googlecustomsearch && composer require imarc/craft-sitesearch
2. Install the Site Search plugin in the Control Panel (or php craft plugin/install sitesearch). Your existing Google Custom Search settings are copied over automatically during install.
3. craft.googlecustomsearch still works but is deprecated — switch templates to craft.siteSearch at your convenience. The result shape is unchanged (plus a new raw property).
4. If you had a config/googlecustomsearch.php, rename it to config/sitesearch.php.
5. Uninstall/remove the old plugin if it's still listed.

Credits

Brought to you by Imarc