This documentation refers to an older version of CiviCRM (3.4 / 4.0). View latest version.

Skip to end of metadata
Go to start of metadata
This page refers to CiviCRM 3.4 and 4.0, current STABLE version.

Documentation Search


CiviCRM 3.4 and 4.0 Documentation

Support and Participation

Developer Resources


CiviCRM books!

Make sure to check out the FLOSS Manual Understanding CiviCRM as well! You can also support this project by ordering a hard copy.

Or support us by buying an eBook or hard copy of Using CiviCRM from Packt Publishing.

Goals and Background

This documents how to extend CiviCRM to meet your needs. We are extending CiviCRM in a very similar manner to Drupal, primarily because based on our experience with Drupal's extension architecture, we think it is clean and non-intrusive, yet incredibly powerful. For a simple example module check civitest module

See Drupal hook documentation for a description of how hooks are implemented.

See the section on Joomla within this article for a description of how to implement hooks in Joomla.

See CRM/Utils/Hook.php for CiviCRM for the source code that invokes these hooks.

Procedures for implementing hooks (for Drupal)

All your hook implementations should be collected within one or more modules, so to begin create a module:

  • Select a short name for your module (e.g. highschool).
  • Create, e.g.,  highschool.info and highschool.module files, and store them in /sites/all/modules/myCiviModule/ (you can rename the directory"myCiviModule" to something more appropriate).  Once you enable the module(s) in Drupal's Administer panel, Drupal will automagically load it and civiCRM will call any hooks that have the proper suffix (e.g. xxxxxxx_civicrm_postProcess).

Note: the function names in the .module file need to start with the module name, e.g. highschool_civicrm_postProcess

  • For a well-commented, working example of using hooks to store a last modified date when a user clicks the "Save" button on a profile form, see the hook_civicrm_postProcess hook documentation below. You can also find examples in your CiviCRM install in civicrm\drupal\civitest.module.sample
  • Here is an example of a .info file:

Procedures for implementing hooks (for Joomla)

Plugins in the civicrm groups should be used to access hooks in Joomla. Information on Joomla plugin development can be found at http://docs.joomla.org/Plugin. Joomla plugins implement the observer design pattern.

Hook plugins should be placed in the civicrm plugin group in a subfolder with the same name as the plugin..

Once created plugins may be packaged and installed with the Joomla installer or the files can be placed in the appropriate folder and installed with the discover method.

A simple example is given below. It consists of two file tabs.php and tabs.xml along with the blank index.html file which is considered good Joomla coding practice.

Tabs.php:

Tabs.xml

You can make plugins that include multiple hooks or you can make separate plugins. What is appropriate will depend on the application.

Note on setting and getting custom field values in hooks

To get a custom field ID given the custom field name and custom group name, you can use the following code:

For setting and getting custom field values in hooks, you need to know the field ID of the custom field(s) you want to work with. The easiest place to find these IDs is in the civicrm_custom_field table in the database. You'll then access these fields as "custom_ID". So if you have a field holding a custom value whose ID in the civicrm_custom_field table is 34, you'll use "custom_34" to access it.

Once you have the ID(s), you'll want to use the setValues and getValues functions in the CRM/Core/BAO/CustomValueTable.php file. Here are a couple of examples of their use:

Setting values (on a Contribution object's custom fields):

Getting values (from a Contribution's associated Contact object):

Note that custom field values may not always be available when you might expect. For instance, you can't retrieve custom field values in the 'create' operation in the _pre and _post hooks, because the custom field values haven't been stored yet. However, you can retrieve values in the 'edit' operation.

Form related hooks

hook_civicrm_validate

Description

Validation of forms

Definition
Parameters
  • $formName - Name of the form being validated, you will typically switch off this value.
  • $fields - Array of name value pairs for all 'POST'ed form values
  • $files - Array of file properties as sent by PHP POST protocol
  • $form - Reference to the civicrm form object. This is useful if you want to retrieve any values that we've constructed in the form
Returns

true if form validates successfully, otherwise array with input field names as keys and error message strings as values

Example

Beginning in CiviCRM 3.2, from within this hook, you can also manipulate validation errors set by CiviCRM. For example, to unset a validation error triggered by CiviCRM:

hook_civicrm_buildForm

Description

This hook is invoked when building a CiviCRM form. This hook should also be used to set the default values of a form element

Definition
Parameters
  • string $formName - the name of the form
  • object $form - reference to the form object
Returns
Example

To access useful values in your hook_civicrm_buildForm function, consider the following:

hook_civicrm_postProcess

Description

This hook is invoked when a CiviCRM form is submitted. If the module has injected
any form elements, this hook should save the values in the database.

This hook is not called when using the API, only when using the regular forms. If you want to have an action that is triggered no matter if it's a form or an API, use the pre and post hooks instead.

Definition
Parameters
  • string $formName - the name of the form
  • object $form - reference to the form object
Returns
  • null - the return value is ignored
Example

Database related hooks

hook_civicrm_pre

Description

This hook is called before a db write on some core objects. This hook does not allow the abort of the operation, use a form hook instead.

We suspect the pre hook will be useful for developers building more complex applications and need to perform operations before CiviCRM takes action. This is very applicable when you need to maintain foreign key constraints etc (when deleting an object, the child objects have to be deleted first). Another good use for the pre hook is to see what is changing between the old and new data.

Definition
Parameters
  • $op - operation being performed with CiviCRM object. Can have the following values:
    • 'view' : The CiviCRM object is going to be displayed
    • 'create' : The CiviCRM object is created (or contacts are being added to a group)
    • 'edit' : The CiviCRM object is edited
    • 'delete' : The CiviCRM object is being deleted (or contacts are being removed from a group)
  • $objectName - can have the following values:
    • 'Individual'
    • 'Household'
    • 'Organization'
    • 'Address'
    • 'Group'
    • 'GroupContact'
    • 'Relationship'
    • 'Contribution'
    • 'Profile' (while this is not really an object, people have expressed an interest to perform an action when a profile is created/edited)
    • 'Membership'
    • 'Event'
    • 'Participant'
    • 'UFMatch' (when an object is linked to a CMS user record, at the request of GordonH. A UFMatch object is passed for both the pre and post hooks)
    • PledgePayment
    • ContributionRecur
    • Pledge
    • CustomGroup

**

  • $id is the unique identifier for the object if available
  • &$params are the parameters passed
Returns
  • None
Example

hook_civicrm_post

Description

This hook is called after a db write on some core objects.

pre and post hooks are useful for developers building more complex applications and need to perform operations before CiviCRM takes action. This is very applicable when you need to maintain foreign key constraints etc (when deleting an object, the child objects have to be deleted first).

Definition
Parameters
  • $op - operation being performed with CiviCRM object. Can have the following values:
    • 'view' : The CiviCRM object is going to be displayed
    • 'create' : The CiviCRM object is created (or contacts are being added to a group)
    • 'edit' : The CiviCRM object is edited
    • 'delete' : The CiviCRM object is being deleted (or contacts are being removed from a group)
  • $objectName - can have the following values:
    • 'Individual'
    • 'Household'
    • 'Organization'
    • 'Group'
    • 'GroupContact'
    • 'Relationship'
    • 'Activity'
    • 'Contribution'
    • 'Profile' (while this is not really an object, people have expressed an interest to perform an action when a profile is created/edited)
    • 'Membership'
    • 'Participant'
    • 'UFMatch' (when an object is linked to a CMS user record, at the request of GordonH. A UFMatch object is passed for both the pre and post hooks)
    • 'Event'
    • 'EntityTag'
    • 'Tag'
    • PledgePayment
    • ContributionRecur
    • Pledge
  • $objectId - the unique identifier for the object. tagID in case of EntityTag
  • $objectRef - the reference to the object if available. For case of EntityTag it is an array of (entityTable, entityIDs)
Returns
  • None
Example

Here is a simple example that will send you an email whenever an INDIVIDUAL Contact is either Added, Updated or Deleted:

Create a new folder called example_sendEmailOnIndividual in this directory /drupal_install_dir/sites/all/modules/civicrm/drupal/modules/ and then put the following two files in that directory (change the email addresses to yours).

FILE #1 /drupal_install_dir/sites/all/modules/civicrm/drupal/modules/example_sendEmailOnIndividual/example_sendEmailOnIndividual.info
FILE #2 /drupal_install_dir/sites/all/modules/civicrm/drupal/modules/example_sendEmailOnIndividual/example_sendEmailOnIndividual.module

Once the files are in the directory, you need to login to Drupal admin, go to Modules and enable our new module and click Save. Now go and edit a contact and you should get an email!

hook_civicrm_custom

Description

This hook is called AFTER the db write on a custom table

Definition
Parameters
  • string $op - the type of operation being performed
  • string $groupID - the custom group ID
  • object $entityID - the entityID of the row in the custom table
  • array $params - the parameters that were sent into the calling function
Returns
  • null - the return value is ignored
Example

hook_civicrm_copy

Description

This hook is called after a CiviCRM object (Event, ContributionPage, Profile) has been copied

Definition
Parameters
  • $objectName - the name of the object that is being copied (Event, ContributionPage, UFGroup)
  • $object - reference to the copied object
Returns
  • null

Permission related hooks

hook_civicrm_aclWhereClause

Description

This hook is called when composing the ACL where clause to restrict visibility of contacts to the logged in user.

NB: This function will not be called at all if the logged in user has access to the "edit all contacts" permission.

Definition
Parameters
  • $type - type of permission needed
  • array $tables - (reference ) add the tables that are needed for the select clause
  • array $whereTables - (reference ) add the tables that are needed for the where clause
  • int $contactID - the contactID for whom the check is made
  • string $where - the currrent where clause
Returns
  • null - the return value is ignored
Example

hook_civicrm_aclGroup

Description

This hook is called when composing the ACL to restrict access to civicrm entities (civicrm groups, profiles and events). NOTE: In order to use this hook you must uncheck "View All Contacts" AND "Edit All Contacts" in Drupal Permissions for the user role you want to limit. You can then go into CiviCRM and grant permission to Edit or View "All Contacts" or "Certain Groups". See the Forum Topic at: http://forum.civicrm.org/index.php/topic,14595.0.html for more information.

Definition
Parameters
  • $type the type of permission needed
  • $contactID the contactID for whom the check is made
  • $tableName the tableName which is being permissioned
  • $allGroups the set of all the objects for the above table
  • $currentGroups the set of objects that are currently permissioned for this contact . This array will be modified by the hook
Returns
  • null - the return value is ignored
Example

Check HRD Module

GUI related hooks

Description

These hooks are used to inject UI into CiviCRM pages such as the Contact Summary page.

Note: remember to use the string & url processing functions of your host framework ( url() and t() for Drupal ).

Definition
Parameters
  • $op = 'view.contact.activity' OR 'view.contact.userDashBoard'
  • $objectName = 'Contact'
  • $objectId -the CiviCRM internal ID of the object (a contact ID.).
  • $links - (optional) the links array to modify in-place
Returns
  • an array of arrays, each element is a tuple consisting of url, title (and depending on the operation some other parameters)
Example

hook_civicrm_dashboard

Description

This hook is called when rendering the dashboard page. This hook can be used to add content to the dashboard page.

Definition
Parameters
  • $contactID the contactID for whom the dashboard is being generated
  • $contentPlacement (output parameter) where should the hook content be displayed relative to the activity list. One of CRM_Utils_Hook::DASHBOARD_BELOW, CRM_Utils_Hook::DASHBOARD_ABOVE, CRM_Utils_Hook::DASHBOARD_REPLACE. Default is to add content BELOW the standard dashboard Activities listing. DASHBOARD_REPLACE replaces the standard Activities listing with the provided content.
Returns
  • the HTML to include in the dashboard
Example

Also check Civitest Sample Module

hook_civicrm_xmlMenu

Description

This hook is called when building CiviCRM's menu structure, which is used to render urls in CiviCRM. This hook should be used when you want to register your custom module url's in CiviCRM. You will need to visit <your_site>/civicrm/menu/rebuild?reset=1 to pick up your additions.

Note: If you just want to register url in top Navigation, you should use hook_civicrm_navigationMenu

Definition
Parameters
  • $files the array for files used to build the menu. You can append or delete entries from this file. You can also override menu items defined by CiviCRM Core.
Returns
  • null

Example

Here's how you can override an existing menu item. First create an XML file like this, and place it in the same folder as your hook implementation:

<?xml version="1.0" encoding="iso-8859-1" ?>
<menu>
  <item>
     <path>civicrm/ajax/contactlist</path>
     <page_callback>CRM_Contact_Page_AJAX::getContactList</page_callback>
     <access_arguments>access CiviCRM AJAX contactlist</access_arguments>
  </item>
</menu>
Drupal developers can define 'my custom permission' using hook_perm . Then create a hook implementation like this:

hook_civicrm_navigationMenu

Description

This hook is called after the menus are rebuild. You can use this hook to add new menu, add children to new menu and get the list of menu items for any parent.

Definition
Parameters
  • $params the navigation menu array

Attributes of the menu :

    1. label : Navigation Title

    2. Name : Internal Name

    3. url : url in case of custom navigation link

    4. permission : comma separated Permissions for menu item

    5. operator : Permission Operator ( AND/OR)

    6. seperator : If separator needs to be added after this menu item.

    7. parentID : Parent navigation item, used for grouping

    8. navID : ID of the menu

    9. active : is active ?

Example

hook_civicrm_pageRun

Description

This hook is called before a CiviCRM page is rendered.

Note that this does not execute on every CiviCRM page in the general sense. CiviCRM's pages are classified as either 'Forms' or 'Pages', and this only runs on pages classified as 'Pages'. If you are not sure if a particular page is a Page, test it by adding some temporary debug code to /CRM/Utils/Hook.php

Definition
Parameters
  • $page the page being rendered
Returns
  • null

hook_civicrm_customFieldOptions

Description

This hook is called when CiviCRM needs to edit/display a custom field with options (select, radio, checkbox, adv multiselect)

Definition
Parameters
  • $fieldID - the custom field ID
  • $options - the current set of options for that custom field. You can add/remove existing options. Important: This array may contain meta-data about the field that is needed elsewhere, so it is important to be careful to not overwrite the array. Only add/edit/remove the specific field options you intend to affect.
  • $detailedFormat - if true, the options are in an ID => array ( 'id' => ID, 'label' => label, 'value' => value ) format
Returns
  • null
Example

This syntax may be more convenient if you are a managing differing sets of options for different fields:

hook_civicrm_summary

Description

This hook is called when contact summary is rendered and you can add on top, below or replace summary with your own html content.

Definition
Parameters
  • $contactID the contactID for whom the contact summary is being generated
  • $contentPlacement (output parameter) where should the hook content be displayed relative to the exiting content. One of CRM_Utils_Hook::SUMMARY_BELOW, CRM_Utils_Hook::SUMMARY_ABOVE, CRM_Utils_Hook::SUMMARY_REPLACE. Default is to add content BELOW default contact summary content.
Example

hook_civicrm_summaryActions (introduced in 4.1)

Description

This hook allows User to customize context menu Actions on Contact Summary Page.

Definition
Parameters
  • $actions Array of all Actions in contextMenu.
  • $contactID contactID for the summary page.
Example

hook_civicrm_searchTasks

Description

This hook is called to display the list of actions allowed after doing a search. This allows the module developer to inject additional actions or to remove existing actions.

Definition
Parameters
  • $objectName - the object for this search - activity, campaign, case, contact, contribution, event, grant, membership, and pledge are supported.
  • $tasks - the current set of tasks for that custom field. You can add/remove existing tasks. Each task needs to have a title (eg 'title'  => ts( 'Add Contacts to Group')) and a class (eg 'class'  => 'CRM_Contact_Form_Task_AddToGroup'). Optional result (boolean) may also be provided. Class can be an array of classes (not sure what that does :( ). The key for new Task(s) should not conflict with the keys for core tasks of that $objectType, which can be found in CRM/$objectType/Task.php.
Returns
  • null
Example

hook_civicrm_searchColumns

Description

This hook is called after a search is done. This allows the developer to modify the headers and/or the values that are displayed as part of this search. The BIGGEST drawback with this hook is that you may need to modify the result template to include your fields. The result files are CRM/{Contact,Contribute,Member,Event…}/Form/Selector.tpl. However, if you use the same number of columns, you can overwrite the existing columns with the values that you want displayed. This is a HACK, but avoids template modification.

Definition
Parameters
  • $objectName - the object for this search - activity, campaign, case, contact, contribution, event, grant, membership, and pledge are supported.
  • $headers - array (reference) - the list of column headers, an associative array with keys: ( name, sort, order )
  • $rows - array (reference) - the list of values, an associate array with fields that are displayed for that component
  • $seletor - array (reference) - the selector object. Allows you access to the context of the search
Returns
  • null
Example

hook_civicrm_buildAmount

Description

This hook is called when building the amount structure for a Contribution or Event Page. It allows you to modify the set of radio buttons representing amounts for contribution levels and event registration fees.

Definition
Parameters
  • $pageType - is this a 'contribution' or 'event'
  • $form - reference to the form object
  • $amount - the amount structure to be displayed
Returns
  • null
Example

hook_civicrm_tabs

Description

This hook is called when composing the tabs to display when viewing a contact

Definition
Parameters
  • $tabs - the array of tabs that will be displayed
  • $contactID - the contactID for whom the view is being rendered
Returns
  • null - the return value is ignored
Example

hook_civicrm_tokens

Description

This hook is called to get all the tokens that can be used

Definitionhook_civicrm_tokens( &$tokens )
Parameters
  • $tokens: reference to the associative array of tokens that are available to be used in mailings and other contexts.
Returns
  • null

hook_civicrm_alterMailingLabelParams

Description

This hook is called to alter the parameters used to generate mailing labels. To be added in CiviCRM 4.1 or later.

Definition
Parameters
  • $args: reference to the associative array of arguments that are about to be used to generate mailing labels
  •  
@param array $args an array of the args for the tcpdf MultiCell api call with the variable names below converted into string keys
  (ie $w become 'w' as the first key for $args).
  If ishtml is set true, then a subset of the args will be passed to the tcdpdf writeHTMLCell api call instead.

float $w Width of cells. If 0, they extend up to the right margin of the page.
float $h Cell minimum height. The cell extends automatically if needed.
string $txt String to print
mixed $border Indicates if borders must be drawn around the cell block. The value can
be either
  a number:
    0: no border (default)
    1: frame or
  a string containing some or all of the following characters (in any order):
    L: left
    T: top
    R: right
    B: bottom
string $align Allows to center or align the text. Possible values are:
  L or empty string: left align
  C: center
  R: right align
  J: justification (default value when $ishtml=false)
int $fill Indicates if the cell background must be painted (1) or transparent (0). Default value: 0.
int $ln Indicates where the current position should go after the call. Possible values are:
  0: to the right
  1: to the beginning of the next line DEFAULT
  2: below
float $x x position in user units
float $y y position in user units
boolean $reseth if true reset the last cell height (default true).
int $stretch stretch carachter mode:
  0 = disabled
  1 = horizontal scaling only if necessary
  2 = forced horizontal scaling
  3 = character spacing only if necessary
  4 = forced character spacing
boolean $ishtml set to true if $txt is HTML content (default = false).
boolean $autopadding if true, uses internal padding and automatically adjust it to account for line width.
float $maxh maximum height. It should be >= $h and less then remaining space to the bottom of the page,
 or 0 for disable this feature. This feature works only when $ishtml=false.

NB: not all html tags are supported, not all style parameters are supported, and improperly constructed html tends to lead to errors and crashes.

Returns
  • null
Example

hook_civicrm_alterPaymentProcessorParams

Description

This hook is called during the processing of a contribution after the payment processor has control, but just before the CiviCRM processor specific code starts a transaction with the back-end payments server (e.g., PayPal, Authorized.net, or Moneris). It allows you to modify the parameters passed to the back end so that you can pass custom parameters, or use features of your back-end that CiviCRM does not "know" about.

Definition
Parameters
  • $paymentObj - instance of payment class of the payment processor invoked
  • $rawParams - the associative array passed by CiviCRM to the processor
  • $cookedParams - the associative array of parameters as translated into the processor's API.
Returns
Example

hook_civicrm_tokenValues

Description

This hook is called to get all the values for the tokens registered. For a good overview of usage, see lobo's blog.

Definition
Parameters
  • $details - array of contactID details
  • $contactIDs - either a single contactID or an array of contactIDs that the system needs values for.
Returns
  • null

hook_civicrm_mailingGroups

Description

This hook is called when composing a mailing. You can include / exclude other groups as needed.

Definition
Parameters
  • $form - the form object for which groups / mailings being displayed
  • $groups - the list of groups being included / excluded
  • $mailings - the list of mailings being included / excluded
Returns
  • null - the return value is ignored
Example

hook_civicrm_contactListQuery

Description

Use this hook to populate the list of contacts returned by Contact Reference custom fields. By default, Contact Reference fields will search on and return all CiviCRM contacts. If you want to limit the contacts returned to a specific group, or some other criteria - you can override that behavior by providing a SQL query that returns some subset of your contacts. The hook is called when the query is executed to get the list of contacts to display.

Definition
Parameters
  • $query - the query that will be executed (input and output parameter); It's important to realize that the ACL clause is built prior to this hook being fired, so your query will ignore any ACL rules that may be defined. Your query must return two columns:
    • the contact 'data' to display in the autocomplete dropdown (usually contact.sort_name - aliased as 'data')
    • the contact IDs
  • $name - the name string to execute the query against (this is the value being typed in by the user)
  • $context - the context in which this ajax call is being made (for example: 'customfield', 'caseview')

    To find the context for a given contactListQuery widget, use firebug console and type in a few letters. You'll see a GET command that looks like this (and includes the context= parameter):http://drupal.demo.civicrm.org/civicrm/ajax/contactlist?context=caseview&s=ada&limit=10&timestamp=1273015964778

  • $id - the id of the object for which the call is being made. For custom fields, it will be the custom field id
Example

This example limits contacts in my contact reference field lookup (custom field id=4) to a specific group (group id=5)

hook_civicrm_membershipTypeValues

Description

This hook is called when composing the array of membershipTypes and their cost during a membership registration (new or renewal). Note the hook is called on initial page load and also reloaded after submit (PRG pattern). You can use it to alter the membership types when first loaded, or after submission (for example if you want to gather data in the form and use it to alter the fees).

Definition
Parameters
  • $form the form object that is presenting the page
  • $membershipTypeValues the array of membership types and their amount
Examples

Give a 50% discount to some memberships in the sample data

Modify specific fee values

hook_civicrm_alterMailParams

Description

This hook is called when an email is about to be sent by CiviCRM.

Definition
Parameters
  • $params the mailing params
Details
  • $params array fields include: groupName, from, toName, toEmail, subject, cc, bcc, text, html, returnPath, replyTo, attachments (array)
  • If you want to abort the mail from being sent, set the boolean abortMailSend to true in the params array

hook_civicrm_caseSummary

Description

This hook is called when the manage case screen is displayed. It allows the injection of label/value pairs which are rendered inside divs underneath the existing summary table.

Definition
Parameters
  • string $caseID - the case ID
Returns
  • array - an array where the key is a custom id that can be used for CSS styling the div and the value is an array with 'label' and 'value' elements.
Example

hook_civicrm_config

Description

This hook is called soon after the CRM_Core_Config object has ben initialized. You can use this hook to modify the config object and hence behavior of CiviCRM dynamically.

Definition
Parameters
  • $config the config object
Example

hook_civicrm_merge

Description

This hook allows modification of the data used to perform merging of duplicates. This can be useful if your custom module has added its own tables related to CiviCRM contacts.
Always implement this hook when storing contact ids in a custom table, otherwise your table may get out-of-sync with the CiviCRM database as contacts are merged and contact_ids change.

Availability

This hook was first available in CiviCRM 3.2.3.

Definition
Parameters
  • $type the type of data being passed (cidRefs|eidRefs|relTables|sqls)
  • $data the data, which depends on the value of $type (see Details)
  • $mainId contact_id of the contact that survives the merge (only when $type == 'sqls')
  • $otherId contact_id of the contact that will be absorbed and deleted (only when $type == 'sqls')
  • $tables when $type is "sqls", an array of tables as it may have been handed to the calling function
Details

The contents of $data will vary based on the $type of data being passed:

  • 'relTables':
    • an array of tables used for asking user which elements to merge, as used at civicrm/contact/merge; each table in the array has this format:
  • 'sqls':
    • a one-dimensional array of SQL statements to be run in the final merge operation;
    • These SQL statements are run within a single transaction.
  • 'cidRefs':
    • an array of tables and their fields referencing civicrm_contact.contact_id explicitely;
    • each table in the array has this format:
  • 'eidRefs':
    • an array of tables and their fields referencing civicrm_contact.contact_id with entity_id;
    • each table in the array has this format:
Example 1 - Modifying the query
Example 2 - Using Drupal to update custom tables

hook_civicrm_export

Description

This hook allows to manipulate or change the output of CSV during export.

Availability

This hook was first available in CiviCRM 3.2.4

Definition
Parameters
  • @param string $exportTempTable - name of the temporary export table used during export
  • @param array $headerRows - header rows for output
  • @param array $sqlColumns - SQL columns
  • @param int $exportMode - export mode ( contact, contribution, etc...)
Details
Example

hook_civicrm_emailProcessor

Description

This hook is called AFTER EACH email has been processed by the script bin/EmailProcessor.php

Definition
Parameters
  • @param string $type type of mail processed: 'activity' OR 'mailing'
  • @param array &$params the params that were sent to the CiviCRM API function
  • @param object $mail the mail object which is an ezcMail class
  • @param array &$result the result returned by the api call
  • @param string $action (optional ) the requested action to be performed if the types was 'mailing'
Returns
  • null
Availability

This hook was first available in CiviCRM 3.4.0

hook_civicrm_import

Description

This hook is called after contacts have been imported into the system, and before the temp import table has been destroyed. It can be used to take custom action on the imported records or handle special columns in the import file. It currently is only applicable to contact import, but in future versions may extend to other objects.

Definition
Parameters
  • @param string  $object     - object being imported (for now Contact only, later Contribution, Activity, Participant and Member)
    @param string  $object     - object being imported (for now Contact only, later Contribution, Activity, Participant and Member)
  • @param string  $usage      - hook usage/location (for now process only, later mapping and others)
  • @param string  $objectRef  - import record object
  • @param array   $params     - array with various key values: currently
                             contactID       - contact id
                             importID        - row id in temp table
                             importTempTable - name of tempTable
                             fieldHeaders    - field headers
Returns
  • null
Availability
  • This hook was first available in CiviCRM 3.4.1
Example

hook_civicrm_alterAPIPermissions

Description

This hook is called when API 3 permissions are checked and can alter the $permissions structure from CRM/Core/DAO/.permissions.php (as well as the API $params array) based on the $entity and $action (or unconditionally).

Note that if a given entity/action permissions are unset, the default ‘access CiviCRM’ permission is enforced.

Definition
Parameters
  • string $entity the API entity (like contact)
  • string $action the API action (like get)
  • array &$params the API parameters
  • array &$permisisons the associative permissions array (probably to be altered by this hook)
Returns
  • null
Availability
  • This hook was first available in CiviCRM 3.4.1
Example

hook_civicrm_dupeQuery

Description

This hook is called during the dedupe lookup process, and can be used to alter the parameters and queries used to determine if two contacts are duplicates.

The dedupe mechanism is triggered in four places:

  1. when a CMS user account is created and connected to an existing or new CiviCRM contact;
  2. during contact imports, where the incoming file records are compared with the existing database;
  3. when a contact record is created through the interface; and
  4. when a find duplicate contacts rule is run (comparing a group of contacts or the entire database with itself).

Using the hook parameters, you can isolate how and when your rule modifications are used.

Note that this hook depends upon the existence of a dedupe rule created in the interface in order for it to be called. It works by allowing access to the queries constructed by an interface-create rule.You can modify or completely replace the query or queries that would be run at the point the hook is called, as illustrated below.

You cannot define rule groups with this hook.

Definition
Parameters
  • @param string $obj object of rulegroup class
  • @param string $type type of queries e.g table / threshold (I'm pretty sure these correspond to strict and fuzzy in the UI)
  • @param array  $query set of queries
  • @access public
Returns
  • null
Availability
  • Available since 3.3
Example

The example below rewrites the queries for the individual rule group entitled "My Dedupe Rule Group Name" when performing site-wide deduping. It combines six fields into a single query, thus speeding up the duplicate search process.

hook_civicrm_buildStateProvinceForCountry

Description

This hook is 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.

Definition
Parameters
  • @param string $countryID Country ID for which State/Province data is being looked up
  • @param array $states array of State/Province data relating to country being looked up (keys = State/Province ID, values = State/Province name)
Returns
  • null
Availability
  • Available since 4.1
Example

The example below reorders the Irish State list so that Dublin is at the top of the list (by default, Dublin would be placed in the list in alphabetical order.

Obsolete hooks

hook_civicrm_shortcuts

Description

This hook is obsoleted in CiviCRM v3.2.4 in favor of hook_civicrm_links ( For more details check hook_civicrm_links documentation )

Labels
  • None