utils.php
CiviCRM APIv3 utility functions.
Table of Contents
Functions
- _civicrm_api3_initialize() : mixed
- Initialize CiviCRM - should be run at the start of each API function.
- civicrm_api3_verify_one_mandatory() : mixed
- Wrapper Function for civicrm_verify_mandatory to make it simple to pass either / or fields for checking.
- civicrm_api3_verify_mandatory() : mixed
- Check mandatory fields are included.
- civicrm_api3_create_error() : array<string|int, mixed>
- Create error array.
- civicrm_api3_create_success() : array<string|int, mixed>
- Format array in result output style.
- _civicrm_api3_load_DAO() : bool
- Load the DAO of the entity.
- _civicrm_api3_get_DAO() : CRM_Core_DAO|string
- Return the DAO of the function or Entity.
- _civicrm_api3_get_BAO() : string|null
- Return the BAO name of the function or Entity.
- _civicrm_api3_separate_values() : mixed
- Recursive function to explode value-separated strings into arrays.
- _civicrm_api3_filter_fields_for_bao() : mixed
- This is a legacy wrapper for api_store_values.
- _civicrm_api3_store_values() : bool
- Copy values (other than id) from params to values if they exist in fields.
- _civicrm_api3_get_using_query_object() : array<string|int, mixed>
- Get function for query object api.
- _civicrm_api3_get_query_object() : array<string|int, mixed>
- Get dao query object based on input params.
- _civicrm_api3_dao_set_filter() : mixed
- Function transfers the filters being passed into the DAO onto the params object.
- _civicrm_api3_apply_filters_to_dao() : mixed
- Apply filters (e.g. high, low) to DAO object (prior to find).
- _civicrm_api3_get_options_from_params() : array<string|int, mixed>
- Get sort, limit etc options from the params - supporting old & new formats.
- _civicrm_api3_apply_options_to_dao() : mixed
- Apply options (e.g. sort, limit, order by) to DAO object (prior to find).
- _civicrm_api3_build_fields_array() : array<string|int, mixed>
- Build fields array.
- _civicrm_api3_get_unique_name_array() : array<string|int, mixed>
- Build fields array.
- _civicrm_api3_dao_to_array() : array<string|int, mixed>
- Converts an DAO object to an array.
- _civicrm_api3_custom_fields_are_required() : bool
- Determine if custom fields need to be retrieved.
- _civicrm_api3_object_to_array() : mixed
- Converts an object to an array.
- _civicrm_api3_object_to_array_unique_fields() : array<string|int, mixed>
- Wrapper for _civicrm_object_to_array when api supports unique fields.
- _civicrm_api3_custom_format_params() : mixed
- Format custom parameters.
- _civicrm_api3_format_params_for_create() : mixed
- Format parameters for create action.
- formatCheckBoxField() : mixed
- We can't rely on downstream to add separators to checkboxes so we'll check here.
- _civicrm_api3_basic_get() : array<string|int, mixed>
- Function to do a 'standard' api get - when the api is only doing a $bao->find then use this.
- _civicrm_api3_basic_create() : array<string|int, mixed>
- Function to do a 'standard' api create - when the api is only doing a $bao::create then use this.
- _civicrm_api3_basic_create_fallback() : CRM_Core_DAO|null
- For BAO's which don't have a create() or add() functions, use this fallback implementation.
- _civicrm_api3_basic_delete() : array<string|int, mixed>
- Function to do a 'standard' api del.
- _civicrm_api3_custom_data_get() : mixed
- Get custom data for the given entity & Add it to the returnArray.
- _civicrm_api3_validate() : array<string|int, mixed>
- Used by the Validate API.
- _civicrm_api3_validate_switch_cases() : mixed
- Used by the Validate API.
- _civicrm_api3_validate_fields() : mixed
- Validate fields being passed into API.
- _civicrm_api3_validate_foreign_keys() : mixed
- Validate foreign key values of fields being passed into API.
- _civicrm_api3_validate_date() : mixed
- Validate date fields being passed into API.
- _civicrm_api3_getValidDate() : mixed
- Convert date into BAO friendly date.
- _civicrm_api3_validate_constraint() : mixed
- Validate foreign constraint fields being passed into API.
- _civicrm_api3_validate_unique_key() : mixed
- Validate foreign constraint fields being passed into API.
- _civicrm_api3_generic_replace() : array<string|int, mixed>|int
- Generic implementation of the "replace" action.
- _civicrm_api3_generic_replace_base_params() : array<string|int, mixed>
- Replace base parameters.
- _civicrm_api_get_fields() : array<string|int, mixed>
- Returns fields allowable by api.
- _civicrm_api_get_custom_fields() : array<string|int, mixed>
- Return an array of fields for a given entity.
- _civicrm_api3_swap_out_aliases() : mixed
- Fill params array with alternate (alias) values where a field has an alias and that is filled & the main field isn't.
- _civicrm_api3_validate_integer() : mixed
- Validate integer fields being passed into API.
- _civicrm_api3_resolve_country_id() : int|null
- Helper function to determine country_id given the myriad of values for country_id or country that are supported
- _civicrm_api3_resolve_contactID() : int|null|"unknown-user"
- Determine a contact ID using a string expression.
- _civicrm_api3_validate_html() : mixed
- Validate html (check for scripting attack).
- _civicrm_api3_validate_string() : mixed
- Validate string fields being passed into API.
- _civicrm_api3_api_match_pseudoconstant() : mixed
- Validate & swap out any pseudoconstants / options.
- _civicrm_api3_api_match_pseudoconstant_value() : mixed
- Validate & swap a single option value for a field.
- _civicrm_api3_api_resolve_alias() : bool|string
- Returns the canonical name of a field.
- _civicrm_api3_deprecation_check() : string|array<string|int, mixed>|null
- Check if the function is deprecated.
- _civicrm_api3_field_value_check() : mixed
- Get the actual field value.
- _civicrm_api3_basic_array_get() : array<string|int, mixed>
- A generic "get" API based on simple array data. This is comparable to _civicrm_api3_basic_get but does not use DAO/BAO. This is useful for small/mid-size data loaded from external JSON or XML documents.
- _civicrm_api3_check_edit_permissions() : mixed
- _civicrm_api3_compare_timestamps() : bool
- Check if an entity has been modified since the last known modified_date
Functions
_civicrm_api3_initialize()
Initialize CiviCRM - should be run at the start of each API function.
_civicrm_api3_initialize() : mixed
civicrm_api3_verify_one_mandatory()
Wrapper Function for civicrm_verify_mandatory to make it simple to pass either / or fields for checking.
civicrm_api3_verify_one_mandatory(array<string|int, mixed> $params[, array<string|int, mixed> $daoName = NULL ][, array<string|int, mixed> $keyoptions = [] ]) : mixed
Parameters
- $params : array<string|int, mixed>
-
Array of fields to check.
- $daoName : array<string|int, mixed> = NULL
-
String DAO to check for required fields (create functions only).
- $keyoptions : array<string|int, mixed> = []
-
List of required fields options. One of the options is required.
Tags
civicrm_api3_verify_mandatory()
Check mandatory fields are included.
civicrm_api3_verify_mandatory(array<string|int, mixed> $params[, array<string|int, mixed> $daoName = NULL ][, array<string|int, mixed> $keys = [] ][, bool $verifyDAO = TRUE ]) : mixed
Parameters
- $params : array<string|int, mixed>
-
Array of fields to check.
- $daoName : array<string|int, mixed> = NULL
-
String DAO to check for required fields (create functions only).
- $keys : array<string|int, mixed> = []
-
List of required fields. A value can be an array denoting that either this or that is required.
- $verifyDAO : bool = TRUE
Tags
civicrm_api3_create_error()
Create error array.
civicrm_api3_create_error(string $msg[, array<string|int, mixed> $data = [] ]) : array<string|int, mixed>
Parameters
- $msg : string
- $data : array<string|int, mixed> = []
Return values
array<string|int, mixed>civicrm_api3_create_success()
Format array in result output style.
civicrm_api3_create_success([array<string|int, mixed>|int $values = 1 ][, array<string|int, mixed> $params = [] ][, string $entity = NULL ][, string $action = NULL ][, object &$dao = NULL ][, array<string|int, mixed> $extraReturnValues = [] ]) : array<string|int, mixed>
Parameters
- $values : array<string|int, mixed>|int = 1
-
values generated by API operation (the result)
- $params : array<string|int, mixed> = []
-
Parameters passed into API call.
- $entity : string = NULL
-
The entity being acted on.
- $action : string = NULL
-
The action passed to the API.
- $dao : object = NULL
-
DAO object to be freed here.
- $extraReturnValues : array<string|int, mixed> = []
-
Additional values to be added to top level of result array(.
- this param is currently used for legacy behaviour support
Tags
Return values
array<string|int, mixed>_civicrm_api3_load_DAO()
Load the DAO of the entity.
_civicrm_api3_load_DAO(string $entity) : bool
Parameters
- $entity : string
Return values
bool_civicrm_api3_get_DAO()
Return the DAO of the function or Entity.
_civicrm_api3_get_DAO(string $name) : CRM_Core_DAO|string
Parameters
- $name : string
-
Either a function of the api (civicrm_{entity}_create or the entity name. return the DAO name to manipulate this function eg. "civicrm_api3_contact_create" or "Contact" will return "CRM_Contact_BAO_Contact"
Return values
CRM_Core_DAO|string_civicrm_api3_get_BAO()
Return the BAO name of the function or Entity.
_civicrm_api3_get_BAO(string $name) : string|null
Parameters
- $name : string
-
Is either a function of the api (civicrm_{entity}_create or the entity name. return the DAO name to manipulate this function eg. "civicrm_contact_create" or "Contact" will return "CRM_Contact_BAO_Contact"
Return values
string|null_civicrm_api3_separate_values()
Recursive function to explode value-separated strings into arrays.
_civicrm_api3_separate_values(array<string|int, mixed> &$values) : mixed
Parameters
- $values : array<string|int, mixed>
_civicrm_api3_filter_fields_for_bao()
This is a legacy wrapper for api_store_values.
_civicrm_api3_filter_fields_for_bao(string $entity, array<string|int, mixed> &$params, array<string|int, mixed> &$values) : mixed
It checks suitable fields using getfields rather than DAO->fields.
Getfields has handling for how to deal with unique names which dao->fields doesn't
Note this is used by BAO type create functions - eg. contribution
Parameters
- $entity : string
- $params : array<string|int, mixed>
- $values : array<string|int, mixed>
_civicrm_api3_store_values()
Copy values (other than id) from params to values if they exist in fields.
_civicrm_api3_store_values(array<string|int, mixed> $fields, array<string|int, mixed> $params, array<string|int, mixed> &$values) : bool
Parameters
- $fields : array<string|int, mixed>
- $params : array<string|int, mixed>
- $values : array<string|int, mixed>
Return values
bool_civicrm_api3_get_using_query_object()
Get function for query object api.
_civicrm_api3_get_using_query_object(string $entity, array<string|int, mixed> $params[, array<string|int, mixed> $additional_options = [] ][, bool $getCount = NULL ][, int $mode = 1 ][, null|array<string|int, mixed> $defaultReturnProperties = NULL ]) : array<string|int, mixed>
The API supports 2 types of get request. The more complex uses the BAO query object. This is a generic function for those functions that call it
At the moment only called by contact we should extend to contribution & others that use the query object. Note that this function passes permission information in. The others don't
Ideally this would be merged with _civicrm_get_query_object but we need to resolve differences in what the 2 variants call
Parameters
- $entity : string
- $params : array<string|int, mixed>
-
As passed into api get or getcount function.
- $additional_options : array<string|int, mixed> = []
-
Array of options (so we can modify the filter).
- $getCount : bool = NULL
-
Are we just after the count.
- $mode : int = 1
-
This basically correlates to the component.
- $defaultReturnProperties : null|array<string|int, mixed> = NULL
-
Default return properties for the entity (used if return not set - but don't do that - set return!).
Tags
Return values
array<string|int, mixed>_civicrm_api3_get_query_object()
Get dao query object based on input params.
_civicrm_api3_get_query_object(array<string|int, mixed> $params, string $mode, string $entity) : array<string|int, mixed>
Ideally this would be merged with _civicrm_get_using_query_object but we need to resolve differences in what the 2 variants call
Parameters
- $params : array<string|int, mixed>
- $mode : string
- $entity : string
Return values
array<string|int, mixed> —[CRM_Core_DAO|CRM_Contact_BAO_Query]
_civicrm_api3_dao_set_filter()
Function transfers the filters being passed into the DAO onto the params object.
DAO based retrieval is being phased out.
_civicrm_api3_dao_set_filter(CRM_Core_DAO &$dao, array<string|int, mixed> $params[, bool $unique = TRUE ][, array<string|int, mixed> $extraSql = [] ]) : mixed
Parameters
- $dao : CRM_Core_DAO
- $params : array<string|int, mixed>
- $unique : bool = TRUE
- $extraSql : array<string|int, mixed> = []
-
API specific queries eg for event isCurrent would be converted to $extraSql['where'] = array('civicrm_event' => array('(start_date >= CURDATE() || end_date >= CURDATE())'));
Tags
_civicrm_api3_apply_filters_to_dao()
Apply filters (e.g. high, low) to DAO object (prior to find).
_civicrm_api3_apply_filters_to_dao(string $filterField, string $filterValue, object &$dao) : mixed
Parameters
- $filterField : string
-
Field name of filter.
- $filterValue : string
-
Field value of filter.
- $dao : object
-
DAO object.
_civicrm_api3_get_options_from_params()
Get sort, limit etc options from the params - supporting old & new formats.
_civicrm_api3_get_options_from_params(array<string|int, mixed> $params[, bool $queryObject = FALSE ][, string $entity = '' ][, string $action = '' ]) : array<string|int, mixed>
Get returnProperties for legacy
Parameters
- $params : array<string|int, mixed>
-
Params array as passed into civicrm_api.
- $queryObject : bool = FALSE
-
Is this supporting a queryObject api (e.g contact) - if so we support more options. for legacy report & return a unique fields array
- $entity : string = ''
- $action : string = ''
Tags
Return values
array<string|int, mixed> —options extracted from params
_civicrm_api3_apply_options_to_dao()
Apply options (e.g. sort, limit, order by) to DAO object (prior to find).
_civicrm_api3_apply_options_to_dao(array<string|int, mixed> &$params, object &$dao, string $entity) : mixed
Parameters
- $params : array<string|int, mixed>
-
Params array as passed into civicrm_api.
- $dao : object
-
DAO object.
- $entity : string
Tags
_civicrm_api3_build_fields_array()
Build fields array.
_civicrm_api3_build_fields_array(CRM_Core_DAO &$bao[, bool $unique = TRUE ]) : array<string|int, mixed>
This is the array of fields as it relates to the given DAO returns unique fields as keys by default but if set but can return by DB fields
Parameters
- $bao : CRM_Core_DAO
- $unique : bool = TRUE
Return values
array<string|int, mixed>_civicrm_api3_get_unique_name_array()
Build fields array.
_civicrm_api3_get_unique_name_array(CRM_Core_DAO &$bao) : array<string|int, mixed>
This is the array of fields as it relates to the given DAO returns unique fields as keys by default but if set but can return by DB fields
Parameters
- $bao : CRM_Core_DAO
Return values
array<string|int, mixed>_civicrm_api3_dao_to_array()
Converts an DAO object to an array.
- DAO based retrieval is being phased out.
_civicrm_api3_dao_to_array(CRM_Core_DAO $dao[, array<string|int, mixed> $params = NULL ][, bool $uniqueFields = TRUE ][, string $entity = "" ][, bool $autoFind = TRUE ]) : array<string|int, mixed>
Parameters
- $dao : CRM_Core_DAO
-
Object to convert.
- $params : array<string|int, mixed> = NULL
- $uniqueFields : bool = TRUE
- $entity : string = ""
- $autoFind : bool = TRUE
Tags
Return values
array<string|int, mixed>_civicrm_api3_custom_fields_are_required()
Determine if custom fields need to be retrieved.
_civicrm_api3_custom_fields_are_required(string $entity, array<string|int, mixed> $params) : bool
We currently retrieve all custom fields or none at this level so if we know the entity && it can take custom fields & there is the string 'custom' in their return request we get them all, they are filtered on the way out
Parameters
- $entity : string
-
Entity name in CamelCase.
- $params : array<string|int, mixed>
Tags
Return values
bool_civicrm_api3_object_to_array()
Converts an object to an array.
_civicrm_api3_object_to_array(object &$dao, array<string|int, mixed> &$values[, array<string|int, mixed>|bool $uniqueFields = FALSE ]) : mixed
Parameters
- $dao : object
-
(reference) object to convert.
- $values : array<string|int, mixed>
-
(reference) array.
- $uniqueFields : array<string|int, mixed>|bool = FALSE
_civicrm_api3_object_to_array_unique_fields()
Wrapper for _civicrm_object_to_array when api supports unique fields.
_civicrm_api3_object_to_array_unique_fields(CRM_Core_DAO &$dao, array<string|int, mixed> &$values) : array<string|int, mixed>
Parameters
- $dao : CRM_Core_DAO
- $values : array<string|int, mixed>
Return values
array<string|int, mixed>_civicrm_api3_custom_format_params()
Format custom parameters.
_civicrm_api3_custom_format_params(array<string|int, mixed> $params, array<string|int, mixed> &$values, string $extends[, string $entityId = NULL ]) : mixed
Parameters
- $params : array<string|int, mixed>
- $values : array<string|int, mixed>
- $extends : string
-
Entity that this custom field extends (e.g. contribution, event, contact).
- $entityId : string = NULL
-
ID of entity per $extends.
_civicrm_api3_format_params_for_create()
Format parameters for create action.
_civicrm_api3_format_params_for_create(array<string|int, mixed> &$params, string $entity) : mixed
Parameters
- $params : array<string|int, mixed>
- $entity : string
formatCheckBoxField()
We can't rely on downstream to add separators to checkboxes so we'll check here.
formatCheckBoxField(mixed &$checkboxFieldValue, string $customFieldLabel, string $entity) : mixed
We should look at pushing to BAO function and / or validate function but this is a safe place for now as it has massive test coverage & we can keep the change very specific note that this is specifically tested in the GRANT api test case so later refactoring should use that as a checking point
We will only alter the value if we are sure that changing it will make it correct - if it appears wrong but does not appear to have a clear fix we don't touch - lots of very cautious code in here
The resulting array should look like array( 'key' => 1, 'key1' => 1, );
OR one or more keys wrapped in a CRM_Core_DAO::VALUE_SEPARATOR - either it accepted by the receiving function
Parameters
- $checkboxFieldValue : mixed
- $customFieldLabel : string
- $entity : string
Tags
_civicrm_api3_basic_get()
Function to do a 'standard' api get - when the api is only doing a $bao->find then use this.
_civicrm_api3_basic_get(string|CRM_Core_DAO $bao_name, array<string|int, mixed> $params[, bool $returnAsSuccess = TRUE ][, string $entity = "" ][, CRM_Utils_SQL_Select|null $sql = NULL ][, bool $uniqueFields = FALSE ]) : array<string|int, mixed>
Parameters
- $bao_name : string|CRM_Core_DAO
-
Name of BAO.
- $params : array<string|int, mixed>
-
Params from api.
- $returnAsSuccess : bool = TRUE
-
Return in api success format.
- $entity : string = ""
- $sql : CRM_Utils_SQL_Select|null = NULL
-
Extra SQL bits to add to the query. For filtering current events, this might be: CRM_Utils_SQL_Select::fragment()->where('(start_date >= CURDATE() || end_date >= CURDATE())');
- $uniqueFields : bool = FALSE
-
Should unique field names be returned (for backward compatibility)
Return values
array<string|int, mixed>_civicrm_api3_basic_create()
Function to do a 'standard' api create - when the api is only doing a $bao::create then use this.
_civicrm_api3_basic_create(string $bao_name, array<string|int, mixed> &$params[, string $entity = NULL ]) : array<string|int, mixed>
Parameters
- $bao_name : string
-
Name of BAO Class.
- $params : array<string|int, mixed>
-
Parameters passed into the api call.
- $entity : string = NULL
-
Entity - pass in if entity is non-standard & required $ids array.
Tags
Return values
array<string|int, mixed>_civicrm_api3_basic_create_fallback()
For BAO's which don't have a create() or add() functions, use this fallback implementation.
_civicrm_api3_basic_create_fallback(string|CRM_Core_DAO $bao_name, array<string|int, mixed> $params) : CRM_Core_DAO|null
Parameters
- $bao_name : string|CRM_Core_DAO
- $params : array<string|int, mixed>
Tags
Return values
CRM_Core_DAO|null —An instance of the BAO
_civicrm_api3_basic_delete()
Function to do a 'standard' api del.
_civicrm_api3_basic_delete(string|CRM_Core_DAO $bao_name, array<string|int, mixed> &$params) : array<string|int, mixed>
When the api is only doing a $bao::del then use this if api::del doesn't exist it will try DAO delete method.
Parameters
- $bao_name : string|CRM_Core_DAO
- $params : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —API result array
_civicrm_api3_custom_data_get()
Get custom data for the given entity & Add it to the returnArray.
_civicrm_api3_custom_data_get(array<string|int, mixed> &$returnArray, bool $checkPermission, string $entity, int $entity_id[, int $groupID = NULL ][, int $subType = NULL ][, string $subName = NULL ]) : mixed
This looks like 'custom_123' = 'custom string' AND 'custom_123_1' = 'custom string' Where 123 is field value & 1 is the id within the custom group data table (value ID)
Parameters
- $returnArray : array<string|int, mixed>
-
Array to append custom data too - generally $result[4] where 4 is the entity id.
- $checkPermission : bool
- $entity : string
-
E.g membership, event.
- $entity_id : int
- $groupID : int = NULL
-
Per CRM_Core_BAO_CustomGroup::getTree.
- $subType : int = NULL
-
E.g. membership_type_id where custom data doesn't apply to all membership types.
- $subName : string = NULL
-
Subtype of entity.
Tags
_civicrm_api3_validate()
Used by the Validate API.
_civicrm_api3_validate(string $entity, string $action, array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $entity : string
- $action : string
- $params : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —$errors
_civicrm_api3_validate_switch_cases()
Used by the Validate API.
_civicrm_api3_validate_switch_cases(string $fieldName, array<string|int, mixed> $fieldInfo, string $entity, array<string|int, mixed> $params, string $action) : mixed
Parameters
- $fieldName : string
- $fieldInfo : array<string|int, mixed>
- $entity : string
- $params : array<string|int, mixed>
- $action : string
Tags
_civicrm_api3_validate_fields()
Validate fields being passed into API.
_civicrm_api3_validate_fields(string $entity, string $action, array<string|int, mixed> &$params, array<string|int, mixed> $fields) : mixed
This function relies on the getFields function working accurately for the given API.
As of writing only date was implemented.
Parameters
- $entity : string
- $action : string
- $params : array<string|int, mixed>
-
-.
- $fields : array<string|int, mixed>
-
Response from getfields all variables are the same as per civicrm_api.
Tags
_civicrm_api3_validate_foreign_keys()
Validate foreign key values of fields being passed into API.
_civicrm_api3_validate_foreign_keys(string $entity, string $action, array<string|int, mixed> &$params, array<string|int, mixed> $fields) : mixed
This function relies on the getFields function working accurately for the given API.
Parameters
- $entity : string
- $action : string
- $params : array<string|int, mixed>
- $fields : array<string|int, mixed>
-
Response from getfields all variables are the same as per civicrm_api.
Tags
_civicrm_api3_validate_date()
Validate date fields being passed into API.
_civicrm_api3_validate_date(array<string|int, mixed> &$params, string &$fieldName, array<string|int, mixed> &$fieldInfo) : mixed
It currently converts both unique fields and DB field names to a mysql date.
Parameters
- $params : array<string|int, mixed>
-
Params from civicrm_api.
- $fieldName : string
-
Uniquename of field being checked.
- $fieldInfo : array<string|int, mixed>
-
Array of fields from getfields function.
Tags
_civicrm_api3_getValidDate()
Convert date into BAO friendly date.
_civicrm_api3_getValidDate(string $dateValue, string $fieldName, int $fieldType) : mixed
We accept 'whatever strtotime accepts'
Parameters
- $dateValue : string
- $fieldName : string
- $fieldType : int
Tags
_civicrm_api3_validate_constraint()
Validate foreign constraint fields being passed into API.
_civicrm_api3_validate_constraint(mixed $fieldValue, string $fieldName, array<string|int, mixed> $fieldInfo, string $entity) : mixed
Parameters
- $fieldValue : mixed
- $fieldName : string
-
Unique name of field being checked.
- $fieldInfo : array<string|int, mixed>
-
Array of fields from getfields function.
- $entity : string
Tags
_civicrm_api3_validate_unique_key()
Validate foreign constraint fields being passed into API.
_civicrm_api3_validate_unique_key(array<string|int, mixed> &$params, string &$fieldName) : mixed
Parameters
- $params : array<string|int, mixed>
-
Params from civicrm_api.
- $fieldName : string
-
Uniquename of field being checked.
Tags
_civicrm_api3_generic_replace()
Generic implementation of the "replace" action.
_civicrm_api3_generic_replace(string $entity, array<string|int, mixed> $params) : array<string|int, mixed>|int
Replace the old set of entities (matching some given keys) with a new set of entities (matching the same keys).
Parameters
- $entity : string
-
Entity name.
- $params : array<string|int, mixed>
-
Params from civicrm_api, including:.
- 'values': an array of records to save
- all other items: keys which identify new/pre-existing records.
Tags
Return values
array<string|int, mixed>|int_civicrm_api3_generic_replace_base_params()
Replace base parameters.
_civicrm_api3_generic_replace_base_params(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
- $params : array<string|int, mixed>
Return values
array<string|int, mixed>_civicrm_api_get_fields()
Returns fields allowable by api.
_civicrm_api_get_fields(string $entity[, bool $unique = FALSE ][, array<string|int, mixed> &$params = [] ]) : array<string|int, mixed>
Parameters
- $entity : string
-
String Entity to query.
- $unique : bool = FALSE
-
Index by unique fields?.
- $params : array<string|int, mixed> = []
Return values
array<string|int, mixed>_civicrm_api_get_custom_fields()
Return an array of fields for a given entity.
_civicrm_api_get_custom_fields(string $entity, array<string|int, mixed> &$params) : array<string|int, mixed>
This is the same as the BAO function but fields are prefixed with 'custom_' to represent api params.
Parameters
- $entity : string
- $params : array<string|int, mixed>
Return values
array<string|int, mixed>_civicrm_api3_swap_out_aliases()
Fill params array with alternate (alias) values where a field has an alias and that is filled & the main field isn't.
_civicrm_api3_swap_out_aliases(array<string|int, mixed> &$apiRequest, array<string|int, mixed> $fields) : mixed
If multiple aliases the last takes precedence
Function also swaps unique fields for non-unique fields & vice versa.
Parameters
- $apiRequest : array<string|int, mixed>
- $fields : array<string|int, mixed>
_civicrm_api3_validate_integer()
Validate integer fields being passed into API.
_civicrm_api3_validate_integer(array<string|int, mixed> &$params, string $fieldName, array<string|int, mixed> &$fieldInfo, string $entity) : mixed
It currently converts the incoming value 'user_contact_id' into the id of the currently logged in user.
Parameters
- $params : array<string|int, mixed>
-
Params from civicrm_api.
- $fieldName : string
-
Uniquename of field being checked.
- $fieldInfo : array<string|int, mixed>
-
Array of fields from getfields function.
- $entity : string
Tags
_civicrm_api3_resolve_country_id()
Helper function to determine country_id given the myriad of values for country_id or country that are supported
_civicrm_api3_resolve_country_id(array<string|int, mixed> $params) : int|null
Parameters
- $params : array<string|int, mixed>
Return values
int|null_civicrm_api3_resolve_contactID()
Determine a contact ID using a string expression.
_civicrm_api3_resolve_contactID(string $contactIdExpr) : int|null|"unknown-user"
Parameters
- $contactIdExpr : string
-
E.g. "user_contact_id" or "@user:username".
Tags
Return values
int|null|"unknown-user"_civicrm_api3_validate_html()
Validate html (check for scripting attack).
_civicrm_api3_validate_html(array<string|int, mixed> &$params, string &$fieldName, array<string|int, mixed> $fieldInfo) : mixed
Parameters
- $params : array<string|int, mixed>
- $fieldName : string
- $fieldInfo : array<string|int, mixed>
Tags
_civicrm_api3_validate_string()
Validate string fields being passed into API.
_civicrm_api3_validate_string(array<string|int, mixed> &$params, string &$fieldName, array<string|int, mixed> &$fieldInfo, string $entity, string $action) : mixed
Parameters
- $params : array<string|int, mixed>
-
Params from civicrm_api.
- $fieldName : string
-
Uniquename of field being checked.
- $fieldInfo : array<string|int, mixed>
-
Array of fields from getfields function.
- $entity : string
- $action : string
Tags
_civicrm_api3_api_match_pseudoconstant()
Validate & swap out any pseudoconstants / options.
_civicrm_api3_api_match_pseudoconstant(mixed &$fieldValue, string $entity, string $fieldName, array<string|int, mixed> $fieldInfo[, string $op = '=' ][, array<string|int, mixed> $additional_lookup_params = [] ]) : mixed
Parameters
- $fieldValue : mixed
- $entity : string
-
: api entity name
- $fieldName : string
-
: field name used in api call (not necessarily the canonical name)
- $fieldInfo : array<string|int, mixed>
-
: getfields meta-data
- $op : string = '='
- $additional_lookup_params : array<string|int, mixed> = []
Tags
_civicrm_api3_api_match_pseudoconstant_value()
Validate & swap a single option value for a field.
_civicrm_api3_api_match_pseudoconstant_value(string &$value, array<string|int, mixed> $options, string $fieldName, bool $isRequired) : mixed
Parameters
- $value : string
-
field value
- $options : array<string|int, mixed>
-
array of options for this field
- $fieldName : string
-
field name used in api call (not necessarily the canonical name)
- $isRequired : bool
-
Is this a required field or is 'null' an acceptable option. We allow 'null' last in case we have the weird situation of it being a valid option in which case our brains will probably explode.
Tags
_civicrm_api3_api_resolve_alias()
Returns the canonical name of a field.
_civicrm_api3_api_resolve_alias(string $entity, string $fieldName[, string $action = 'create' ]) : bool|string
Parameters
- $entity : string
-
api entity name (string should already be standardized - no camelCase).
- $fieldName : string
-
any variation of a field's name (name, unique_name, api.alias).
- $action : string = 'create'
Return values
bool|string —FieldName or FALSE if the field does not exist
_civicrm_api3_deprecation_check()
Check if the function is deprecated.
_civicrm_api3_deprecation_check(string $entity[, array<string|int, mixed> $result = [] ]) : string|array<string|int, mixed>|null
Parameters
- $entity : string
- $result : array<string|int, mixed> = []
Return values
string|array<string|int, mixed>|null_civicrm_api3_field_value_check()
Get the actual field value.
_civicrm_api3_field_value_check(array<string|int, mixed> &$params, string $fieldName[, string $type = NULL ]) : mixed
In some case $params[$fieldName] holds Array value in this format Array([operator] => [value]) So this function returns the actual field value.
Parameters
- $params : array<string|int, mixed>
- $fieldName : string
- $type : string = NULL
_civicrm_api3_basic_array_get()
A generic "get" API based on simple array data. This is comparable to _civicrm_api3_basic_get but does not use DAO/BAO. This is useful for small/mid-size data loaded from external JSON or XML documents.
_civicrm_api3_basic_array_get(string $entity, array<string|int, mixed> $params, array<string|int, mixed> $records, string $idCol, array<string|int, mixed> $filterableFields) : array<string|int, mixed>
Parameters
- $entity : string
- $params : array<string|int, mixed>
-
API parameters.
- $records : array<string|int, mixed>
-
List of all records.
- $idCol : string
-
The property which defines the ID of a record
- $filterableFields : array<string|int, mixed>
-
List of filterable fields.
Tags
Return values
array<string|int, mixed>_civicrm_api3_check_edit_permissions()
_civicrm_api3_check_edit_permissions(string $bao_name, array<string|int, mixed> $params) : mixed
Parameters
- $bao_name : string
- $params : array<string|int, mixed>
Tags
_civicrm_api3_compare_timestamps()
Check if an entity has been modified since the last known modified_date
_civicrm_api3_compare_timestamps(string $modifiedDate, int $id, string $entity) : bool
Parameters
- $modifiedDate : string
-
Last knowm modified_date
- $id : int
-
Id of record to check
- $entity : string
-
API Entity