Documentation

Save extends DAOSaveAction
in package

Application

uses ImportSaveTrait

Create or update one or more $ENTITIES.

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.
$defaults : array<string|int, mixed>: Array of default values.
$language : string: Preferred language (optional)
$match : array<string|int, mixed>: Specify fields to match for update.
$records : array<string|int, mixed>: Array of $ENTITIES to save.
$reload : array<string|int, mixed>|bool: Optionally reload $ENTITIES after saving with an extra SELECT.
$version : int: Api version number; cannot be changed.
$_maxWeights : array<string|int, mixed>

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
addDefault() : $this: Set default value for a field.
addRecord() : $this: Add one or more records to be saved.
baoToArray() : array<string|int, mixed>: Override parent method which expects self::fields() to actually return something
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
getDefaults() : array<string|int, mixed>
getEntityName() : string
getLanguage() : string|null
getMatch() : bool
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>
getRecords() : array<string|int, mixed>
getReload() : bool
getUnpermittedFields() : array<string|int, mixed>: Get fields the logged in user is not permitted to act on.
offsetExists() : bool
offsetGet() : mixed
offsetSet() : void
offsetUnset() : void
paramExists() : bool
reflect() : ReflectionClass
setChain() : $this
setCheckPermissions() : $this
setDebug() : $this
setDefaults() : $this
setLanguage() : $this
setMatch() : $this
setRecords() : $this
setReload() : $this
setVersion() : $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.
ensureCustomFieldDefaultsAreWrittenOnCreate() : void
fillDefaults() : mixed: Fill field defaults which were declared by the api.
filterUnpermittedFields() : void: Filter out any fields with field level permissions.
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
getBaoName() : CRM_Core_DAO|string
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
getIdField() : string
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.
getMatchFields() : array<string|int, mixed>: Options callback for $this->match
getParamDefaults() : array<string|int, mixed>
matchExisting() : int: Find existing record based on $this->match param
reloadResults() : array<string|int, mixed>
resolveFKValues() : void: Looks up an id based on some other property of an fk entity
updateWeight() : mixed: Update weights when inserting or updating a sortable entity
validateValues() : mixed
write() : mixed
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.

$defaults

Array of default values.


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

These defaults will be merged into every $ENTITY in records before saving. Values set in records will override these defaults if set in both places, but updating existing $ENTITIES will overwrite current values with these defaults.

$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).

$match

Specify fields to match for update.


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

The API will perform an update if an existing $ENTITY matches all specified fields.

Note: the fields named in this param should be without any options suffix (e.g. my_field not my_field:name). Any options suffixes in the $records will be resolved by the api prior to matching.

$records

Array of $ENTITIES to save.


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

Should be in the same format as returned by Get.

$reload

Optionally reload $ENTITIES after saving with an extra SELECT.


        protected
            array<string|int, mixed>|bool
    $reload

By default, this action typically returns partial records containing only the fields that were updated. If more is needed, set reload to an array of fields to SELECT (use ['*'] to select all) and they will be returned via an extra get request.

$version

Api version number; cannot be changed.


        protected
            int
    $version
     = 4

$_maxWeights


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

__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

addDefault()

Set default value for a field.


    public
                    addDefault(string $fieldName, mixed $defaultValue) : $this

Parameters

$fieldName : string
$defaultValue : mixed

Return values

$this

addRecord()

Add one or more records to be saved.


    public
                    addRecord(array<string|int, mixed> ...$records) : $this

Parameters

$records : array<string|int, mixed>

Return values

$this

baoToArray()

Override parent method which expects self::fields() to actually return something


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

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

getDefaults()


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

Return values

array<string|int, mixed>

getEntityName()


    public
                    getEntityName() : string

Return values

string

getLanguage()


    public
                    getLanguage() : string|null

Return values

string|null

getMatch()


    public
                    getMatch() : bool

Return values

bool

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>

getRecords()


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

Return values

array<string|int, mixed>

getReload()


    public
                    getReload() : bool

Return values

bool

getUnpermittedFields()

Get fields the logged in user is not permitted to act on.


    public
                    getUnpermittedFields() : 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

setDefaults()


    public
                    setDefaults(array<string|int, mixed> $defaults) : $this

Array of defaults.

Parameters

$defaults : array<string|int, mixed>

Return values

$this

setLanguage()


    public
                    setLanguage(string|null $language) : $this

Parameters

$language : string|null

Return values

$this

setMatch()


    public
                    setMatch(array<string|int, mixed> $match) : $this

Specify fields to match for update.

Parameters

$match : array<string|int, mixed>

Return values

$this

setRecords()


    public
                    setRecords(array<string|int, mixed> $records) : $this

Set array of records to be saved.

Parameters

$records : array<string|int, mixed>

Return values

$this

setReload()


    public
                    setReload(array<string|int, mixed>|null $reload) : $this

Optionally reload $ENTITIES after saving with an extra SELECT.

Parameters

$reload : array<string|int, mixed>|null

Return values

$this

setVersion()


    public
                    setVersion(int $val) : $this

Parameters

$val : int

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>

ensureCustomFieldDefaultsAreWrittenOnCreate()


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

Parameters

$record : 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>

filterUnpermittedFields()

Filter out any fields with field level permissions.


    protected
                    filterUnpermittedFields(array<string|int, mixed> &$items) : void

Parameters

$items : 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()


    protected
                    formatWriteValues(mixed &$record) : mixed

Parameters

$record : mixed

getBaoName()


    protected
                    getBaoName() : CRM_Core_DAO|string

Return values

CRM_Core_DAO|string

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

getIdField()


    protected
                    getIdField() : string

Return values

string

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).

getMatchFields()

Options callback for $this->match


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

Return values

array<string|int, mixed>

getParamDefaults()


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

Return values

array<string|int, mixed>

matchExisting()

Find existing record based on $this->match param


    protected
                    matchExisting(mixed &$record) : int

Parameters

$record : mixed

Return values

int —

Returns number of existing records (1 or 0)

reloadResults()


    protected
                    reloadResults(array<string|int, mixed> $savedRecords[, array<string|int, mixed>|bool $select = true ]) : array<string|int, mixed>

Parameters

$savedRecords : array<string|int, mixed>
$select : array<string|int, mixed>|bool = true

Return values

array<string|int, mixed>

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>

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

write()


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

Parameters

$items : array<string|int, mixed>

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

Save extends DAOSaveAction in package Application uses ImportSaveTrait

Table of Contents

Properties

Methods

Properties

$_debugOutput

$_actionName

$_entityName

$chain

$checkPermissions

$debug

$defaults

$language

Tags

$match

Tags

$records

Tags

$reload

$version

$_maxWeights

Methods

__call()

Parameters

Tags

Return values

__construct()

Parameters

__set()

Parameters

Tags

_run()

Parameters

Tags

addChain()

Parameters

Return values

addDefault()

Parameters

Return values

addRecord()

Parameters

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

getDefaults()

Return values

getEntityName()

Return values

getLanguage()

Return values

getMatch()

Return values

getParamInfo()

Parameters

Return values

getParams()

Return values

getPermissions()

Return values

getRecords()

Save extends DAOSaveAction
in package

Application

uses ImportSaveTrait