Skip to content

Hooks Introduction

Overview

Hooks are a common way to extend systems. Let's say you want to send a message to someone in your organization every time a contact is created. An easy way to do this would be to insert code to send the message in the CiviCRM core code right where the contact is created. However, as soon as we upgrade to a newer version all this code will be overwritten. This is where hooks come in to save the day.

At key points in processing - for example saving something to the database - CiviCRM checks to see whether you've "hooked in" some custom code, and runs any valid code it finds.

Hooks allow you to do this by defining a function with a specific name and adding it to your organisation's CiviCRM installation. The name of the function indicates the point at which CiviCRM should call it. CiviCRM looks for appropriate function names and calls the functions whenever it performs the indicated operations.

Hooks are a powerful way to extend CiviCRM's functionality, incorporate additional business logic, and even integrate CiviCRM with external systems. Many CiviCRM developers find themselves using them in nearly every customization project.

Tip

A good test for whether or not to use a hook is to ask yourself whether what you're trying to do can be expressed with a sentence like this: "I want X to happen every time someone does Y."

Usage

There are two ways to use hooks: the traditional method and the Symfony events method.

Traditional method

The traditional method of using a hook is to create a function with a specific name such as:

function myextension_civicrm_buildForm($formName, &$form) {
  // do something
}

This works well in many cases but has its limitations. For example, if two extensions call the same hook there is no way to determine which runs first.

For details, see Traditional Hooks

Symfony method

A newer method that provides greater flexibility is to use Symfony events.

For example:

Civi::dispatcher()->addListener('hook_civicrm_buildForm', "myextension_buildForm", $priority);

function myextension_buildForm($event) {
  // do something
}

For more details see Hooks with Symfony

Targeting Certain Events

When you create a hook, it will be called for all the types of entities. For instance, a civicrm_post is called after the creation or modification of any object of any type (contact, tag, group, activity, etc.). But usually, you want to launch an action only for a specific type of entity.

So a hook generally starts with a test on the type of entity or type of action. For instance, if you want to act only when an address was edited, start your civicrm_post hook with:

if ($objectName != "Address" || $op != "edit") {
  return;
}

Pitfalls of Hooks

Because you have little control over what CiviCRM passes to your hook function, it is very helpful to look inside those objects (especially $objectRef) to make sure you're getting what you expect.

While the hook contract specifies what arrays and objects will be passed out to your hook the arrays and objects themselves may not be subject to an explicit contract and could change over time. Where values are documented in the hook documnetation or you are using functions that have been given the docblock annotation @api you should have more certainty. In general, however, you are advised to ensure your custom code has unit tests.

Supported form functions (these will not change in minor versions but they might become available across more forms)

Function Used to Version
getSubmittedValue() get a single submitted value (processed for money formatting) 5.50-ish?
getSubmittedValues() get all submitted values 5.50-ish?
getSubmittableValues() get all available submitted values 5.50-ish?
getAuthenticatedContactID() All Get the id of the user authenticated by login or checksum
getEventID() Get the Event ID in play 5.66+
getEventValue() ---- 5.66ish?
getDiscountID() Get the Discount ID (civicrm_discount.id) in play 5.66+
getPriceSetID() ---- 5.66+
getParticipantID() ---- 5.66+
getParticipantValue() ---- 5.66ish?
getEventValue() ---- 5.66ish?
getContributionPageID() ---- 5.66ish?
getContributionPageValue() ---- 5.66ish?
getContactID() ---- 5.66+
isTest() ---- 5.69 added to contribution page flow
getLineItems() ---- 5.69 added to contribution page flow
setLineItems() ---- 5.69 added to contribution page flow

A good debugger is indispensable here. See the page on debugging for more information on setting up a debugger for your development environment.

Warning

From time to time a new release of CiviCRM can deprecate or change certain hooks. Keep this in mind when upgrading, and make sure you check the release notes before upgrading.

Packaging Hooks

Hooks are packaged in CMS-agnostic extensions.

Organizing Your Hooks

You may find that some of your hooks target a lot of different cases. Such hooks can quickly get out of control, and maintaining them can be a nightmare.

You might find it helpful when implementing a hook to delegate certain operations to different functions instead of lumping it all in together in the main hook.

If you're using Civix to create your extension it will automatically generate wrapper code for your hook.