This is an overview list of all available hooks and the event listeners that are supported for use outside of core. Any event listeners not listed here are not supported for use outside of core & could change without notice
- hook_civicrm_batchItems - called when a CSV batch export file is about to be generated.
- hook_civicrm_batchQuery - called when the query of CSV batch export is generated.
- hook_civicrm_caseChange - fires whenever a record in a case changes.
- hook_civicrm_caseEmailSubjectPatterns - called when getting case email subject patterns.
- hook_civicrm_caseTypes - defines available case types.
- hook_civicrm_post_case_merge - called after a case merge happens.
- hook_civicrm_pre_case_merge - called before a case merge happens.
- hook_civicrm_alterLocationMergeData - allows you to alter the location information that will be moved from the duplicate contact to the master contact.
- hook_civicrm_copy - called after a CiviCRM object (Event, ContributionPage, Profile) has been copied.
- hook_civicrm_custom - called after the database write on a custom table.
- hook_civicrm_customPre - called before the database write on a custom table.
- hook_civicrm_managed - allows a module to declare a list of managed entities using the API.
- hook_civicrm_merge - allows modification of the data used to perform merging of duplicates. It can be useful if your custom module has added its own tables related to CiviCRM contacts. !!! note If your extension has registered entities that have contact ID foreign keys defined correctly in their schema XML, these entities will be automatically handled by the merge process so you don’t need to implement this hook unless you need to do something fancy.
- hook_civicrm_post - called after a db write on some core objects.
- hook_civicrm_postCommit - called after the DB commits changes (for certain objects).
- hook_civicrm_postSave_table_name - called after writing to a database table that has an associated DAO, including core tables but not custom tables or log tables.
- hook_civicrm_pre - called before a db write on some core objects.
- hook_civicrm_referenceCounts - called to determine the reference-count for a record.
- hook_civicrm_triggerInfo - allows you to define MySQL triggers.
- hook_civicrm_dupeQuery - called during the dedupe lookup process, and can be used to alter the parameters and queries used to determine if two contacts are duplicates.
- hook_civicrm_findDuplicates - called when contacts are added/updated via profiles, event registration pages, contribution pages etc. When a form is submitted CiviCRM checks if a contact already exists using one of the built-in deduplication rules and returns a contact ID if a match is found. allows you to override the contact matching rules to implement more complex rules.
- hook_civicrm_entityTypes - used to declare a new type of entity, for example a booking extension might want to declare a Resource entity.
Extension Lifecycle Hooks¶
- hook_civicrm_disable - called when an extension is disabled.
- hook_civicrm_enable - called when an extension is re-enabled.
- hook_civicrm_install - called when an extension is installed.
- hook_civicrm_postInstall - called immediately after an extension is installed.
- hook_civicrm_uninstall - called when an extension is uninstalled.
- hook_civicrm_upgrade - called when an administrator visits the "Manage Extensions" screen to determine if there are any pending upgrades.
- hook_civicrm_alterAngular - alters the definition of some AngularJS HTML partials and allows you to inject AngularJS changesets.
- hook_civicrm_alterContent - invoked after all the content of a CiviCRM form or page is generated and allows for direct manipulation of the generated content.
- hook_civicrm_alterTemplateFile - invoked while selecting the tpl file to use to render the page.
- hook_civicrm_buildForm - invoked when building a form. It can be used to set the default values of a form element, to change form elements attributes, and to add new fields to a form.
- hook_civicrm_idsException - allows you to modify the list of form or page paths where submitted data should not be sent through PHPIDS, the intrusion detection system (IDS).
- hook_civicrm_postProcess - invoked when a CiviCRM form is submitted.
- hook_civicrm_preProcess - can be used to modify the behavior of a form before the
hook_civicrm_validate- (Removed) invoked during all CiviCRM form validation. An array of errors detected is returned. Else we assume validation succeeded.
- hook_civicrm_validateForm - allows you to customize the logic used to validate forms.
- hook_civicrm_activeTheme - The activeTheme hook determines which theme is active.
- hook_civicrm_alterBundle - Specify the content of a resource bundle (JS/CSS/etc).
- hook_civicrm_alterCustomFieldDisplayValue - allows modification of custom field value for an entity eg Individual, Contribution etc before its displayed on screen. This might be useful if you want to alter the value of the custom field that's being displayed on the screen based on some condition.
- hook_civicrm_alterEntityRefParams - called when an
entityReffield is rendered in a form, which allows you to modify the parameters used to fetch options for this kind of field.
- hook_civicrm_alterMenu - called when building CiviCRM's list of HTTP routes and should be used when you want to register custom paths or URLS.
- hook_civicrm_alterAdminPanel - invoked after all the panels and items on Administer CiviCRM screen have been generated and allows for direct manipulation of these items and panels.
- hook_civicrm_buildAmount - called when building the amount structure for a Contribution or Event Page, allowing you to modify the set of radio buttons representing amounts for contribution levels and event registration fees.
- hook_civicrm_caseSummary - called when the manage case screen is displayed, and it allows the injection of label/value pairs which are rendered inside divs underneath the existing summary table.
- hook_civicrm_contact_get_displayname - called when retrieving the display name of a contact, allowing you to alter it and return a custom display name.
hook_civicrm_customFieldOptions- Deprecated in 4.7 in favor of hook_civicrm_fieldOptions. Use that instead for modifying all option lists, not limited to custom fields.
- hook_civicrm_dashboard - called when rendering the dashboard page and can be used to add content to the dashboard page.
- hook_civicrm_dashboard_defaults - called while a contact views their dashboard for the first time and can be used to enable or disable the set of default dashlets.
- hook_civicrm_entityRefFilters - called when filters and create links for entityRef field is build.
- hook_civicrm_fieldOptions - allows you to dynamically modify the option list for any field (including custom fields).
- hook_civicrm_links - allows you to modify action links including: the actions at the end of a search result row, the Create New dropdown, and the Actions dropdown at the top of a contact record.
- hook_civicrm_navigationMenu - called after the menus are rebuilt.
- hook_civicrm_pageRun - called before a CiviCRM page is rendered.
- hook_civicrm_searchColumns - called after a search is done, allowing you to modify the headers and/or the values that are displayed as part of the search.
- hook_civicrm_searchTasks - called to display the list of actions allowed after doing a search, allowing you to inject additional actions or to remove existing actions to legacy style searches. For SearchKit searches use
- hook_civicrm_searchKitTasks - called to allow you to add to or alter the tasks available in search kit.
- hook_civicrm_summary - called when the contact summary is rendered, allowing you to modify the summary with your own content.
- hook_civicrm_summaryActions - allows you to customize the context menu actions on the Contact Summary Page.
- hook_civicrm_themes - called when building a list of available themes for use within CiviCRM.
hook_civicrm_tabs- deprecated in 4.7 & removed in 5.31 in favor of hook_civicrm_tabset.
- hook_civicrm_tabset - called when composing the tabs interface used for contacts, contributions and events.
- hook_civicrm_xmlMenu - called when building CiviCRM's menu structure, which is used to render urls in CiviCRM.
- hook_civicrm_importAlterMappedRow - allows an import row to be adjusted, after the user configuration has been interpreted into an apiv4-ready format. It is called twice. The first time the usage is
validateand the second time the usage is
import. In the validate usage you should avoid doing any db lookups or anything resource intensive. Validate mode is intended for a quick pass before presenting the preview screen. For the
importusage you can do more intensive lookups and change the data if needed.
hook_civicrm_import- deprecated. The description below may be unreliable. We are working to replace it with
hook_civicrm_importAlterMappedRowcalled after contacts have been imported into the system, and before the temp import table has been destroyed.
- hook_civicrm_alterMailContent - called after getting the content of the mail and before tokenizing it.
- hook_civicrm_alterMailer - called when CiviCRM prepares an email driver class to handle outbound message delivery.
- hook_civicrm_alterMailParams - called when an email is being prepared for sending by CiviCRM. It is also called when downloading or emailing PDF invoices and receipts from the route,
- hook_civicrm_alterMailStore - Add or modify email storage drivers (IMAP, POP3, etc).
- hook_civicrm_alterMailingRecipients - called to allow the user to alter the mailing recipients after they have been constructed.
- hook_civicrm_emailProcessor - called after each email has been processed by the script
- hook_civicrm_emailProcessorContact - called by the Email Processor when deciding which contact to create an activitity for recording an inbound email.
- hook_civicrm_mailingGroups - called when composing a mailing allowing you to include or exclude other groups as needed.
- hook_civicrm_mailSetupActions - Register special actions for setting up new mail accounts.
- hook_civicrm_postEmailSend - called when an email has been successfully sent by CiviCRM, but not on an error.
- hook_civicrm_postMailing - called at the successful completion of a bulk mailing done through CiviMail.
- hook_civicrm_unsubscribeGroups - called when CiviCRM receives a request to unsubscribe a user from a mailing.
- hook_civicrm_alterCalculatedMembershipStatus - called when calculating the membership status.
- hook_civicrm_membershipTypeValues - called when composing the array of membership types and their costs during a membership registration (new or renewal).
- hook_civicrm_aclGroup - called when composing the ACL to restrict access to civicrm entities (civicrm groups, profiles and events).
- hook_civicrm_aclWhereClause - called when composing the ACL where clause to restrict visibility of contacts to the logged in user. !!! note "Only for Contacts" For all other entities use hook_civicrm_selectWhereClause.
- hook_civicrm_alterApiRoutePermissions - called when API version 4 permissions are checked. Note that this does not apply to API version 3.
- hook_civicrm_alterAPIPermissions - called when API version 3 permissions are checked. Note that this does not apply to API version 4.
- hook_civicrm_invalidateChecksum - allows you to invalidate contact checksums (see https://docs.civicrm.org/user/en/latest/common-workflows/tokens-and-mail-merge/#checksum). It does NOT allow marking a checksum as valid because it could easily open up a security hole - e.g. it could inadvertently allow access to data it shouldn't, especially if multiple extensions implement the hook.
hook_civicrm_notePrivacy- !!! warning "Deprecation Notice" deprecated. It will be removed in a future version. called after one or more notes is loaded from the database. It is called once per note, to allow the note to be programmatically hidden. It is now deprecated in favor of hook_civicrm_selectWhereClause.
- hook_civicrm_permission - called to allow custom permissions to be defined.
- hook_civicrm_permission_check - called to dynamically alter permissions based on conditions or external criteria.
- hook_civicrm_permissionList - enumerates special or external permissions, making them available for use in CiviCRM configuration.
- hook_civicrm_selectWhereClause - allows the permission (ACL) clause of a SELECT query to be altered. It is called for all API-based queries (e.g. SearchKit) but not all legacy queries (e.g. search, report). !!! note "Not for Contacts" For Contact ACLs use hook_civicrm_aclWhereClause.
- hook_civicrm_buildProfile - called while preparing a profile form. This form allows for extension authors to add various scripts onto the profile pages. Note that
hook_civicrm_buildFormis not fired for profile pages.
- hook_civicrm_buildUFGroupsForModule - called when ufgroups (profiles) are being built for a module.
- hook_civicrm_processProfile - called when processing a valid profile form submission (e.g. for "civicrm/profile/create" or "civicrm/profile/edit").
- hook_civicrm_searchProfile - called while preparing a list of contacts (based on a profile).
- hook_civicrm_validateProfile - called while validating a profile form submission.
- hook_civicrm_viewProfile - called while preparing a read-only profile screen.
- hook_civicrm_queueActive - Hook to inform background queue processor not to process items. called when a background process attempts to claim an item from the queue to process. A hook could alter the status from 'active' to denote that the server is busy & hence no item should be claimed and processed at this time.
- hook_civicrm_queueRun - .
- hook_civicrm_queueStatus - # hook_civicrm_QueueStatus.
- hook_civicrm_queueTaskError - allows for the modification of how a queue task Error is handled.
- hook_civicrm_alterReportVar - used to add or modify display columns and filters.
- hook_civicrm_inboundSMS - called when an inbound SMS has been received, processed by the provider extension, but not matched or processed by CiviSMS.
Scheduled Job / cron Hooks¶
- hook_civicrm_cron - called every time the CiviCRM scheduler is polled.
- hook_civicrm_preJob - called before a scheduled job is executed.
- hook_civicrm_postJob - called after a scheduled job is executed or was interrupted by an exception.
- civi.token.eval - This event is dispatched when evaluating tokens.
- civi.token.list - This event is dispatched when listing tokens.
hook_civicrm_tokens- called to allow custom tokens to be defined. hook_civicrm_tokenValues- called to get all the values for the tokens registered.
- hook_civicrm_alterBadge - allows you to modify the content and format of name badges.
- hook_civicrm_alterBarcode - allows you to modify the content that is encoded in barcode.
- hook_civicrm_alterExternUrl - allows you to modify extern urls such as click tracking, tracked opens urls.
- hook_civicrm_alterLogTables - allows you to amend the specification of the log tables to be created when logging is turned on.
- hook_civicrm_alterMailingLabelParams - called to alter the parameters used to generate mailing labels.
- hook_civicrm_alterPaymentProcessorParams - allows you to modify parameters passed to the payment processor.
- hook_civicrm_alterRedirect - called when when the browser is being redirected. This allows extensions to override the destination of an HTTP redirect.
- hook_civicrm_alterSettingsFolders - allows modules and extensions to scan for settings in additional folders.
- hook_civicrm_alterSettingsMetaData - called when Settings have been loaded from the xml. It is an opportunity for hooks to alter the data.
- hook_civicrm_alterUFFIelds - allows for the modification of the available fields that are permissible for use within a profile. This might be useful for when you have an extension that has defined it's own entities or it is seeking to permit a core component that doesn't show up in profiles by default e.g. Grants.
- hook_civicrm_angularModules - generates a list of AngularJS modules and allows you to register additional AngularJS modules. Extensions generated with civix implement this hook by default to automatically scan the extension's
angdirectory for files ending in
- hook_civicrm_apiWrappers - allows you to add, override, or remove methods to be called before and after API calls — and to modify either the parameters or the result of the call.
- hook_civicrm_buildAsset - fires whenever the system builds a semi-dynamic asset.
- hook_civicrm_buildStateProvinceForCountry - called during the ajax callback that is used to build the options that display in the State/Province select widget for a specific country, and can be used to alter the list of State/Province options for particular countries.
- hook_civicrm_check - called by the "System Check" api.
- hook_civicrm_config - called soon after the
CRM_Core_Configobject has been initialized.
hook_civicrm_contactListQuery- Deprecated in favor of hook_civicrm_apiWrappers.
- hook_civicrm_container - modifies the CiviCRM container allowing you to add new services, parameters, extensions, etc.
- hook_civicrm_coreResourceList - called when the list of core js/css resources is about to be processed, giving you the opportunity to modify the list prior to the resources being added, or add your own.
hook_civicrm_crudLink>- removed in 5.33.
- hook_civicrm_crypto - added in 5.33 and allows for extension authors to define more keys and ciphers that are then used in the Crypto Registry.
- hook_civicrm_cryptoRotateKey - When a system administrator changes the cryptographic key used for data-storage, this event fires. Listen to this event to re-encrypt data with the new key.
- hook_civicrm_eventDiscount - allows you to apply a customized discount to an event registration.
- hook_civicrm_export - allows to manipulate or change the output of CSV during export.
- hook_civicrm_fileSearches - allows you to add a reference to a file search service (e.g. Solr).
- hook_civicrm_geocoderFormat - allows you to manipulate the Address object during geocoding, for instance to extract additional fields from the geocoder's returned XML.
- hook_civicrm_getAssetUrl - called when building a link to a semi-static asset, allowing you to modify the params the asset will be built with.
- hook_civicrm_oauthProviders - generates a list of OAuth providers.
- hook_civicrm_oauthReturn - After a user has approved an OAuth2 grant (in the "authorization code" flow), we may perform additional work.
- hook_civicrm_oauthReturnError - If an OAuth2 grant (in the "authorization code" flow) produces an error, then this hook provides details.
hook_civicrm_optionValues- deprecated in 4.7 in favor of hook_civicrm_fieldOptions.
- hook_civicrm_postIPNProcess - allows you to do custom processing of IPN Data following CiviCRM processing.
- hook_civicrm_queryObjects - called while building the core search query, allowing you to provide your own query objects which alter or extend the core search.
- hook_civicrm_recent - called before storing recently viewed items.
- hook_civicrm_scanClasses - Scan extensions for classes. This allows auto-registration based on code-conventions, interfaces, annotations.
- hook_civicrm_unhandledException - fires when an unhandled exception (fatal error) occurs.