Documentation

Update extends DAOUpdateAction
in package

Application

Update one or more $ENTITY with new values.

Use the where clause to bulk update multiple records, or supply 'id' as a value to update a single record.

Properties

$_debugOutput : mixed
$_actionName : string
$_entityName : string
$chain : array<string|int, mixed>: Additional api requests - will be called once per result.
$checkPermissions : bool: Whether to enforce acl permissions based on the current user.
$debug : bool: Add debugging info to the api result.
$language : string: Preferred language (optional)
$limit : int: Maximum number of $ENTITIES to return.
$offset : int: Zero-based index of first $ENTITY to return.
$orderBy : array<string|int, mixed>: Array of field(s) to use in ordering the results.
$reload : bool: Reload $ENTITIES after saving.
$values : array<string|int, mixed>: Field values to update.
$version : int: Api version number; cannot be changed.
$where : array<string|int, mixed>: Criteria for selecting items to update.
$_arrayStorage : array<string|int, mixed>
$_entityFields : array<string|int, mixed>
$_id : int
$_maxWeights : array<string|int, mixed>
$_paramInfo : array<string|int, mixed>
$_reflection : ReflectionClass

Methods

__call() : static|mixed: Magic function to provide automatic getter/setter for params.
__construct() : mixed: Action constructor.
__set() : mixed: Strictly enforce api parameters
_run() : mixed
addChain() : $this
addClause() : $this: Adds one or more AND/OR/NOT clause groups
addOrderBy() : $this: Adds to the orderBy clause
addValue() : $this: Add an item to the values array.
addWhere() : $this
baoToArray() : array<string|int, mixed>: Convert saved object to array
entityFields() : array<string|int, mixed>: Returns schema fields for this entity & action.
evaluateCondition() : bool: This function is used internally for evaluating field annotations.
execute() : Result: Invoke api call.
getActionName() : string
getChain() : array<string|int, mixed>
getCheckPermissions() : bool
getDebug() : bool
getEntityName() : string
getLanguage() : string|null
getLimit() : int
getOffset() : int
getOrderBy() : array<string|int, mixed>
getParamInfo() : array<string|int, mixed>: Get documentation for one or all params
getParams() : array<string|int, mixed>: Serialize this object's params into an array
getPermissions() : array<string|int, mixed>
getReload() : bool
getValue() : mixed|null: Retrieve a single value, transforming pseudoconstants as necessary
getValues() : array<string|int, mixed>
getValues() : array<string|int, mixed>
getWhere() : array<string|int, mixed>
offsetExists() : bool
offsetGet() : mixed
offsetSet() : void
offsetUnset() : void
paramExists() : bool
reflect() : ReflectionClass
setChain() : $this
setCheckPermissions() : $this
setDebug() : $this
setLanguage() : $this
setLimit() : $this
setOffset() : $this
setOrderBy() : $this
setReload() : $this
setValues() : $this: Overwrite all values
setValues() : $this
setVersion() : $this
setWhere() : $this
addCallbackToDebugOutput() : mixed: When in debug mode, this logs the callback function being used by a Basic*Action class.
checkRequiredFields() : array<string|int, mixed>: Validates required fields for actions which create a new object.
fillDefaults() : mixed: Fill field defaults which were declared by the api.
formatCustomParams() : mixed: Converts params from flat array e.g. ['GroupName.Fieldname' => value] to the hierarchy expected by the BAO, nested within $params['custom'].
formatWriteValues() : mixed: Replaces pseudoconstants in input values
getBaoName() : CRM_Core_DAO|string
getBatchAction() : AbstractGetAction: Get an API action object which resolves the list of records for this batch.
getBatchRecords() : array<string|int, mixed>: Get a list of records for this batch.
getCustomFieldInfo() : array{id: int, name: string, entity: string, suffix: string, html_type: string, data_type: string, extends: string, table_name: string}|null: Gets field info needed to save custom data
getLanguageOptions() : array<string|int, mixed>: Get available preferred languages.
getMagicProperties() : array<string|int, mixed>: Get a list of class properties for which magic methods are supported.
getParamDefaults() : array<string|int, mixed>
getSelect() : array<string|int, string>: Determines what fields will be returned by getBatchRecords
resolveFKValues() : void: Looks up an id based on some other property of an fk entity
updateRecords() : array<string|int, mixed>
updateWeight() : mixed: Update weights when inserting or updating a sortable entity
validateValues() : mixed
whereClauseToString() : string: Produces a human-readable where clause, for the reading enjoyment of you humans.
write() : array<string|int, CRM_Core_DAO>: Overrideable function to save items using the appropriate BAO function
writeObjects() : array<string|int, mixed>: Write bao objects as part of a create/update/save action.
getMaxWeight() : int|mixed: Looks up max weight for a set of sortable entities

$_debugOutput


    public
        mixed
    $_debugOutput
     = []

$_actionName


    protected
        string
    $_actionName

$_entityName


    protected
        string
    $_entityName

$chain

Additional api requests - will be called once per result.


    protected
        array<string|int, mixed>
    $chain
     = []

Keys can be any string - this will be the name given to the output.

You can reference other values in the api results in this call by prefixing them with $.

For example, you could create a contact and place them in a group by chaining the GroupContact api to the Contact api:

Contact::create()
  ->setValue('first_name', 'Hello')
  ->addChain('add_a_group', GroupContact::create()
    ->setValue('contact_id', '$id')
    ->setValue('group_id', 123)
  )

This will substitute the id of the newly created contact with $id.

$checkPermissions

Whether to enforce acl permissions based on the current user.


    protected
        bool
    $checkPermissions
     = TRUE

Setting to FALSE will disable permission checks and override ACLs. In REST/javascript this cannot be disabled.

$debug

Add debugging info to the api result.


    protected
        bool
    $debug
     = FALSE

When enabled, $result->debug will be populated with information about the api call, including sql queries executed.

Note: with checkPermissions enabled, debug info will only be returned if the user has "view debug output" permission.

$language

Preferred language (optional)


    protected
        string
    $language

This option will notify major localization subsystems (ts(), multilingual, etc) about which locale should be used for composing/formatting messaging.

This indicates the preferred language. The effective language is determined by Civi\Core\Locale::negotiate($preferredLanguage).

$limit

Maximum number of $ENTITIES to return.


    protected
        int
    $limit
     = 0

Defaults to 0 - unlimited.

Note: the Api Explorer sets this to 25 by default to avoid timeouts. Change or remove this default for your application code.

$offset

Zero-based index of first $ENTITY to return.


    protected
        int
    $offset
     = 0

Defaults to 0 - first $ENTITY found.

$orderBy

Array of field(s) to use in ordering the results.


    protected
        array<string|int, mixed>
    $orderBy
     = []

Defaults to id ASC

$example->addOrderBy('sort_name', 'ASC')

$reload

Reload $ENTITIES after saving.


    protected
        bool
    $reload
     = FALSE

Setting to true will load complete records and return them as the api result. If false the api usually returns only the fields specified to be updated.

$values

Field values to update.


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

$version

Api version number; cannot be changed.


    protected
        int
    $version
     = 4

$where

Criteria for selecting items to update.


    protected
        array<string|int, mixed>
    $where
     = []

Required if no id is supplied in values.

$_arrayStorage


    private
        array<string|int, mixed>
    $_arrayStorage
     = []

$_entityFields


    private
        array<string|int, mixed>
    $_entityFields

$_id


    private
        int
    $_id

Used to identify api calls for transactions

$_maxWeights


    private
        array<string|int, mixed>
    $_maxWeights
     = []

$_paramInfo


    private
        array<string|int, mixed>
    $_paramInfo

$_reflection


    private
        ReflectionClass
    $_reflection

__call()

Magic function to provide automatic getter/setter for params.


    public
                    __call(mixed $name, mixed $arguments) : static|mixed

Parameters

$name : mixed
$arguments : mixed

Return values

static|mixed

__construct()

Action constructor.


    public
                    __construct(string $entityName, string $actionName) : mixed

Parameters

$entityName : string
$actionName : string

__set()

Strictly enforce api parameters


    public
                    __set(mixed $name, mixed $value) : mixed

Parameters

$name : mixed
$value : mixed

_run()


    public
                    _run(Result $result) : mixed

Parameters

$result : Result

addChain()


    public
                    addChain(string $name, AbstractAction $apiRequest[, string|int|array<string|int, mixed> $index = NULL ]) : $this

Parameters

$name : string: Unique name for this chained request
$apiRequest : AbstractAction
$index : string|int|array<string|int, mixed> = NULL: See civicrm_api4() for documentation of $index param

Return values

$this

addClause()

Adds one or more AND/OR/NOT clause groups


    public
                    addClause(string $operator, mixed $condition1) : $this

Parameters

$operator : string
$condition1 : mixed: ... $conditionN Either a nested array of arguments, or a variable number of arguments passed to this function.

Return values

$this

addOrderBy()

Adds to the orderBy clause


    public
                    addOrderBy(string $fieldName[, string $direction = 'ASC' ]) : $this

Parameters

$fieldName : string
$direction : string = 'ASC'

Return values

$this

addValue()

Add an item to the values array.


    public
                    addValue(string $fieldName, mixed $value) : $this

Parameters

$fieldName : string
$value : mixed

Return values

$this

addWhere()


    public
                    addWhere(string $fieldName, string $op[, mixed $value = NULL ]) : $this

Parameters

$fieldName : string
$op : string
$value : mixed = NULL

Return values

$this

baoToArray()

Convert saved object to array


    public
                    baoToArray(CRM_Core_DAO $bao, array<string|int, mixed> $input) : array<string|int, mixed>

Used by create, update & save actions

Parameters

$bao : CRM_Core_DAO
$input : array<string|int, mixed>

Return values

array<string|int, mixed>

entityFields()

Returns schema fields for this entity & action.


    public
                    entityFields() : array<string|int, mixed>

Here we bypass the api wrapper and run the getFields action directly. This is because we DON'T want the wrapper to check permissions as this is an internal op.

Return values

array<string|int, mixed>

evaluateCondition()

This function is used internally for evaluating field annotations.


    public
            static        evaluateCondition(string $expr, array<string|int, mixed> $vars) : bool

It should never be passed raw user input.

Parameters

$expr : string: Conditional in php format e.g. $foo > $bar
$vars : array<string|int, mixed>: Variable name => value

Return values

bool

execute()

Invoke api call.


    public
                    execute() : Result

At this point all the params have been sent in and we initiate the api call & return the result. This is basically the outer wrapper for api v4.

Return values

Result

getActionName()


    public
                    getActionName() : string

Return values

string

getChain()


    public
                    getChain() : array<string|int, mixed>

Return values

array<string|int, mixed>

getCheckPermissions()


    public
                    getCheckPermissions() : bool

Return values

bool

getDebug()


    public
                    getDebug() : bool

Return values

bool

getEntityName()


    public
                    getEntityName() : string

Return values

string

getLanguage()


    public
                    getLanguage() : string|null

Return values

string|null

getLimit()


    public
                    getLimit() : int

Return values

int

getOffset()


    public
                    getOffset() : int

Return values

int

getOrderBy()


    public
                    getOrderBy() : array<string|int, mixed>

Return values

array<string|int, mixed>

getParamInfo()

Get documentation for one or all params


    public
                    getParamInfo([string $param = NULL ]) : array<string|int, mixed>

Parameters

$param : string = NULL

Return values

array<string|int, mixed> —

of arrays [description, type, default, (comment)]

getParams()

Serialize this object's params into an array


    public
                    getParams() : array<string|int, mixed>

Return values

array<string|int, mixed>

getPermissions()


    public
                    getPermissions() : array<string|int, mixed>

Return values

array<string|int, mixed>

getReload()


    public
                    getReload() : bool

Return values

bool

getValue()

Retrieve a single value, transforming pseudoconstants as necessary


    public
                    getValue(string $fieldExpr) : mixed|null

Parameters

$fieldExpr : string

Return values

mixed|null

getValues()


    public
                    getValues() : array<string|int, mixed>

Return values

array<string|int, mixed>

getValues()


    public
                    getValues() : array<string|int, mixed>

Get field values.

Return values

array<string|int, mixed>

getWhere()


    public
                    getWhere() : array<string|int, mixed>

Return values

array<string|int, mixed>

offsetExists()


    public
                    offsetExists(mixed $offset) : bool

Parameters

$offset : mixed

Return values

bool

offsetGet()


    public
                &    offsetGet(mixed $offset) : mixed

Parameters

$offset : mixed

offsetSet()


    public
                    offsetSet(mixed $offset, mixed $value) : void

Parameters

$offset : mixed
$value : mixed

offsetUnset()


    public
                    offsetUnset(mixed $offset) : void

Parameters

$offset : mixed

paramExists()


    public
                    paramExists(string $param) : bool

Parameters

$param : string

Return values

bool

reflect()


    public
                    reflect() : ReflectionClass

Return values

ReflectionClass

setChain()


    public
                    setChain([array<string|int, mixed> $chain =  ]) : $this

Parameters

$chain : array<string|int, mixed> =

Return values

$this

setCheckPermissions()


    public
                    setCheckPermissions(bool $checkPermissions) : $this

Parameters

$checkPermissions : bool

Return values

$this

setDebug()


    public
                    setDebug([bool $debug =  ]) : $this

Enable/disable debug output

Parameters

$debug : bool =

Return values

$this

setLanguage()


    public
                    setLanguage([string|null $language =  ]) : $this

Parameters

$language : string|null =

Return values

$this

setLimit()


    public
                    setLimit([int $limit =  ]) : $this

Parameters

$limit : int =

Return values

$this

setOffset()


    public
                    setOffset([int $offset =  ]) : $this

Parameters

$offset : int =

Return values

$this

setOrderBy()


    public
                    setOrderBy([array<string|int, mixed> $order =  ]) : $this

Parameters

$order : array<string|int, mixed> =

Return values

$this

setReload()


    public
                    setReload([bool $reload =  ]) : $this

Specify whether complete objects will be returned after saving.

Parameters

$reload : bool =

Return values

$this

setValues()

Overwrite all values


    public
                    setValues(array<string|int, mixed> $values) : $this

Parameters

$values : array<string|int, mixed>

Return values

$this

setValues()


    public
                    setValues([array<string|int, mixed> $values =  ]) : $this

Set all field values from an array of key => value pairs.

Parameters

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

Return values

$this

setVersion()


    public
                    setVersion(int $val) : $this

Parameters

$val : int

Return values

$this

setWhere()


    public
                    setWhere([array<string|int, mixed> $wheres =  ]) : $this

Parameters

$wheres : array<string|int, mixed> =

Return values

$this

addCallbackToDebugOutput()

When in debug mode, this logs the callback function being used by a Basic*Action class.


    protected
                    addCallbackToDebugOutput(callable $callable) : mixed

Parameters

$callable : callable

checkRequiredFields()

Validates required fields for actions which create a new object.


    protected
                    checkRequiredFields(mixed $values) : array<string|int, mixed>

Parameters

$values : mixed

Return values

array<string|int, mixed>

fillDefaults()

Fill field defaults which were declared by the api.


    protected
                    fillDefaults(array<string|int, mixed> &$params) : mixed

Note: default values from core are ignored because the BAO or database layer will supply them.

Parameters

$params : array<string|int, mixed>

formatCustomParams()

Converts params from flat array e.g. ['GroupName.Fieldname' => value] to the hierarchy expected by the BAO, nested within $params['custom'].


    protected
                    formatCustomParams(array<string|int, mixed> &$params, int $entityId) : mixed

Parameters

$params : array<string|int, mixed>
$entityId : int

formatWriteValues()

Replaces pseudoconstants in input values


    protected
                    formatWriteValues(mixed &$record) : mixed

Parameters

$record : mixed

getBaoName()


    protected
                    getBaoName() : CRM_Core_DAO|string

Return values

CRM_Core_DAO|string

getBatchAction()

Get an API action object which resolves the list of records for this batch.


    protected
                    getBatchAction() : AbstractGetAction

This is similar to getBatchRecords(), but you may further refine the API call (e.g. selecting different fields or data-pages) before executing.

Return values

AbstractGetAction

getBatchRecords()

Get a list of records for this batch.


    protected
                    getBatchRecords() : array<string|int, mixed>

Return values

array<string|int, mixed>

getCustomFieldInfo()

Gets field info needed to save custom data


    protected
                    getCustomFieldInfo(string $fieldExpr) : array{id: int, name: string, entity: string, suffix: string, html_type: string, data_type: string, extends: string, table_name: string}|null

Parameters

$fieldExpr : string: Field identifier with possible suffix, e.g. MyCustomGroup.MyField1:label

Return values

array{id: int, name: string, entity: string, suffix: string, html_type: string, data_type: string, extends: string, table_name: string}|null

getLanguageOptions()

Get available preferred languages.


    protected
                    getLanguageOptions() : array<string|int, mixed>

Return values

array<string|int, mixed>

getMagicProperties()

Get a list of class properties for which magic methods are supported.


    protected
            static        getMagicProperties() : array<string|int, mixed>

Return values

array<string|int, mixed> —

List of supported properties, keyed by property name. Array(string $propertyName => bool $true).

getParamDefaults()


    protected
                    getParamDefaults() : array<string|int, mixed>

Return values

array<string|int, mixed>

getSelect()

Determines what fields will be returned by getBatchRecords


    protected
                    getSelect() : array<string|int, string>

Defaults to an entity's primary key(s), typically ['id']

Return values

array<string|int, string>

resolveFKValues()

Looks up an id based on some other property of an fk entity


    protected
                    resolveFKValues(array<string|int, mixed> &$record) : void

Parameters

$record : array<string|int, mixed>

updateRecords()


    protected
                    updateRecords(array<string|int, mixed> $items) : array<string|int, mixed>

Parameters

$items : array<string|int, mixed>

Return values

array<string|int, mixed>

updateWeight()

Update weights when inserting or updating a sortable entity


    protected
                    updateWeight(array<string|int, mixed> &$record) : mixed

Parameters

$record : array<string|int, mixed>

validateValues()


    protected
                    validateValues() : mixed

whereClauseToString()

Produces a human-readable where clause, for the reading enjoyment of you humans.


    protected
                    whereClauseToString([array<string|int, mixed> $whereClause = NULL ][, string $op = 'AND' ]) : string

Parameters

$whereClause : array<string|int, mixed> = NULL
$op : string = 'AND'

Return values

string

write()

Overrideable function to save items using the appropriate BAO function


    protected
                    write(array<string|int, array<string|int, mixed>> $items) : array<string|int, CRM_Core_DAO>

Parameters

$items : array<string|int, array<string|int, mixed>>: Items already formatted by self::writeObjects

Return values

array<string|int, CRM_Core_DAO> —

Array of saved DAO records

writeObjects()

Write bao objects as part of a create/update/save action.


    protected
                    writeObjects(array<string|int, mixed> $items) : array<string|int, mixed>

Parameters

$items : array<string|int, mixed>: The records to write to the DB.

Return values

array<string|int, mixed> —

The records after being written to the DB (e.g. including newly assigned "id").

getMaxWeight()

Looks up max weight for a set of sortable entities


    private
                    getMaxWeight(mixed $daoName, mixed $filters, mixed $weightField) : int|mixed

Keeps it in memory in case this operation is writing more than one record

Parameters

$daoName : mixed
$filters : mixed
$weightField : mixed

Return values

int|mixed

Update extends DAOUpdateAction in package Application

Table of Contents

Properties

Methods

Properties

$_debugOutput

$_actionName

$_entityName

$chain

$checkPermissions

$debug

$language

Tags

$limit

$offset

$orderBy

$reload

$values

Tags

$version

$where

$_arrayStorage

$_entityFields

$_id

Tags

$_maxWeights

$_paramInfo

$_reflection

Methods

__call()

Parameters

Tags

Return values

__construct()

Parameters

__set()

Parameters

Tags

_run()

Parameters

Tags

addChain()

Parameters

Return values

addClause()

Parameters

Tags

Return values

addOrderBy()

Parameters

Return values

addValue()

Parameters

Return values

addWhere()

Parameters

Tags

Return values

baoToArray()

Parameters

Return values

entityFields()

Tags

Return values

evaluateCondition()

Parameters

Tags

Return values

execute()

Tags

Return values

getActionName()

Return values

getChain()

Return values

getCheckPermissions()

Return values

getDebug()

Return values

getEntityName()

Update extends DAOUpdateAction
in package

Application