Documentation

FormattingUtil
in package

Table of Contents

Properties

$pseudoConstantContexts  : array<string|int, string>

Methods

contactFieldsToRemove()  : array<string|int, mixed>
Lists all field names (including suffixed variants) that should be removed for a given contact type.
convertDataType()  : mixed
filterByPath()  : array<string|int, mixed>
Given a field belonging to either the main entity or a joined entity, and a values array of [path => value], this returns all values which share the same root path.
formatDateValue()  : array<string|int, mixed>|string
Parse date expressions.
formatInputValue()  : mixed
Transform raw api input to appropriate format for use in a SQL query.
formatOutputValues()  : mixed
Unserialize raw field values and convert to correct type
formatWriteParams()  : mixed
Massage values into the format the BAO expects for a write operation
getFieldOptions()  : void
Get options associated with an entity field
getPseudoconstantList()  : array<string|int, mixed>
Retrieves pseudoconstant option list for a field.
getSuffix()  : string|null
Returns the suffix from a given field name if it exists and matches known suffixes.
removeSuffix()  : string
Removes the suffix from a given field name, if a suffix is detected.
replacePseudoconstant()  : array<string|int, mixed>|mixed|null
Replaces value (or an array of values) with options from a pseudoconstant list.
resolveContactID()  : int|null
A contact ID field passed in to the API may contain values such as "user_contact_id" which need to be resolved to the actual contact ID.
applyFormatter()  : void
applyFormatters()  : void
Apply a field's output_formatters callback functions

Properties

$pseudoConstantContexts

public static array<string|int, string> $pseudoConstantContexts = ['name' => 'validate', 'abbr' => 'abbreviate', 'label' => 'get']

Methods

contactFieldsToRemove()

Lists all field names (including suffixed variants) that should be removed for a given contact type.

public static contactFieldsToRemove(string $contactType, string $prefix) : array<string|int, mixed>
Parameters
$contactType : string

Individual|Organization|Household

$prefix : string

Path at which these fields are found, e.g. "address.contact."

Return values
array<string|int, mixed>

convertDataType()

public static convertDataType(mixed $value, string $dataType) : mixed
Parameters
$value : mixed
$dataType : string

filterByPath()

Given a field belonging to either the main entity or a joined entity, and a values array of [path => value], this returns all values which share the same root path.

public static filterByPath(array<string|int, mixed> $values, string $fieldPath, string $fieldName) : array<string|int, mixed>

Note: Unlike CRM_Utils_Array::filterByPrefix this does not mutate the original array.

Ex:

$values = [
  'first_name' => 'a',
  'middle_name' => 'b',
  'related_contact.first_name' => 'c',
  'related_contact.last_name' => 'd',
  'activity.subject' => 'e',
]
$fieldPath = 'related_contact.id'
$fieldName = 'id'

filterByPrefix($values, $fieldPath, $fieldName)
returns [
  'first_name' => 'c',
  'last_name' => 'd',
]
Parameters
$values : array<string|int, mixed>
$fieldPath : string
$fieldName : string
Return values
array<string|int, mixed>

formatDateValue()

Parse date expressions.

public static formatDateValue(mixed $format, mixed $value[, mixed &$operator = null ][, mixed $index = null ]) : array<string|int, mixed>|string

Expands relative date range expressions, modifying the sql operator if necessary

Parameters
$format : mixed
$value : mixed
$operator : mixed = null
$index : mixed = null
Return values
array<string|int, mixed>|string

formatInputValue()

Transform raw api input to appropriate format for use in a SQL query.

public static formatInputValue(mixed &$value, string|null $fieldPath, array<string|int, mixed> $fieldSpec[, array<string|int, mixed> $params = [] ][, string|null &$operator = null ][, null $index = null ]) : mixed

This is used by read AND write actions (Get, Create, Update, Replace)

Parameters
$value : mixed
$fieldPath : string|null
$fieldSpec : array<string|int, mixed>
$params : array<string|int, mixed> = []
$operator : string|null = null

(only for 'get' actions)

$index : null = null

(for recursive loops)

Tags
throws
CRM_Core_Exception

formatOutputValues()

Unserialize raw field values and convert to correct type

public static formatOutputValues(array<string|int, mixed> &$records, array<string|int, mixed> $fields[, string $action = 'get' ][, array<string|int, mixed> $selectAliases = [] ]) : mixed
Parameters
$records : array<string|int, mixed>
$fields : array<string|int, mixed>
$action : string = 'get'
$selectAliases : array<string|int, mixed> = []
Tags
throws
CRM_Core_Exception

formatWriteParams()

Massage values into the format the BAO expects for a write operation

public static formatWriteParams(array<string|int, mixed> &$params, array<string|int, mixed> $fields) : mixed
Parameters
$params : array<string|int, mixed>
$fields : array<string|int, mixed>
Tags
throws
CRM_Core_Exception

getFieldOptions()

Get options associated with an entity field

public static getFieldOptions(array<string|int, mixed> $field[, array<string|int, mixed> $values = [] ][, bool $includeDisabled = false ][, bool $checkPermissions = false ][, int|null $userId = null ]) : void
Parameters
$field : array<string|int, mixed>
$values : array<string|int, mixed> = []
$includeDisabled : bool = false
$checkPermissions : bool = false
$userId : int|null = null
Tags
throws
CRM_Core_Exception

getPseudoconstantList()

Retrieves pseudoconstant option list for a field.

public static getPseudoconstantList(array<string|int, mixed> $field, string $fieldAlias[, array<string|int, mixed> $values = [] ][, string $action = 'get' ]) : array<string|int, mixed>
Parameters
$field : array<string|int, mixed>
$fieldAlias : string

Field path plus pseudoconstant suffix, e.g. 'contact.employer_id.contact_sub_type:label'

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

Other values for this object

$action : string = 'get'
Tags
throws
CRM_Core_Exception
Return values
array<string|int, mixed>

getSuffix()

Returns the suffix from a given field name if it exists and matches known suffixes.

public static getSuffix(string|null $fieldName) : string|null
Parameters
$fieldName : string|null

The name of the field, potentially containing a suffix in the format ":suffix".

Return values
string|null —

The extracted suffix if found and recognized; otherwise, NULL.

removeSuffix()

Removes the suffix from a given field name, if a suffix is detected.

public static removeSuffix(string $fieldName) : string
Parameters
$fieldName : string

The name of the field to process.

Return values
string —

The field name without its suffix, or the original field name if no suffix exists.

replacePseudoconstant()

Replaces value (or an array of values) with options from a pseudoconstant list.

public static replacePseudoconstant(array<string|int, mixed> $options, string|array<string|int, string> $value[, bool $reverse = false ]) : array<string|int, mixed>|mixed|null

The direction of lookup defaults to transforming ids to option values for api output; for api input, set $reverse = TRUE to transform option values to ids.

Parameters
$options : array<string|int, mixed>
$value : string|array<string|int, string>
$reverse : bool = false

Is this a reverse lookup (for transforming input instead of output)

Return values
array<string|int, mixed>|mixed|null

resolveContactID()

A contact ID field passed in to the API may contain values such as "user_contact_id" which need to be resolved to the actual contact ID.

public static resolveContactID(string $fieldName, string|int|null $fieldValue) : int|null

This function resolves those strings to the actual contact ID or throws an exception on "unknown user"

Parameters
$fieldName : string
$fieldValue : string|int|null
Tags
throws
CRM_Core_Exception
Return values
int|null

applyFormatter()

private static applyFormatter(array<string|int, mixed> $fieldDefn, array<string|int, mixed> $row, mixed &$value) : void
Parameters
$fieldDefn : array<string|int, mixed>
$row : array<string|int, mixed>
$value : mixed

applyFormatters()

Apply a field's output_formatters callback functions

private static applyFormatters(array<string|int, mixed> $result, SqlExpression $fieldExpr, array<string|int, mixed> $fieldDefn, mixed &$value) : void
Parameters
$result : array<string|int, mixed>
$fieldExpr : SqlExpression
$fieldDefn : array<string|int, mixed>
$value : mixed 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results