Documentation

Create extends DAOCreateAction
in package
uses ContributionSaveTrait

Create a new $ENTITY from supplied values.

Tags
inheritDoc

Table of Contents

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)
$values  : array<string|int, mixed>
Field values to set for the new $ENTITY.
$version  : int
Api version number; cannot be changed.
$_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
addValue()  : $this
Add an item to the values array.
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
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>
getValue()  : mixed|null
Retrieve a single value, transforming pseudoconstants as necessary
getValues()  : array<string|int, mixed>
getValues()  : array<string|int, mixed>
offsetExists()  : bool
offsetGet()  : mixed
offsetSet()  : void
offsetUnset()  : void
paramExists()  : bool
reflect()  : ReflectionClass
setChain()  : $this
setCheckPermissions()  : $this
setDebug()  : $this
setLanguage()  : $this
setValues()  : $this
Overwrite all values
setValues()  : $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.
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
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
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>
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

Properties

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

Tags
optionsCallback

getLanguageOptions

$values

Field values to set for the new $ENTITY.

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

$version

Api version number; cannot be changed.

protected int $version = 4

$_arrayStorage

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

Methods

__call()

Magic function to provide automatic getter/setter for params.

public __call(mixed $name, mixed $arguments) : static|mixed
Parameters
$name : mixed
$arguments : mixed
Tags
throws
CRM_Core_Exception
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
Tags
throws
Exception

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

addValue()

Add an item to the values array.

public addValue(string $fieldName, mixed $value) : $this
Parameters
$fieldName : string
$value : mixed
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.

Tags
see
GetFields
throws
CRM_Core_Exception
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

Tags
throws
CRM_Core_Exception
throws
Exception
Return values
bool

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

getEntityName()

public getEntityName() : string
Return values
string

getLanguage()

public getLanguage() : string|null
Return values
string|null

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>

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>

offsetExists()

public offsetExists(mixed $offset) : bool
Parameters
$offset : mixed
Tags
inheritDoc
Return values
bool

offsetGet()

public & offsetGet(mixed $offset) : mixed
Parameters
$offset : mixed
Tags
inheritDoc
Attributes
#[ReturnTypeWillChange]

offsetSet()

public offsetSet(mixed $offset, mixed $value) : void
Parameters
$offset : mixed
$value : mixed
Tags
inheritDoc

offsetUnset()

public offsetUnset(mixed $offset) : void
Parameters
$offset : mixed
Tags
inheritDoc

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

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

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
Tags
throws
CRM_Core_Exception
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
Tags
throws
CRM_Core_Exception

formatWriteValues()

protected formatWriteValues(mixed &$record) : mixed
Parameters
$record : mixed
Tags
inheritDoc

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>

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>
Tags
see
SortableEntity

write()

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

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.

Tags
throws
CRM_Core_Exception
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 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results