1. class
  2. Civi
  3. \
  4. Api4
  5. \
  6. Generic
  7. \
  8. DAOSaveAction

DAOSaveAction

class DAOSaveAction extends AbstractSaveAction

Create or update one or more records.

If creating more than one record with similar values, use the "defaults" param.

Set "reload" if you need the api to return complete records.

Traits

DAOActionTrait

Properties

protected int $version Api version number; cannot be changed. from AbstractAction
protected array $chain Additional api requests - will be called once per result. from AbstractAction
protected bool $checkPermissions Whether to enforce acl permissions based on the current user. from AbstractAction
protected string $_entityName from AbstractAction
protected string $_actionName from AbstractAction
protected array $records Array of records. from AbstractSaveAction
protected array $defaults Array of default values. from AbstractSaveAction
protected bool $reload Reload records after saving. from AbstractSaveAction
protected string $language Specify the language to use if this is a multi-lingual environment. from DAOActionTrait

Methods

__construct(string $entityName, string $actionName, string $idField = 'id')

BatchAction constructor.

from AbstractSaveAction
__set($name, $value)

Strictly enforce api parameters

from AbstractAction
$this
setVersion(int $val)

No description

from AbstractAction
$this
addChain(string $name, AbstractAction $apiRequest, string|int $index = NULL)

No description

from AbstractAction
AbstractAction|mixed
__call($name, $arguments)

Magic function to provide addFoo, getFoo and setFoo for params.

from AbstractAction
Result
execute()

Invoke api call.

from AbstractAction
_run(Result $result)

No description

array
getParams()

Serialize this object's params into an array

from AbstractAction
array
getParamInfo(string $param = NULL)

Get documentation for one or all params

from AbstractAction
string
getEntityName()

No description

from AbstractAction
string
getActionName()

No description

from AbstractAction
bool
paramExists(string $param)

No description

from AbstractAction
array
getParamDefaults()

No description

from AbstractAction
offsetExists($offset)

No description

from AbstractAction
offsetGet($offset)

No description

from AbstractAction
offsetSet($offset, $value)

No description

from AbstractAction
offsetUnset($offset)

No description

from AbstractAction
bool
isAuthorized()

Is this api call permitted?

from AbstractAction
array
getPermissions()

No description

from AbstractAction
array
entityFields()

Returns schema fields for this entity & action.

from AbstractAction
ReflectionClass
reflect()

No description

from AbstractAction
array
checkRequiredFields($values)

Validates required fields for actions which create a new object.

from AbstractAction
bool
evaluateCondition(string $expr, array $vars)

This function is used internally for evaluating field annotations.

from AbstractAction
bool
getCheckPermissions()

No description

from AbstractAction
array
getChain()

No description

from AbstractAction
validateValues()

No description

from AbstractSaveAction
string
getIdField()

No description

from AbstractSaveAction
array
getRecords()

No description

from AbstractSaveAction
array
getDefaults()

No description

from AbstractSaveAction
bool
getReload()

No description

from AbstractSaveAction
CRM_Core_DAO|string
getBaoName()

No description

from DAOActionTrait
static array
baoToArray(object $bao)

Extract the true fields from a BAO

from DAOActionTrait
array|int
getObjects()

No description

from DAOActionTrait
fillDefaults(array $params)

Fill field defaults which were declared by the api.

from DAOActionTrait
array
writeObjects(array $items)

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

from DAOActionTrait
mixed
formatCustomParams(array $params, int $entityId)

No description

from DAOActionTrait
checkContactPermissions($baoName, $item)

Check edit/delete permissions for contacts and related entities.

from DAOActionTrait
string
getLanguage()

No description

from DAOActionTrait
setLanguage(string $language)

No description

from DAOActionTrait

Details

in AbstractSaveAction at line 97
__construct(string $entityName, string $actionName, string $idField = 'id')

BatchAction constructor.

Parameters

string $entityName
string $actionName
string $idField

in AbstractAction at line 149
__set($name, $value)

Strictly enforce api parameters

Parameters

$name
$value

Exceptions

Exception

in AbstractAction at line 158
$this setVersion(int $val)

Parameters

int $val

Return Value

$this

Exceptions

API_Exception

in AbstractAction at line 174
$this addChain(string $name, AbstractAction $apiRequest, string|int $index = NULL)

Parameters

string $name Unique name for this chained request
AbstractAction $apiRequest
string|int $index Either a string for how the results should be indexed e.g. 'name' or the index of a single result to return e.g. 0 for the first result.

Return Value

$this

in AbstractAction at line 187
AbstractAction|mixed __call($name, $arguments)

Magic function to provide addFoo, getFoo and setFoo for params.

Parameters

$name
$arguments

Return Value

AbstractAction|mixed

Exceptions

API_Exception

in AbstractAction at line 231
Result execute()

Invoke api call.

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 Value

Result

Exceptions

UnauthorizedException

at line 53
_run(Result $result)

Parameters

Result $result

in AbstractAction at line 247
array getParams()

Serialize this object's params into an array

Return Value

array

in AbstractAction at line 265
array getParamInfo(string $param = NULL)

Get documentation for one or all params

Parameters

string $param

Return Value

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

in AbstractAction at line 282
string getEntityName()

Return Value

string

in AbstractAction at line 290
string getActionName()

Return Value

string

in AbstractAction at line 298
bool paramExists(string $param)

Parameters

string $param

Return Value

bool

in AbstractAction at line 305
protected array getParamDefaults()

Return Value

array

in AbstractAction at line 312
offsetExists($offset)

Parameters

$offset

in AbstractAction at line 319
offsetGet($offset)

Parameters

$offset

in AbstractAction at line 344
offsetSet($offset, $value)

Parameters

$offset
$value

in AbstractAction at line 359
offsetUnset($offset)

Parameters

$offset

in AbstractAction at line 373
bool isAuthorized()

Is this api call permitted?

This function is called if checkPermissions is set to true.

Return Value

bool

in AbstractAction at line 381
array getPermissions()

Return Value

array

in AbstractAction at line 410
array entityFields()

Returns schema fields for this entity & action.

Here we bypass the api wrapper and execute the getFields action directly. This is because we DON'T want the wrapper to check permissions as this is an internal op, but we DO want permissions to be checked inside the getFields request so e.g. the api_key field can be conditionally included.

Return Value

array

See also

GetFields

in AbstractAction at line 429
ReflectionClass reflect()

Return Value

ReflectionClass

in AbstractAction at line 443
protected array checkRequiredFields($values)

Validates required fields for actions which create a new object.

Parameters

$values

Return Value

array

Exceptions

API_Exception

in AbstractAction at line 473
protected bool evaluateCondition(string $expr, array $vars)

This function is used internally for evaluating field annotations.

It should never be passed raw user input.

Parameters

string $expr Conditional in php format e.g. $foo > $bar
array $vars Variable name => value

Return Value

bool

Exceptions

API_Exception
Exception

in AbstractAction at line 50
bool getCheckPermissions()

Return Value

bool

in AbstractAction at line 50
array getChain()

Return Value

array

in AbstractSaveAction at line 106
protected validateValues()

Exceptions

API_Exception

in AbstractSaveAction at line 121
protected string getIdField()

Return Value

string

in AbstractSaveAction at line 54
array getRecords()

Return Value

array

in AbstractSaveAction at line 54
array getDefaults()

Return Value

array

in AbstractSaveAction at line 54
bool getReload()

Return Value

bool

in DAOActionTrait at line 61
protected CRM_Core_DAO|string getBaoName()

Return Value

CRM_Core_DAO|string

in DAOActionTrait at line 73
static array baoToArray(object $bao)

Extract the true fields from a BAO

(Used by create and update actions)

Parameters

object $bao

Return Value

array

in DAOActionTrait at line 88
protected array|int getObjects()

Return Value

array|int

in DAOActionTrait at line 109
protected fillDefaults(array $params)

Fill field defaults which were declared by the api.

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

Parameters

array $params

in DAOActionTrait at line 131
protected array writeObjects(array $items)

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

Parameters

array $items The records to write to the DB.

Return Value

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

Exceptions

API_Exception

in DAOActionTrait at line 214
protected mixed formatCustomParams(array $params, int $entityId)

Parameters

array $params
int $entityId

Return Value

mixed

in DAOActionTrait at line 280
protected checkContactPermissions($baoName, $item)

Check edit/delete permissions for contacts and related entities.

Parameters

$baoName
$item

Exceptions

UnauthorizedException

in DAOActionTrait at line 47
string getLanguage()

Return Value

string

in DAOActionTrait at line 47
setLanguage(string $language)

Parameters

string $language