Documentation

api.php

Tags
file

CiviCRM APIv3 API wrapper.

Table of Contents

Functions

civicrm_api()  : array<string|int, mixed>|int|Result
The original API wrapper.
civicrm_api4()  : Result
CiviCRM API version 4.
civicrm_api3()  : array<string|int, mixed>|int
Version 3 wrapper for civicrm_api.
_civicrm_api3_api_getfields()  : array<string|int, mixed>
Call getfields from api wrapper.
civicrm_error()  : bool
Check if the result is an error. Note that this function has been retained from api v2 for convenience but the result is more standardised in v3 and param 'format.is_success' => 1 will result in a boolean success /fail being returned if that is what you need.
_civicrm_api_get_camel_name()  : string|null
Get camel case version of entity name.
_civicrm_api_replace_variables()  : mixed
Swap out any $values vars.
_civicrm_api_replace_variable()  : mixed|null
Swap out a $value.foo variable with the value from parent api results.
_civicrm_api_get_entity_name_from_camel()  : string
Convert possibly camel name to underscore separated entity name.
_civicrm_api_get_entity_name_from_dao()  : string
Having a DAO object find the entity name.

Functions

civicrm_api()

The original API wrapper.

Not recommended for new code but ok for existing code to continue using.

Calling civicrm_api() is functionally identical to civicrm_api3() or civicrm_api4() except:

  1. It requires $params['version'].
  2. It catches exceptions and returns an array like ['is_error' => 1, 'error_message' => ...]. This is disfavored for typical business-logic/hooks/forms/etc. However, if an existing caller handles civicrm_api()-style errors, then there is no functional benefit to reworking it.
civicrm_api(string $entity, string $action, array<string|int, mixed> $params) : array<string|int, mixed>|int|Result
Parameters
$entity : string
$action : string
$params : array<string|int, mixed>
Return values
array<string|int, mixed>|int|Result

civicrm_api4()

CiviCRM API version 4.

civicrm_api4(string $entity, string $action[, array<string|int, mixed> $params = [] ][, string|int|array<string|int, mixed> $index = NULL ]) : Result

This API (Application Programming Interface) is used to access and manage data in CiviCRM.

APIv4 is the latest stable version.

Parameters
$entity : string

Name of the CiviCRM entity to access. All entity names are capitalized CamelCase, e.g. ContributionPage. Most entities correspond to a database table (e.g. Contact is the table civicrm_contact). For a complete list of available entities, call civicrm_api4('Entity', 'get');

$action : string

The "verb" of the api call. For a complete list of actions for a given entity (e.g. Contact), call civicrm_api4('Contact', 'getActions');

$params : array<string|int, mixed> = []

An array of API input keyed by parameter name. The easiest way to discover all available parameters is to visit the API Explorer on your CiviCRM site. The API Explorer is listed in the CiviCRM menu under Support -> Developer.

$index : string|int|array<string|int, mixed> = NULL

Controls the Result array format. By default the api Result contains a non-associative array of data. Passing an $index tells the api to automatically reformat the array, depending on the variable type passed:

  • Integer: return a single result array; e.g. $index = 0 will return the first result, 1 will return the second, and -1 will return the last.

    For APIv4 Explorer, use e.g. 0 in the Index box.

  • String: index the results by a field value; e.g. $index = "name" will return an associative array with the field 'name' as keys.

    For APIv4 Explorer, use e.g. name in the Index box.

  • Non-associative array: return a single value from each result; e.g. $index = ['title'] will return a non-associative array of strings - the 'title' field from each result.

    For APIv4 Explorer, use e.g. [title] in the Index box.

  • Associative array: a combination of the previous two modes; e.g. $index = ['name' => 'title'] will return an array of strings - the 'title' field keyed by the 'name' field.

    For APIv4 Explorer, use e.g. {name: title} in the Index box.

Tags
see
https://docs.civicrm.org/dev/en/latest/api/v4/usage/
throws
CRM_Core_Exception
throws
NotImplementedException
Return values
Result

civicrm_api3()

Version 3 wrapper for civicrm_api.

civicrm_api3(string $entity, string $action[, array<string|int, mixed> $params = [] ]) : array<string|int, mixed>|int

Throws exception.

Parameters
$entity : string
$action : string
$params : array<string|int, mixed> = []
Tags
throws
CRM_Core_Exception
Return values
array<string|int, mixed>|int —

Dependent on the $action

_civicrm_api3_api_getfields()

Call getfields from api wrapper.

_civicrm_api3_api_getfields(array<string|int, mixed> &$apiRequest) : array<string|int, mixed>

This function ensures that settings that could alter getfields output (e.g. action for all api & profile_id for profile api ) are consistently passed in.

We check whether the api call is 'getfields' because if getfields is being called we return an empty array as no alias swapping, validation or default filling is done on getfields & we want to avoid a loop

Parameters
$apiRequest : array<string|int, mixed>
Tags
todo

other output modifiers include contact_type

Return values
array<string|int, mixed> —

getfields output

civicrm_error()

Check if the result is an error. Note that this function has been retained from api v2 for convenience but the result is more standardised in v3 and param 'format.is_success' => 1 will result in a boolean success /fail being returned if that is what you need.

civicrm_error(mixed $result) : bool
Parameters
$result : mixed
Return values
bool —

true if error, false otherwise

_civicrm_api_get_camel_name()

Get camel case version of entity name.

_civicrm_api_get_camel_name(string|null $entity) : string|null
Parameters
$entity : string|null
Return values
string|null

_civicrm_api_replace_variables()

Swap out any $values vars.

_civicrm_api_replace_variables(array<string|int, mixed> &$params, array<string|int, mixed> &$parentResult[, string $separator = '.' ]) : mixed

Ie. the value after $value is swapped for the parent $result 'activity_type_id' => '$value.testfield', 'tag_id' => '$value.api.tag.create.id', 'tag1_id' => '$value.api.entity.create.0.id'

Parameters
$params : array<string|int, mixed>
$parentResult : array<string|int, mixed>
$separator : string = '.'

_civicrm_api_replace_variable()

Swap out a $value.foo variable with the value from parent api results.

_civicrm_api_replace_variable(string $value, array<string|int, mixed> $parentResult, string $separator) : mixed|null

Called by _civicrm_api_replace_variables to do the substitution.

Parameters
$value : string
$parentResult : array<string|int, mixed>
$separator : string
Return values
mixed|null

_civicrm_api_get_entity_name_from_camel()

Convert possibly camel name to underscore separated entity name.

_civicrm_api_get_entity_name_from_camel(string $entity) : string
Parameters
$entity : string

Entity name in various formats e.g. Contribution, contribution, OptionValue, option_value, UFJoin, uf_join.

Return values
string —

Entity name in underscore separated format.

_civicrm_api_get_entity_name_from_dao()

Having a DAO object find the entity name.

_civicrm_api_get_entity_name_from_dao(CRM_Core_DAO $bao) : string
Parameters
$bao : CRM_Core_DAO

DAO being passed in.

Return values
string 

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results