civix (legacy)
Add a custom search¶
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.
Copying an existing 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.
Using your search¶
- Disable and re-enable your extension.
- Go to Search > Custom Searches... and find your new custom search listed at the bottom.
Building your custom search¶
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 {
return;
}