Documentation

AutocompleteAction extends AbstractAction
in package

Application

uses SavedSearchInspectorTrait, GetSetValueTrait

Retrieve $ENTITIES for an autocomplete form field.

Properties

$_debugOutput : mixed
$filters : array<string|int, mixed>: Search conditions that will be automatically added to the WHERE or HAVING clauses
$_actionName : string
$_apiParams : array{select: array, where: array, having: array, orderBy: array, limit: int, offset: int, checkPermissions: bool, debug: bool}
$_displayType : 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.
$display : string|array<string|int, mixed>|null: Either the name of the display or an array containing the display definition (for preview mode)
$fieldName : string
$formName : string
$ids : array<string|int, mixed>: Array of ids for render mode
$input : string: Autocomplete search input for search mode
$key : string: Unique identifier to be returned as key (typically `id` or `name`)
$language : string: Preferred language (optional)
$page : int
$savedSearch : string|array<string|int, mixed>: Name of SavedSearch to use for filtering.
$values : array<string|int, mixed>: Known entity values.
$version : int: Api version number; cannot be changed.
$_arrayStorage : array<string|int, mixed>
$_entityFields : array<string|int, mixed>
$_id : int
$_joinMap : array<string|int, mixed>
$_paramInfo : array<string|int, mixed>
$_reflection : ReflectionClass
$_searchEntityFields : array<string|int, mixed>
$_selectClause : array<string|int, mixed>
$_selectQuery : Api4SelectQuery
$trustedFilters : array<string|int, mixed>: Filters set programmatically by `civi.api.prepare` listener. Automatically trusted.

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: Fetch results.
addChain() : $this
addFilter() : mixed: Method for `civi.api.prepare` listener to add a trusted filter.
addValue() : $this: Add an item to the values 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
getFieldName() : string
getFilters() : array<string|int, mixed>
getFormName() : string
getIds() : array<string|int, mixed>
getInput() : string
getKey() : string
getLanguage() : string|null
getPage() : 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>
getSelectClause() : array<string|int, SqlExpression, dataType: string}>: Returns the select clause enhanced with metadata
getValue() : mixed|null: Retrieve a single value, transforming pseudoconstants as necessary
getValues() : array<string|int, mixed>
offsetExists() : bool
offsetGet() : mixed
offsetSet() : void
offsetUnset() : void
paramExists() : bool
reflect() : ReflectionClass
setChain() : $this
setCheckPermissions() : $this
setDebug() : $this
setFieldName() : $this
setFilters() : $this
setFormName() : $this
setIds() : $this
setInput() : $this
setKey() : $this
setLanguage() : $this
setPage() : $this
setValues() : $this: Overwrite all values
setVersion() : $this
addCallbackToDebugOutput() : mixed: When in debug mode, this logs the callback function being used by a Basic*Action class.
applyFilter() : mixed
checkPermissionToLoadSearch() : mixed: Only SearchKit admins can use unsecured "preview mode" and pass an array for savedSearch or display
checkRequiredFields() : array<string|int, mixed>: Validates required fields for actions which create a new object.
formatWriteValues() : mixed: Replaces pseudoconstants in input values
getColumnLabel() : string
getField() : array<string|int, mixed>|null: Returns field definition for a given field or NULL if not found
getJoin() : array{entity: string, alias: string, table: string, bridge: string|null}|null
getJoinLabel() : string
getJoins() : array<string|int, array{entity: string, alias: string, table: string, bridge: string|null}>
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>
getSelectExpression() : SqlExpression, dataType: string}|null
getTokens() : array<string|int, mixed>: Search a string for all square bracket tokens and return their contents (without the brackets)
hasValue() : bool: Checks if a filter contains a non-empty value
loadSavedSearch() : mixed: If SavedSearch is supplied as a string, this will load it as an array
loadSearchDisplay() : void: Loads display if not already an array
augmentSelectClause() : mixed: Ensure SELECT param includes all display fields & trusted filters
canAggregate() : bool: Determines if a column belongs to an aggregate grouping
getDisplayFields() : array<string|int, mixed>: Gather all fields used by the display
getEntityFields() : array<string|int, mixed>: Used as a fallback for non-DAO entities which don't use the Query object
getKeyField() : string: Get the field by which results will be keyed (typically `id` unless $this->key is set).
getQuery() : Api4SelectQuery|bool: Returns a Query object for the search entity, or FALSE if it doesn't have a DAO
renameIfAggregate() : string

$_debugOutput


    public
        mixed
    $_debugOutput
     = []

$filters

Search conditions that will be automatically added to the WHERE or HAVING clauses


    public
        array<string|int, mixed>
    $filters
     = []

Format: [fieldName => value][]

$_actionName


    protected
        string
    $_actionName

$_apiParams


    protected
        array{select: array, where: array, having: array, orderBy: array, limit: int, offset: int, checkPermissions: bool, debug: bool}
    $_apiParams

$_displayType


    protected
        string
    $_displayType
     = 'autocomplete'

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

$display

Either the name of the display or an array containing the display definition (for preview mode)


    protected
        string|array<string|int, mixed>|null
    $display

Leave NULL to use the autogenerated default.

$fieldName


    protected
        string
    $fieldName

$formName


    protected
        string
    $formName

$ids

Array of ids for render mode


    protected
        array<string|int, mixed>
    $ids

$input

Autocomplete search input for search mode


    protected
        string
    $input
     = ''

$key

Unique identifier to be returned as key (typically `id` or `name`)


    protected
        string
    $key

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

$page


    protected
        int
    $page
     = 1

$savedSearch

Name of SavedSearch to use for filtering.


    protected
        string|array<string|int, mixed>
    $savedSearch

$values

Known entity values.


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

Value will be populated by the form based on data entered at the time. They can be used by hooks for contextual filtering.

Format: [fieldName => value][]

$version

Api version number; cannot be changed.


    protected
        int
    $version
     = 4

$_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

$_joinMap


    private
        array<string|int, mixed>
    $_joinMap

$_paramInfo


    private
        array<string|int, mixed>
    $_paramInfo

$_reflection


    private
        ReflectionClass
    $_reflection

$_searchEntityFields


    private
        array<string|int, mixed>
    $_searchEntityFields

$_selectClause


    private
        array<string|int, mixed>
    $_selectClause

$_selectQuery


    private
        Api4SelectQuery
    $_selectQuery

$trustedFilters

Filters set programmatically by `civi.api.prepare` listener. Automatically trusted.


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

Format: [fieldName => value][]

__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()

Fetch results.


    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

addFilter()

Method for `civi.api.prepare` listener to add a trusted filter.


    public
                    addFilter(string $fieldName, mixed $value) : mixed

Parameters

$fieldName : string
$value : mixed

addValue()

Add an item to the values array.


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

Parameters

$fieldName : string
$value : mixed

Return values

$this

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

getFieldName()


    public
                    getFieldName() : string

Return values

string

getFilters()


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

Return values

array<string|int, mixed>

getFormName()


    public
                    getFormName() : string

Return values

string

getIds()


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

Return values

array<string|int, mixed>

getInput()


    public
                    getInput() : string

Return values

string

getKey()


    public
                    getKey() : string

Return values

string

getLanguage()


    public
                    getLanguage() : string|null

Return values

string|null

getPage()


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

getSelectClause()

Returns the select clause enhanced with metadata


    public
                    getSelectClause() : array<string|int, SqlExpression, dataType: string}>

Return values

array<string|int, SqlExpression, dataType: string}>

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>

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

setFieldName()


    public
                    setFieldName([string $fieldName =  ]) : $this

Set fieldName.

Parameters

$fieldName : string =

Return values

$this

setFilters()


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

Parameters

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

Return values

$this

setFormName()


    public
                    setFormName([string $formName =  ]) : $this

Set formName.

Parameters

$formName : string =

Return values

$this

setIds()


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

Set array of ids.

Parameters

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

Return values

$this

setInput()


    public
                    setInput([string $input =  ]) : $this

Set input term.

Parameters

$input : string =

Return values

$this

setKey()


    public
                    setKey([string $key =  ]) : $this

Set keyField used as unique identifier.

Parameters

$key : string =

Return values

$this

setLanguage()


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

Parameters

$language : string|null =

Return values

$this

setPage()


    public
                    setPage([int $page =  ]) : $this

Set current page.

Parameters

$page : int =

Return values

$this

setValues()

Overwrite all values


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

Parameters

$values : array<string|int, mixed>

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

applyFilter()


    protected
                    applyFilter(string|array<string|int, mixed> $fieldName, mixed $value) : mixed

Parameters

$fieldName : string|array<string|int, mixed>: If multiple field names are given they will be combined in an OR clause
$value : mixed

checkPermissionToLoadSearch()

Only SearchKit admins can use unsecured "preview mode" and pass an array for savedSearch or display


    protected
                    checkPermissionToLoadSearch() : mixed

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>

formatWriteValues()

Replaces pseudoconstants in input values


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

Parameters

$record : array<string|int, mixed>

getColumnLabel()


    protected
                    getColumnLabel(SqlExpression $expr) : string

Parameters

$expr : SqlExpression

Return values

string

getField()

Returns field definition for a given field or NULL if not found


    protected
                    getField(mixed $fieldName) : array<string|int, mixed>|null

Parameters

$fieldName : mixed

Return values

array<string|int, mixed>|null

getJoin()


    protected
                    getJoin(string $joinAlias) : array{entity: string, alias: string, table: string, bridge: string|null}|null

Parameters

$joinAlias : string: Alias of the join, with or without the trailing dot

Return values

array{entity: string, alias: string, table: string, bridge: string|null}|null

getJoinLabel()


    protected
                    getJoinLabel(string $joinAlias) : string

Parameters

$joinAlias : string

Return values

string

getJoins()


    protected
                    getJoins() : array<string|int, array{entity: string, alias: string, table: string, bridge: string|null}>

Return values

array<string|int, array{entity: string, alias: string, table: string, bridge: 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>

getSelectExpression()


    protected
                    getSelectExpression(string $key) : SqlExpression, dataType: string}|null

Parameters

$key : string

Return values

SqlExpression, dataType: string}|null

getTokens()

Search a string for all square bracket tokens and return their contents (without the brackets)


    protected
                    getTokens(string $str) : array<string|int, mixed>

Parameters

$str : string

Return values

array<string|int, mixed>

hasValue()

Checks if a filter contains a non-empty value


    protected
                    hasValue(mixed $value) : bool

"Empty" search values are [], '', and NULL. Also recursively checks arrays to ensure they contain at least one non-empty value.

Parameters

$value : mixed

Return values

bool

loadSavedSearch()

If SavedSearch is supplied as a string, this will load it as an array


    protected
                    loadSavedSearch([int|null $id = NULL ]) : mixed

Parameters

$id : int|null = NULL

loadSearchDisplay()

Loads display if not already an array


    protected
                    loadSearchDisplay() : void

augmentSelectClause()

Ensure SELECT param includes all display fields & trusted filters


    private
                    augmentSelectClause(string $idField, array<string|int, mixed> $displayFields) : mixed

Parameters

$idField : string
$displayFields : array<string|int, mixed>

canAggregate()

Determines if a column belongs to an aggregate grouping


    private
                    canAggregate(string $fieldPath) : bool

Parameters

$fieldPath : string

Return values

bool

getDisplayFields()

Gather all fields used by the display


    private
                    getDisplayFields() : array<string|int, mixed>

Return values

array<string|int, mixed>

getEntityFields()

Used as a fallback for non-DAO entities which don't use the Query object


    private
                    getEntityFields() : array<string|int, mixed>

Return values

array<string|int, mixed>

getKeyField()

Get the field by which results will be keyed (typically `id` unless $this->key is set).


    private
                    getKeyField() : string

If $this->key param is set, it will allow it ONLY if the field is a unique index on the entity. This is a security measure. Allowing any value could give access to potentially sensitive data.

Return values

string

getQuery()

Returns a Query object for the search entity, or FALSE if it doesn't have a DAO


    private
                    getQuery() : Api4SelectQuery|bool

Return values

Api4SelectQuery|bool

renameIfAggregate()


    private
                    renameIfAggregate(string $fieldPath[, bool $asSelect = FALSE ]) : string

Parameters

$fieldPath : string
$asSelect : bool = FALSE

Return values

string

AutocompleteAction extends AbstractAction in package Application uses SavedSearchInspectorTrait, GetSetValueTrait

Tags

Table of Contents

Properties

Methods

Properties

$_debugOutput

$filters

$_actionName

$_apiParams

$_displayType

Tags

$_entityName

$chain

$checkPermissions

$debug

$display

$fieldName

$formName

$ids

$input

$key

$language

Tags

$page

$savedSearch

$values

$version

$_arrayStorage

$_entityFields

$_id

Tags

$_joinMap

$_paramInfo

$_reflection

$_searchEntityFields

$_selectClause

$_selectQuery

$trustedFilters

Methods

__call()

Parameters

Tags

Return values

__construct()

Parameters

__set()

Parameters

Tags

_run()

Parameters

addChain()

Parameters

Return values

addFilter()

Parameters

addValue()

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

Return values

getFieldName()

AutocompleteAction extends AbstractAction
in package

Application

uses SavedSearchInspectorTrait, GetSetValueTrait