Skip to content

civix (legacy)

You are discouraged from creating new custom searches using this legacy framework. The focus is now on using SearchKit.

If you do add custom searches be sure to add unit tests and run them regularly.

CiviCRM enables developers to define new search forms using customizable SQL logic and form layouts. Use this command to get started:

civix help generate:search

Then you could generate your basic search code for a MySearch class with:

civix generate:search MySearch

This command will create two files:

  • CRM/Myextension/Form/Search/MySearch.mgd.php stores metadata about the custom search. The format of the file is based on hook_civicrm_managed and the API.
  • CRM/Myextension/Form/Search/MySearch.php contains the form-builder and query-builder for the custom search.

If one of the existing searches is close to meeting your needs you may copy it instead and then customise the PHP, SQL and templates.

To make a new search based on an existing search first determine the name of the original search class within the civicrm/CRM/Contact/Form/Search/Custom directory of CiviCRM source tree. Then run the generate:search command from within your module directory.

For example, the zipcode search is in the class CRM_Contact_Form_Search_Custom_ZipCodeRange, so you can copy it with:

civix generate:search --copy CRM_Contact_Form_Search_Custom_ZipCodeRange MySearch

The "copy" option will create either two or three files depending on whether the original search screen defines its own Smarty template.

  1. Disable and re-enable your extension.
  2. Go to Search > Custom Searches... and find your new custom search listed at the bottom.

Now you have a working custom search, but how do you make it do something custom?

If your search extends anything other than contacts you probably need to add a function to prevent notices like this

  * @param CRM_Utils_Sort $sort
  * @param string $cacheKey
  * @param int $start
  * @param int $end
  * @throws \CRM_Core_Exception
  public function fillPrevNextCache($sort, $cacheKey, $start = 0, $end = self::CACHE_SIZE): void {
See this (extremely outdated) wiki page for more information.