-
Seamus Lee authoredSeamus Lee authored
- API changes
- APIv3: Framework
- 5.8 Support for Extension Examples in the API Explorer.
- 5.0 Support for custom data on any entity via the api
- 5.0 Support for Serialization Metadata
- 4.7.17: OR Operator
- 4.7.13: Standardized output of EntityTag api
- 4.7.11: Added generic action 'validate'
- 4.7.0: Support for joins across multiple entities
- 4.7.0: New hook_civicrm_selectWhereclause
- 4.7.0: REST XML format
- 4.7.0: Permission changes
- 4.7.0: Searching on custom fields now works for all entity types
- 4.6.7 Multi-select custom field are always returned as numerical indexed arrays
- 4.6.7: Fixes for chained calls
- 4.6.0: 'setvalue' api action deprecated
- 4.6.0: Added 'force_rollback' option
- 4.5.0: Added 'getrefcount' action
- 4.5.0: Added 'getlist' action
- 4.4.5: Added client-side CRM.api3() wrapper
- 4.4.0: 'getoptions' action accepts additional params related to context
- 4.4.0: 'getoptions' action respects 'sequential' param
- 4.4.0: 'create' action accepts 'options.reload=1'
- 4.4.0: 'create' and 'replace' actions accept 'options.match' or 'options.match-mandatory'
- 4.4.0: Smarty wrapper defaults to 'sequential'
- 4.3.0: New 'getoptions' action
- 4.3.0: Deprecating action=update
- 4.3.0: Default permission changed from "access CiviCRM" to "administer CiviCRM"
- 4.3.0: AJAX: cj().crmAPI() is now CRM.api()
- 4.3.0: REST: user/password authentication unsupported
- 4.3.5 / 4.2.10: Introduction of civicrm_api3 wrapper
- APIv3: Specific APIs (Changes)
- 4.7.25: Event API. price_set_id not returned unless specified.
- 4.7.20/4.7.13 : Extensions API Get. All Information on Extensions is returned by default
- 4.7.11: Group API: "group_type" is supported for both integer and array values
- 4.7.0: GroupContact API
- 4.6.0: Mailing API
- 4.6.0: Mailing Component API
- 4.5.0: Case API: "case_type" corresponds to machine-name
- 4.4.0: Activity API Changes
- 4.3.0: Deprecate Constant API
- 4.3.0: Contact get API now respects ACLS
- 4.3.0: Contribution API creates line items
- 4.3.0: Create events from a template
- APIv3: Specific APIs (Additions)
- 4.7.15 StateProvince API
- 4.7.7 System.updatelogtables
- 4.7.0: EntityBatch, SavedSearch, OpenId
- 4.7.0: GroupContact API accepts array of contact_id or group_id
- 4.7.0: StatusPreference API
- 4.6.0: Attachment API
- 4.6.0: Mailing AB API
- 4.5.0: contribution_page.submit action
- 4.5.0: CaseType API
- 4.4.8: FinancialType, FinancialAccount, ActivityContact API
- 4.4.?: Dashboard API -- Enable developers to register new dashlets
- 4.4.?: DashboardContact API -- Enable developers to assign dashlets to the dashboard for particular users
- 4.4.2: ActionSchedule API (Scheduled Reminders)
- 4.4.0 Profile submit & getfields api
- 4.4.0: Soft Credits API
- 4.4.0: Mailing Contact API
- 4.4.0: Report Instance API
- 4.3.4 / 4.2 LTS Contribution.completetransaction action (like an IPN)
- 4.3.0: Location Type API
- 4.3.0: Mailing API
- 4.3.0 / 4.2.10: Setting API
- 4.3.0: Job API
- 4.3.0: Payment Processor API
- 4.3.0: LocBlock API
- Object-Oriented APIs
- 4.3.0: CRM_Contact_Form_Search_Interface::all
- 4.6.0: CRM_Contact_Form_Search_Interface->buildTaskList
- Hooks
- 4.7.14 hook_civicrm_pre & hook_civicrm_post supports CustomField
- 4.7.0 hook_civicrm_tabs deprecated
- 4.7.0 hook_civicrm_validate removed
- 4.5.0: hook_civicrm_enableDisable removed
- 4.5.0: hook_civicrm_referenceCounts
- 4.4.0: Add hooks for profile forms
- 4.4.0: hook_civicrm_searchColumns: Change of $values in profile-listings
- 4.4.0: hook_civicrm_buildUFGroupsForModule: Change to $ufGroups
- Other
- 4.7.0: CRM_Core_Config: Property loading
- 4.7.0: Global $civicrm_setting: Multiple changes
- 4.7.0: bin: Removed deprecated scripts
- 4.6.alpha2: CRM_Core_Payment: Object construction
- 4.6.alpha1: CRM_Core_Transaction
- 4.5.3: AJAX, Regions, and Resources
- 4.5.0: CiviCase: Changes in XML
- 4.4.6, 4.2.17: Profiles: Removed hidden fields
API changes
This page lists changes to CiviCRM core which affect the ways in which developers use the API.
APIv3: Framework
5.8 Support for Extension Examples in the API Explorer.
From 5.8 it is now possible for Extension authors to store examples for their API entities in a folder <extensiondir>/api/v3/examples/<entity>/<file>
in the same structure as is in core. They will now be displayed in the API Explorer just like the core examples.
5.0 Support for custom data on any entity via the api
It is now possible to add any (almost) entity to the cg_group_extends option group and create / retrieve custom data for that field via the api (also custom entities). Ones that do not work as of 5.0 release are
'CaseContact',
'CustomField',
'CustomGroup',
'DashboardContact',
'Domain',
'File',
'FinancialType',
'LocBlock',
'MailingEventConfirm',
'MailingEventResubscribe',
'MailingEventSubscribe',
'MailingEventUnsubscribe',
'MailingJob',
'MembershipPayment',
'SavedSearch',
'UFJoin',
'UFField',
'PriceFieldValue',
'GroupContact',
'EntityTag',
'PledgePayment',
5.0 Support for Serialization Metadata
A field defined with the key 'serialize' (in the metadata) will be serialized on save/create with no additional handling if using basic create methods. Generally this is used by adding <serialize>JSON</serialize>
to the xml when generating the DAO. Example declaration
4.7.17: OR Operator
Most API "get" operations (with the exception of some nonstandard entities - Contact, Contribution, Pledge & Participant) now support the OR operator. Use the API Explorer to see the syntax.
4.7.13: Standardized output of EntityTag api
The EntityTag api had nonstandard output which indexed results by the tag_id
column instead of the id column. This was cleaned up as part of permission fixes in 4.7.13. Any custom code relying on this quirk will need to be updated.
4.7.11: Added generic action 'validate'
A generic validate action which can be used to return an array of errors in an API call. The error values returned are key =>
value pairs with the key being the name of the field and value array containing a description message and error code. For example:
civicrm_api3('Contact', 'validate', array('action' => "create"));
{ "is_error": 0,
"version": 3,
"count": 1,
"id": 0,
"values": [
{
"contact_type":
{
"message": "Mandatory key(s) missing from params array: contact_type",
"code": "mandatory_missing"
}
}
]
}
4.7.0: Support for joins across multiple entities
Most api "get" operations now support joining onto related entities for the filters, return values, or sort fields.
4.7.0: New hook_civicrm_selectWhereclause
This hook can be used to impose access limits on most entities fetched via the api by adding conditions to the where clause.
4.7.0: REST XML format
The encoding of some values in the XML-based API changed. Changes.
4.7.0: Permission changes
- If you have 'access CiviCRM' permissions, you can now retrieve countries: CRM-16963 and CRM-16963 Changes
- If you have 'edit all contacts' permissions, you can now delete relationships using the API: CRM-15991 and CRM-15991 Changes
- Contact related apis (phone, email, address, im, website, relationship, case, etc.) now respect fine-grained contact ACLs instead of requiring heavy-handed permissions like "view all contacts"
4.7.0: Searching on custom fields now works for all entity types
With previous versions of the API, you could not search on custom fields of entities, except for contacts. This issue has been resolved: now you can search the custom fields of any entity type. See CRM-16036 and CRM-16036 Changes. This fix involved a considerable change in the inner workings of the API, so it may cause some unexpected results. If you bump into an issue, please report it.
4.6.7 Multi-select custom field are always returned as numerical indexed arrays
In previous versions of the API, multi-select custom fields were returned either as numerical indexed arrays, either as key-value arrays, depending on the entity type the custom field set applied to. From CiviCRM 4.6.7 on, all multi-select custom fields are returned as numerical indexed arrays. See CRM-15915 and CRM-15915 Changes. (This is still work in progress)
4.6.7: Fixes for chained calls
Some bugs for API chaining were fixed:
- You can chain a LocBlock call to an Event call, even if the event doesn't have a loc block: CRM-16169.
- You can chain multiple create calls that create multiple entities at once: CRM-15815.
- Chaining now works with both sequential=1 and reload=1: CRM-15904
See Pull Request.
4.6.0: 'setvalue' api action deprecated
The 'setvalue' generic api action was used to change one field of a given entity. It was problematic in that it bypassed hooks and business logic related to updating that entity, and is now deprecated. Use the 'create' action instead to update all entities by passing their id plus fields to be modified.
4.6.0: Added 'force_rollback' option
The force_rollback option allows one to simulate an API call – all the logic of the API call will run, but any changes to the databases will be rolled back (reverted).
4.5.0: Added 'getrefcount' action
API action "getrefcount" is a generic action which counts the number of references to a record. For example:
- If you called
civicrm_api3('Contact','getrefcount',array('id'=>123)
, the result might tell you that there are a total of 10 references -- 1 reference incivicrm_email.contact_id
, 2 references incivicrm_address.contact_id
, 2 references incivicrm_phone.contact_id
, and 5 references incivicrm_activity_contact.contact_id
. - The activity type "Survey" is an option-value record. If you queried the refcount for that option-value, the result might list a total of 8 references -- 6 references in
civicrm_activity.activity_type_id
, 1 reference incivicrm_survey.activity_type_id
, and 1 reference in CiviCase XML.
The implementation automatically detects the following types of references:
- Standard SQL foreign-keys
- Dynamic SQL foreign-keys which follow the pattern
entity_table+entity_id
. - Quasi-SQL foreign keys which are linked to OptionValue's (via "pseudo-constants")
To detect other references, one must implement hook_civicrm_referenceCounts
or CRM_Core_Component_Info::getReferenceCounts()
. For example, CRM_Case_Info implements getReferenceCounts()
to count references from CiviCase XML to activity-types.
4.5.0: Added 'getlist' action
API action "getlist" is a wrapper for API action "get." It is used mainly for quicksearch and autocomplete widgets. A call to, for example: CRM.api3('contact', 'getlist', {input: 'bob'})
will internally call contact.get and return a list of resuts formatted for use by the select2 widget or other autocomplete/search forms. It supports formatted description, icons or other images in the results, infinite scrolling or paging of search results, and context-aware searching.
See EntityRef Fields documentation for more info.
4.4.5: Added client-side CRM.api3() wrapper
CRM.api3()
is the new api wrapper in javascript and is the recommended way to call the api from the client-side. It supplants the now deprecated cj().crmAPI()
and CRM.api()
functions.
The new wrapper does not accept callback functions but instead returns a jQuery deferred object which you can attach one or more handlers to.
The new wrapper supports issuing multiple api calls in a single requestto save bandwidth and server-load.
4.4.0: 'getoptions' action accepts additional params related to context
See Pseudoconstant (option list) Reference
4.4.0: 'getoptions' action respects 'sequential' param
The 'sequential' param will cause results to be returned in a non-associative array, which is especially useful for json. Prior to 4.4, this param was ignored for the 'getoptions' action. This has now been fixed.
!!! caution Because api calls from the smarty context set 'sequential=1' as a default, this will produce inconsistent results from 4.3 to 4.4 if you do not explicitly set this param.
See:CRM-13608
4.4.0: 'create' action accepts 'options.reload=1'
When calling the "create" action, the API returns a copy of the record. However, for many entities, the returned value does not meet expectations – for example, if a hook (like hook_civicrm_post
) has manipulated the record in the DB, then the manipulated record will not appear the return-value. Also, any field-values with dates or NULLs may appear unusually formatted. If your application relies on the return-value being correct & consistent, then pass in 'option.reload=1', e.g.
$result = civicrm_api3('Contact', 'create', array(
'contact_type' => 'Individual',
'first_name' => 'First',
'last_name' => 'Last',
'nick_name' => 'Firstie',
'options' => array(
'reload' => 1,
),
));
After completely creating or updating the record, the API will reload the record with "get". This ensures greater consistency but may incur a slight performance penalty.
See also: CRM/Utils/API/ReloadOptionTest.php
4.4.0: 'create' and 'replace' actions accept 'options.match' or 'options.match-mandatory'
When calling the "create" or "replace" action, one may wish to update an existing record. In this past, this required passing the ID. If one passes 'options.match', the API will attempt to update an existing record.
The option is available in two variations, 'options.match' and 'options.match-mandatory' (which requires that a match be found – if no match is found, it raises an error).
Using "options.match" with "create"
// Create "Jeffrey Lebowski" with external ID "1234".
// If a contact already exists with external ID "1234", update it.
$result = civicrm_api3('contact', 'create', array(
'contact_type' => 'Individual',
'first_name' => 'Jeffrey',
'last_name' => 'Lebowski',
'nick_name' => 'The Dude',
'external_identifier' => '1234',
'options' => array(
'match' => 'external_identifier',
),
));
Using "options.match" with "replace"
// Update contact #123 and reconcile his email addresses with the given list.
//
// If the contact already has an email record for "one@example.com", it will
// be updated. (Extra metadata -- like on-hold status -- will be preserved.)
// If not, a new email record will be inserted.
//
// Similarly, an email record for "two@example.com" will be updated or
// inserted.
//
// Any other email records for contact #123 will be deleted.
$result = civicrm_api3('contact', 'create', array(
'id' => 123,
'api.Email.replace' => array(
'values' => array(
array('email' => 'one@example.com', 'location_type_id' => 1),
array('email' => 'two@example.com', 'location_type_id' => 2),
),
'options' => array('match' => 'email'),
),
));
See also: CRM/Utils/API/MatchOptionTest.php
4.4.0: Smarty wrapper defaults to 'sequential'
Because 'sequential' gives a more concise format, it has been made the default in smarty. If you do not want the sequential format, add sequential=0 to your smarty api call.
4.3.0: New 'getoptions' action
Fetch the options for a specified field e.g. civicrm_api('contact', 'getoptions' array('field' => 'gender_id'));
returns array(1 => 'Female', 2 => 'Male', 3 => 'Transgender')
See Pseudoconstant (option list) Reference
4.3.0: Deprecating action=update
CRM-12140: The API update action was a clunky hack (get+create) to workaround the problems on the create api with an id set (mostly forcing default values). We have now have all (well, at least most of) the entities that behaves on create. We are keeping the action=update working as it was, but no longer mention it in the docs and have removed it from the api explorer as a default action
4.3.0: Default permission changed from "access CiviCRM" to "administer CiviCRM"
- CRM-11329
- This affects API functions called with
check_permissions = 1
(all AJAX, & REST calls) where the permission is not otherwise defined -
This could affect you if\
- you use Rest / Ajax for non permissioned users or you use the
check_permissions
flag in smarty or php calls AND - You access API functions in this way which don't have explicitly defined permissions in CRM/Core/DAO/,permissions.php (most common functions are defined)
- You use custom api via REST and have not defined the permissions for them (using the hook)
- you use Rest / Ajax for non permissioned users or you use the
- See the ticket for more
4.3.0: AJAX: cj().crmAPI() is now CRM.api()
Prior to 4.3, the syntax for AJAX API calls was
cj().crmAPI('Entity', 'action', {...params...}, {
callBack: function(data) { ... }
});
This notation is still supported in 4.3. However, the recommended notation has changed to:
CRM.api('Entity', 'action', {...params...}, {
success: function(data) { ... }
});
4.3.0: REST: user/password authentication unsupported
In previous releases, REST API calls supported two forms of authentication:
- Authentication with a per-user API key (e.g.
rest.php?entity=contact&action=get&api_key=...&key=...
) - Authentication with a username/password (e.g.
rest.php?q=civicrm/login&user=...&pass=...&key=...
) and subsequent requests with a PHPSESSID (e.g.rest.php?q=civicrm/contact/get&PHPSESSID=...&key=...
)
The second form is no longer supported.
4.3.5 / 4.2.10: Introduction of civicrm_api3 wrapper
This allows the syntax
try {
civicrm_api3('contact', 'get', array());
civicrm_api3('contribution', 'sendconfirmation', array('id' => 100));
}
catch (CiviCRM_API3_Exception $e) {
$error = $e->getMessage();
}
APIv3: Specific APIs (Changes)
4.7.25: Event API. price_set_id not returned unless specified.
This api now follows the standard convention of only returning extra data when requested. Specify return: 'price_set_id'
in the params to fetch this field.
4.7.20/4.7.13 : Extensions API Get. All Information on Extensions is returned by default
When calling either the get or getsingle action for the Extension API you will now by default be returned all information on an extension rather than just id status and key - See CRM-19414. However the initial implementation meant that there was no ability to filter Extensions down to just retrieve either information on one extension or a specific set of fields for extensions. This has been fixed in CRM-20532 released in 4.7.20
4.7.11: Group API: "group_type" is supported for both integer and array values
When creating a new Group, the "create" API previously failed for group_type
parameter. This is now supported for both integer and array values.
- Using Integer -
group_type => 2
will create a group with only type "Mailing List". - Using arrays -
group_type => array(1, 2)
will create a group with both "Access Control" and "Mailing List" as its types.
4.7.0: GroupContact API
Deprecated ability to use the 'create' method with multiple contacts / groups in the format contact_id.1
, contact_id.2
/ group_id.1
, group_id.2
etc. This will be removed in a future version. The new approach, using arrays, is documented in the API additions section.
4.6.0: Mailing API
- Default values now match the default values of the user-interface. For example, if
footer_id
is omitted, then the default footer is used. - When saving a mailing, the recipient list and the scheduled job will not be created by default. They will be created when a
scheduled_date
is set. - The default
api.mailing_job.create: 1
has been removed. - The "submit" action is akin to "create", but it requires a
scheduled_date
and works with CiviMail's advanced/optional permission model. - When using advanced CiviMail workflows, the "create" and "submit" actions will enforce the additional permissions for 'create mailings', 'schedule mailings', and 'approve mailings'.
- If the site policy requires standard mail-merge tokens (as it should, as it does by default), then the Mailing API will enforce that requirement when scheduling the blast.
4.6.0: Mailing Component API
By default, components are now filtered on is_active=1
. To get the full listing of components (regardless of is_active
), specify a query value is_active = NULL
. Make sure you use an API binding that supports NULL (e.g. civicrm_api3
or JSON-based REST). Example:
civicrm_api3('MailingComponent','get',array('is_active' => NULL));
4.5.0: Case API: "case_type" corresponds to machine-name
When creating a new Case record, the "create" API previously accepted case_type
using the displayable title of the case-type (e.g. "Housing Support"). Beginning in v4.5, the case_type
should specify the internal machine-name of the case-type (e.g. housing_support
). Submitting the displayable title will still work - but this is deprecated. For more discussion about changes to handling of case-type names, see Check Case Type Name Consistency.
4.4.0: Activity API Changes
source_contact_id
is no longer part of the activity record, it is returned by default from the new activity contact table so the change does not need to affect interactive code
4.3.0: Deprecate Constant API
Most CRM_*_Pseudoconstant methods
(which the 'constant' api is a wrapper for) are deprecated in 4.3 and many are removed in 4.4. To future-proof your code, use the api.getoptions method instead of the constant api. See Pseudoconstant (option list) Reference
4.3.0: Contact get API now respects ACLS
This means that contact get api now gets only the contacts for which the logged in person is permission if you set the check_permissions
flag on the api call (it is always set for REST calls & Smarty). Note that the fields that can be returned from contact api if check_permissions
is set are restricted to those shown by 'getfields'
Sponsored by Fuzion.
4.3.0: Contribution API creates line items
If you create a contribution then a default line item will be automatically created for it according to various rules. If you wish to create the line items yourself you need to add the param 'skipLineItems' => 1
4.3.0: Create events from a template
The event api can now clone templates similar to how the UI can do it. Add the param template_id
and all properties of that event template (including payment processors, profiles, scheduled reminders, etc) will be added to your new event.
APIv3: Specific APIs (Additions)
4.7.15 StateProvince API
This API can be used to create, update and delete 'state/province' entries via the API. Added in CRM-19688.
4.7.7 System.updatelogtables
This api can be called to change the format of the log_conn_id
fields to a 17 Char varchar - and to switch to using truly unique connection ids. Calling this api can also convert log tables to INNODB - using this hook hook_civicrm_alterLogTables either in your code or with the Extension
Note that log table conversion can be slow which is why we are offering a conversion tool for the improved log_conn_id
storage rather than springing it in an upgrade script
4.7.0: EntityBatch, SavedSearch, OpenId
These entities are now accessible using the api:
- EntityBatch: CRM-16842 and Pull Request
- SavedSearch: CRM-16701 and Pull Request
- OpenId: CRM-16517 and Pull Request
4.7.0: GroupContact API accepts array of contact_id or group_id
It is now possible to add multiple contacts to one or more groups using a standard array. The 'create' method now correctly accepts an array of contact ids in the contact_id
param, or an array of groups in the group_id
param. This replaces the legacy functionality that was deprecated in this version.
4.7.0: StatusPreference API
The StatusPreference API controls access to the new StatusPreference entity. It is used to read and write the values for the CiviCRM 4.7 Status Page.
4.6.0: Attachment API
The Attachment API allows reading and writing attachments. It is a successor to File API which provides a unified interface for managing
-
civicrm_file
records, -
civicrm_entity_file records
, and - file content on disk. Details (at time of writing):
- It supports attachments on Activity and Mailing records.
- Permissions derive from the permissions on the related entity. (Ex: To attach a file to a mailing, one must have permission to create/edit mailings. To read a file from an activity, one must have permission to read activities.) Only coarse-grained permissions are supported.
- It supports 1-M relations (one entity to many attachments). Theoretically, the DB schema allows M-M, but this has not been used in practice and requires more complicated DX.
4.6.0: Mailing AB API
The Mailing AB API allows creation of A/B tests.
4.5.0: contribution_page.submit action
Similar to profile.submit - this takes the values you would pass into the form and uses them for post processing. - including credit card processing, creating memberships etc. This api has mostly been used in the test suite so far so you should investigate carefully before using it. (Profile.submit is more mature)
4.5.0: CaseType API
The CaseType API allows one to create, modify, and delete case types. This includes support for setting the detailed activity/relationship configuration with the "definition" property. For examples, see api_v3_CaseTypeTest
.
4.4.8: FinancialType, FinancialAccount, ActivityContact API
4.4.?: Dashboard API -- Enable developers to register new dashlets
$result = civicrm_api3('dashboard', 'create', array(
'label' => 'New Dashlet element',
'name' => 'New Dashlet element',
'url' => 'civicrm/report/list&reset=1&compid=99&snippet=5',
'fullscreen_url' => 'civicrm/report/list&compid=99&reset=1&snippet=5&context=dashletFullscreen',
));
4.4.?: DashboardContact API -- Enable developers to assign dashlets to the dashboard for particular users
$result = civicrm_api3('dashboard_contact', 'create', array(
'contact_id' => $contact['id'],
'dashboard_id' => $dashresult['id'],
'is_active' => 1,
));
4.4.2: ActionSchedule API (Scheduled Reminders)
$activityContacts = CRM_Core_OptionGroup::values('activity_contacts', FALSE, FALSE, FALSE, NULL, 'name');
$assigneeID = CRM_Utils_Array::key('Activity Assignees', $activityContacts);
$targetID = CRM_Utils_Array::key('Activity Targets', $activityContacts);
$scheduledStatus = CRM_Core_OptionGroup::getValue('activity_status', 'Scheduled', 'name');
$mappingId = CRM_Core_DAO::getFieldValue('CRM_Core_DAO_ActionMapping', 'activity_type', 'id', 'entity_value');
$activityTypeId = CRM_Core_OptionGroup::getValue('activity_type', "Meeting", 'name');
$result = civicrm_api3('dashboard', 'create', array(
'title' => "simpleActionSchedule",
'recipient' => $assigneeID,
'limit_to' => 1,
'entity_value' => $activityTypeId,
'entity_status' => $scheduledStatus,
'is_active' => 1,
'record_activity' => 1,
'mapping_id' => $mappingId,
));
4.4.0 Profile submit & getfields api
Using these api along with get you can build your own profile form prefilled with a contact id and use the params from it to submit as if you were using the built in profile. The prefilling on cid=0
pages use the profile.get with contact_id
4.4.0: Soft Credits API
Civi 4.4 has a MIH to support multiple soft credits per contact. The soft credit API supports the new functions. CRM-12496
4.4.0: Mailing Contact API
4.4.0: Report Instance API
4.3.4 / 4.2 LTS Contribution.completetransaction action (like an IPN)
This api takes a pending contribution and completes it, updating related entities like memberships and sending out emails as required. Some IPN call this function in their handlePaymentNotification function (as soon as they have ascertained a successful payment)
4.3.0: Location Type API
Big thanks to Jon Goldberg CRM-11206
4.3.0: Mailing API
Functions to create new CiviMails contributed by Chris Burgess of Giant Robot.
4.3.0 / 4.2.10: Setting API
Settings can be set / retrieved / reverted to defaults for single or mulitple domains using the setting api. There is also the ability to define default settings e.g country - specific ones by hook (Try the civiconfigure extension for more on that)
4.3.0: Job API
Schedule cron tasks by creating records with the "Job" API.
4.3.0: Payment Processor API
Implements basic CRUD functionality for payment processors.
4.3.0: LocBlock API
Although location blocks are no longer used by CiviCRM contacts, they are currently still used for events. So the main purpose of this api is to allow you to CRUD the address, emails and phones associated with an event.
Object-Oriented APIs
This section doesn't document changes to APIv3 per se – rather, it documents changes to public-facing PHP classes. For example, when a developer writes a custom report or custom search, he typically extends a public-facing PHP class, and any changes to that class should be clearly communicated.
4.3.0: CRM_Contact_Form_Search_Interface::all
The all method has a new parameter and a custom search written for 4.2 needs to be changed to have a new $justIDs = FALSE param. The new signature for all:
function all($offset = 0, $rowcount = 0, $sort = NULL,$includeContactIDs = FALSE, $justIDs = FALSE)
You need to upgrade civix as well so it generates this new code for a custom search
4.6.0: CRM_Contact_Form_Search_Interface->buildTaskList
Classes which implement this interface must implement a new method called buildTaskList. This method is responsible for building the list of actions (e.g., Add to Group) that may be performed on set of search results. It differs
from hook_civicrm_searchTasks in that the hook allows a developer to specify tasks by entity (e.g., Contact, Event, etc.) whereas buildTaskList provides the ability to target a specific form. The new method takes a CRM_Core_Form_Search
object as an argument and should return an array. Dump CRM_Core_Form_Search()->_taskList
to learn about the format of the array. The array returned by buildTaskList will completely replace the task list.
Aside from the community-maintained custom searches in CRM/Contact/Form/Search/Custom/
, this change does not affect CiviCRM core. Custom searches which extend CRM_Contact_Form_Search_Custom_Base
(as do those built on civix) will not be affected, as the method is implemented there.
See CRM-15965 for more information.
Hooks
This section doesn't document changes to APIv3 per se – rather, it documents changes to the the Hook interfaces.
4.7.14 hook_civicrm_pre & hook_civicrm_post supports CustomField
Pre and post hooks now fire when adding, updating or deleting custom fields.
4.7.0 hook_civicrm_tabs deprecated
This hook is deprecated in 4.7. Use hook_civicrm_tabset
instead.
4.7.0 hook_civicrm_validate removed
This hook was deprecated since v4.2 in favor of hook_civicrm_validateForm
.
4.5.0: hook_civicrm_enableDisable removed
The deprecated enableDisablehook was not reliably invoked every time an entity was enabled or disabled.It was removed in 4.5. Use the standard pre and post hooks instead.
4.5.0: hook_civicrm_referenceCounts
The new API call "getrefcount" allows one to ask about references to a given record. Using hook_civicrm_referenceCounts, a third-party developer can modify the reference-count.
4.4.0: Add hooks for profile forms
Added hooks for
- "civicrm/profile/view" hook_civicrm_viewProfile,
- "civicrm/profile" hook_civicrm_searchProfile,
- "civicrm/profile/edit" or "civicrm/profile/create" hook_civicrm_buildProfile,hook_civicrm_validateProfile, hook_civicrm_processProfile).
See also: CRM-12865
4.4.0: hook_civicrm_searchColumns: Change of $values in profile-listings
When displaying a profile-based listing (such as "civicrm/profile?gid=XXX"), the $values represents a row/column matrix by providing an array of rows. Each row contains several cells keyed numerically, but one cell was inconsistently keyed by the string sort_name
instead of its numeric position. The sort_name
cell appeared early and affected the numbering of all subsequent cells. For greater consistency, the sort_name
will now be identified numerically, and other cells will be renumbered accordingly.
4.4.0: hook_civicrm_buildUFGroupsForModule: Change to $ufGroups
$ufGroups provides an array of UFGroup records. In previous releases, this array always contained the same fields for each record (id
, title
, is_reserved
, etc). In 4.4, the fields are usually the same, but they may vary depending on the context. See patches to CRM-13388
Other
4.7.0: CRM_Core_Config: Property loading
In previous versions, the properties in CRM_Core_Config
were loaded from a mix of sources, most notably a SQL field (civicrm_domain.config_backend
). The config_backend
contained a mix of canonical settings and caches. For any given property, it was very difficult to trace the lifecycle (e.g. to identify where the property was canonically stored, how it was filtered, or how it could be changed).
In v4.7+, all persistent settings should now be stored canonically in the table civicrm_setting, and caches should be stored using a cache service. These are not stored in civicrm_domain.config_backend.
To provide backward compatibility, CRM_Core_Config
defines properties with the magic methods, __get()
and __set()
. To trace a property (and determine where it's truly stored), examine Core_Config_MagicMerge::getPropertyMap()
.
Most downstream code should work with CRM_Core_Config
properties the same way as before, but there are a couple caveats:
- If a property's value is an array, you cannot directly modify the array-elements (e.g. "
$config->foo['bar'] = 123;
); doing so will produce a PHP warning. Instead, you can replace the array$config->foo = $config->foo + array('bar' => 123);
. (There were no examples of this in the core codebase, but there was one example in the core test suite.) - A handful of properties were removed because they appeared to be unused, misleading, or redundant.
-
enableComponentIDs
,formKeyDisable
,gettextCodeset
,gettextDomain
,gettextCodeset
,gettextDomain
,gettextResourceDir
,groupTree
,importDataSourceDir
,localeCustomStrings
,mailerPeriod
,mailerSpoolLimit
,mapGeoCoding
,maxImportFileSize
,maxLocationBlocks
,oldInputStyle
,pluginsDir
,revampPages
,smartyDir
,sqlDir
- Attempting to access an unknown/undefined property will now trigger an error.
See also: CRM-16373
4.7.0: Global $civicrm_setting: Multiple changes
The global variable $civicrm_setting
is used to override CiviCRM settings. It has been changed:
- In previous versions, settings were indexed by group name (e.g.
Search Preferences
). In v4.7+, settings should be indexed by entity name (e.g.domain
orcontact
). For backward compatibility, most group names are treated as an alias fordomain
orcontact
.// Old/Deprecated/Verbose. Compatible with v4.1+. $civicrm_setting['Search Preferences']['search_autocomplete_count'] = 10; $civicrm_setting['CiviCRM Preferences']['remote_profile_submissions'] = FALSE; // New/Preferred/Simplified. Compatible with v4.7+. $civicrm_setting['domain']['search_autocomplete_count'] = 10; $civicrm_setting['domain']['remote_profile_submissions'] = FALSE;
-
$civicrm_setting
is usually modified within the filecivicrm.settings.php
, but it can be modified at runtime (e.g. in a hook). If you modify it at runtime, then you must also calluseMandatory()
to assimilate the changes. Examples for v4.6 and v4.7 are compared below.// Ex: Compatible with v4.6 or older (minimalist) function example_hook() { global $civicrm_setting; $civicrm_setting['Search Preferences']['search_autocomplete_count'] = 10; } // Ex: Compatible with v4.7 or newer (minimalist) function example_hook() { global $civicrm_setting; $civicrm_setting['domain']['search_autocomplete_count'] = 10; Civi::service('settings_manager')->useMandatory(); } // Ex: Compatible with both v4.6 and v4.7 function example_hook() { global $civicrm_setting; $civicrm_setting['Search Preferences']['search_autocomplete_count'] = 10; if (version_compare('>=', CRM_Utils_System::version(), '4.7.alpha1')) { Civi::service('settings_manager')->useMandatory(); } }
See also: CRM-16373.
4.7.0: bin: Removed deprecated scripts
Earlier versions of CiviCRM included a number of standalone scripts which could be called using wget
and cron
. In Civi v4.1, an API-based job-scheduler was introduced, and these cron scripts moved into APIv3 (Job.process_mailing
, Job.process_membership
, etc). Some scripts were left in the "bin/deprecated" folder, but these have now been removed in v4.7.
4.6.alpha2: CRM_Core_Payment: Object construction
In prior versions, payment processors followed this practice:
- (Mandatory) Implement
public static function &singleton($mode, &$paymentProcessor, &$paymentForm = NULL, $force = FALSE)
- (Conventional) Implement
public function __construct($mode, &$paymentProcessor)
In v4.6+, the singleton() has been replaced by a centralized manager (Civi\Payment\System). Individual payment processors no longer require their own singletons. However, the constructor is mandatory:
- (Optional - for backward compatibility) Implement
public static function &singleton($mode, &$paymentProcessor, &$paymentForm = NULL, $force = FALSE)
- (Mandatory) Implement
public function __construct($mode &$paymentProcessor)
See also: Pull Request
4.6.alpha1: CRM_Core_Transaction
-
CRM_Core_Transaction
has traditionally used a reference-counting mechanism to combine multiple pieces of business-logic into a single transaction. In 4.6, this remains the default behavior, but one can also use nested transactions (by passing$nested=TRUE
to the constructor). Any work done in the nested transaction can be rolled back without affecting the overall transaction. - Prior to 4.6, the idiom for managing transactions was to call
$tx = new CRM_Core_Transaction()
and rely on the destructor to cleanup the transaction (e.g. issue the COMMIT/ROLLBACK). Unfortunately, it can be cumbersome to correctly apply this idiom when handling exceptions generated by non-Civi classes. 4.6 introduces a safer notation:CRM_Core_Transaction::create()->run(function($tx){});
which automatically rolls back in case of an exception.
For more details, see Transaction Reference.
4.5.3: AJAX, Regions, and Resources
CiviCRM 4.2+ allowed developers to inject content on a web page using the Region and Resource APIs. CiviCRM 4.5+ introduced broad changes to the page-loading process which cause many pages to load in-situ as "snippets". This significantly improved perceived load times but caused some regressions on customized backend forms which relied on Region or Resource APIs. v4.5.3 introduces the following changes:
- The
page-header
,page-body
, andpage-footer
regions will all be processed on normal (full, standalone) pages as well as snippets (embedded AJAX pages). - The
html-header
region is only processed on normal-pages. - The
ajax-snippet
region is only processed on snippet-pages. - Settings exported via Resource API (
CRM_Core_Resources::addSetting()
) will be communicated in both normal-pages and snippet-pages. The settings on the snippet-page will merge with the settings on the normal-page. Merges are conducted deeply/recursively.
4.5.0: CiviCase: Changes in XML
-
CiviCase XML content may be loaded from the database (
civicrm_case_type.definition
) or from a file (as in previous versions). Database content will take precedence over file content. -
CiviCase XML supports additional tags:
- A <CaseType> may set <forkable>0</forkable>. Use this if you want to (a) store XML in a file and (b) prohibit editing in the GUI See also: CRM-15097
- An <ActivitySet> may set <sequence>true</sequence> to indicate that activities are performed in a linear, back-to-back fashion. See also: CRM-14727 3.(FIXME: In 4.5.beta6, the two tags have different representations of boolean. In the next release, use "true" or "false" for both.)
-
If a CiviCase XML file references an unknown activity-type or relationship-type, then it will be auto-created as a ManagedEntity. Moreover, if the XML changes or disappears, and if there are no records which rely on the activity-type or relationship-type, then it will be auto-removed. ManagedEntities are reconciled (created/preserved/deleted) when editing Casetypes via GUI, during extension install, and during other system flushes.
-
When using CiviCase XML files, the file-name and machine-name (
civicrm_case_type.name
) shouldmatch. Admins may occasionally see a warning if these are mismatched.-
See also: checkCaseTypeNameConsistency
-
The example CiviCase XML files have been renamed:
Case Type (Title) Case Type (Name) Old Filename New Filename Housing Support housing_support
HousingSupport.xml
housing_support.xml
Adult Day Care Referral adult_day_care_referral
AdultDayCareReferral.xml
adult_day_care_referral.xml
-
4.4.6, 4.2.17: Profiles: Removed hidden fields
Profile forms previously included hidden fields (post_URL
, cancel_URL
, and add_to_group_id
). If you have customizations which rely on manipulating these hidden fields (e.g. by embedding a profile on a third-party site using a customized HTML snippet), then those customizations may break. However, you may still control the values of post_URL
, cancel_URL
, and add_to_group_id
by configuring the profile's advanced settings. See: CRM-14856.