Documentation

GetLinks extends BasicGetAction
in package

Application

uses GetSetValueTrait

Get action links for the $ENTITY entity.

Action links are paths to forms for e.g. view, edit, or delete actions.

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.
$entityTitle : bool|string
$expandMultiple : bool: Should multiple links e.g. to create different subtypes all be returned?
$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.
$select : array<string|int, mixed>: Fields to return for each $ENTITY. Defaults to all fields `[*]`.
$values : array<string|int, mixed>: Links will be returned appropriate to the specified values (e.g. ['contact_type' => 'Individual'])
$version : int: Api version number; cannot be changed.
$where : array<string|int, mixed>: Criteria for selecting $ENTITIES.
$_arrayStorage : array<string|int, mixed>
$_entityFields : array<string|int, mixed>
$_id : int
$_paramInfo : array<string|int, mixed>
$_reflection : ReflectionClass
$getter : callable

Methods

__call() : static|mixed: Magic function to provide automatic getter/setter for params.
__construct() : mixed: Basic Get constructor.
__set() : mixed: Strictly enforce api parameters
_run() : mixed: Fetch results from the getter then apply filter/sort/select/limit.
addChain() : $this
addClause() : $this: Adds one or more AND/OR/NOT clause groups
addOrderBy() : $this: Adds to the orderBy clause
addSelect() : $this: Add one or more fields to be selected (wildcard * allowed)
addValue() : $this: Add an item to the values array.
addWhere() : $this
compareValues() : bool
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.
expandSelectClauseWildcards() : mixed: Adds all standard fields matched by the * wildcard
fields() : mixed
filterCompare() : bool
getActionName() : string
getChain() : array<string|int, mixed>
getCheckPermissions() : bool
getDebug() : bool
getEntityName() : string
getEntityTitle() : string
getExpandMultiple() : bool
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>
getValue() : mixed|null: Retrieve a single value, transforming pseudoconstants as necessary
getValues() : array<string|int, mixed>
getWhere() : array<string|int, mixed>
offsetExists() : bool
offsetGet() : mixed
offsetSet() : void
offsetUnset() : void
paramExists() : bool
reflect() : ReflectionClass
selectRowCount() : $this: Only return the number of found items.
setChain() : $this
setCheckPermissions() : $this
setDebug() : $this
setDefaultWhereClause() : mixed: Adds field defaults to the where clause.
setEntityTitle() : $this
setExpandMultiple() : $this
setLanguage() : $this
setLimit() : $this
setOffset() : $this
setOrderBy() : $this
setValues() : $this: Overwrite all values
setVersion() : $this
setWhere() : $this
_isFieldSelected() : bool: Helper to see if field(s) should be selected by the getRecords function.
_itemsToGet() : array<string|int, mixed>|null: Helper to parse the WHERE param for getRecords to perform simple pre-filtering.
_whereContains() : bool: Walk through the where clause and check if field(s) are in use.
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.
filterArray() : array<string|int, mixed>
formatRawValues() : mixed: Evaluate :pseudoconstant suffix expressions and replace raw values with option values
formatWriteValues() : mixed: Replaces pseudoconstants in input values
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>
getRecords() : array<string|int, mixed>: BasicGet is a general-purpose get action for non-DAO-based entities.
limitArray() : array<string|int, mixed>
queryArray() : mixed
selectArray() : array<string|int, mixed>
sortArray() : array<string|int, mixed>
whereClauseToString() : string: Produces a human-readable where clause, for the reading enjoyment of you humans.
evaluateFilters() : bool
fetchLinks() : array<string|int, mixed>: Get the full set of links for an entity
filterByPermission() : void
getAllowedEntityActions() : array<string|int, mixed>
isActionAllowed() : bool
replaceTokens() : void: Replace [square_bracket] tokens in the path and `%1` placeholders in the text.
sortCompare() : mixed
walkFilters() : bool

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

$entityTitle


    protected
        bool|string
    $entityTitle
     = TRUE

$expandMultiple

Should multiple links e.g. to create different subtypes all be returned?


    protected
        bool
    $expandMultiple
     = FALSE

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

$select

Fields to return for each $ENTITY. Defaults to all fields `[*]`.


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

Use the * wildcard by itself to select all available fields, or use it to match similarly-named fields. E.g. is_* will match fields named is_primary, is_active, etc.

Set to ["row_count"] to return only the number of $ENTITIES found.

$values

Links will be returned appropriate to the specified values (e.g. ['contact_type' => 'Individual'])


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

$version

Api version number; cannot be changed.


    protected
        int
    $version
     = 4

$where

Criteria for selecting $ENTITIES.


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

$example->addWhere('contact_type', 'IN', ['Individual', 'Household'])

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

$_paramInfo


    private
        array<string|int, mixed>
    $_paramInfo

$_reflection


    private
        ReflectionClass
    $_reflection

$getter


    private
        callable
    $getter

Function(BasicGetAction $thisAction): array[]

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

Basic Get constructor.


    public
                    __construct(string $entityName, string $actionName[, callable $getter = NULL ]) : mixed

Parameters

$entityName : string
$actionName : string
$getter : callable = NULL

__set()

Strictly enforce api parameters


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

Parameters

$name : mixed
$value : mixed

_run()

Fetch results from the getter then apply filter/sort/select/limit.


    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

addSelect()

Add one or more fields to be selected (wildcard * allowed)


    public
                    addSelect(string ...$fieldNames) : $this

Parameters

$fieldNames : string

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

compareValues()


    public
            static        compareValues(mixed $value, string $operator, mixed $expected) : bool

Parameters

$value : mixed
$operator : string
$expected : mixed

Return values

bool

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

expandSelectClauseWildcards()

Adds all standard fields matched by the * wildcard


    public
                    expandSelectClauseWildcards() : mixed

Note: this function only deals with simple wildcard expressions. It ignores those containing special characters like dots or parentheses, they are handled separately in Api4SelectQuery.

fields()


    public
                    fields() : mixed

filterCompare()


    public
            static        filterCompare(array<string|int, mixed> $row, array<string|int, mixed> $condition[, int|null $index = NULL ]) : bool

Parameters

$row : array<string|int, mixed>
$condition : array<string|int, mixed>
$index : int|null = NULL

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

getDebug()


    public
                    getDebug() : bool

Return values

bool

getEntityName()


    public
                    getEntityName() : string

Return values

string

getEntityTitle()


    public
                    getEntityTitle() : string

Return values

string

getExpandMultiple()


    public
                    getExpandMultiple() : bool

Return values

bool

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>

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>

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

selectRowCount()

Only return the number of found items.


    public
                    selectRowCount() : $this

Return values

$this

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

setDefaultWhereClause()

Adds field defaults to the where clause.


    public
                    setDefaultWhereClause() : mixed

Note: it will skip adding field defaults when fetching records by id, or if that field has already been added to the where clause.

setEntityTitle()


    public
                    setEntityTitle([string $entityTitle =  ]) : $this

Parameters

$entityTitle : string =

Return values

$this

setExpandMultiple()


    public
                    setExpandMultiple([bool $expandMultiple =  ]) : $this

Parameters

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

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

setWhere()


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

Parameters

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

Return values

$this

_isFieldSelected()

Helper to see if field(s) should be selected by the getRecords function.


    protected
                    _isFieldSelected(string ...$fieldNames) : bool

Checks the SELECT, WHERE and ORDER BY params to see what fields are needed.

Note that if no SELECT clause has been set then all fields should be selected and this function will return TRUE for field expressions that don't contain a :pseudoconstant suffix.

Parameters

$fieldNames : string: One or more field names to check (uses OR if multiple)

Return values

bool —

Returns true if any given fields are in use.

_itemsToGet()

Helper to parse the WHERE param for getRecords to perform simple pre-filtering.


    protected
                    _itemsToGet(string $field) : array<string|int, mixed>|null

This is intended to optimize some common use-cases e.g. calling the api to get one or more records by name or id.

Ex: If getRecords fetches a long list of items each with a unique name, but the user has specified a single record to retrieve, you can optimize the call by checking $this->_itemsToGet('name') and only fetching the item(s) with that name.

Parameters

$field : string

Return values

array<string|int, mixed>|null

_whereContains()

Walk through the where clause and check if field(s) are in use.


    protected
                    _whereContains(string|array<string|int, mixed> $fieldName[, array<string|int, mixed> $clauses = NULL ]) : bool

Parameters

$fieldName : string|array<string|int, mixed>: A single fieldName or an array of names (uses OR if multiple)
$clauses : array<string|int, mixed> = NULL

Return values

bool —

Returns true if any given fields are found in the where clause.

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>

filterArray()


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

Parameters

$values : array<string|int, mixed>

Return values

array<string|int, mixed>

formatRawValues()

Evaluate :pseudoconstant suffix expressions and replace raw values with option values


    protected
                    formatRawValues(mixed &$records) : mixed

Parameters

$records : mixed

formatWriteValues()

Replaces pseudoconstants in input values


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

Parameters

$record : array<string|int, mixed>

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>

getRecords()

BasicGet is a general-purpose get action for non-DAO-based entities.


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

Useful for fetching records from files or other places. Specify any php function to retrieve the records, and this class will automatically filter, sort, select & limit the raw data from the callback.

This action is implemented in one of two ways:

Invoke this class directly by passing a callable ($getter) to the constructor. BasicEntity does this by default. The function is passed a copy of $this action as it's first argument.
Extend this class and override this function.

Either way, this function should return an array of arrays, each representing one retrieved object.

The simplest thing for your getter function to do is return every full record and allow this class to automatically do the sorting and filtering.

Sometimes however that may not be practical for performance reasons. To optimize your getter, it can use the following helpers from $this:

Use this->_itemsToGet() to match records to field values in the WHERE clause. Note the WHERE clause can potentially be very complex and it is not recommended to parse $this->where yourself.

Use $this->_isFieldSelected() to check if a field value is called for - useful if loading the field involves expensive calculations.

Be careful not to make assumptions, e.g. if LIMIT 100 is specified and your getter "helpfully" truncates the list at 100 without accounting for WHERE, ORDER BY and LIMIT clauses, the final filtered result may be very incorrect.

Return values

array<string|int, mixed>

limitArray()


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

Parameters

$values : mixed

Return values

array<string|int, mixed>

queryArray()


    protected
                    queryArray(array<string|int, mixed> $values, Result $result) : mixed

Parameters

$values : array<string|int, mixed>: List of all rows to be filtered
$result : Result: Object to store result

selectArray()


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

Parameters

$values : mixed

Return values

array<string|int, mixed>

sortArray()


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

Parameters

$values : mixed

Return values

array<string|int, 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

evaluateFilters()


    private
                    evaluateFilters(array<string|int, mixed> $row) : bool

Parameters

$row : array<string|int, mixed>

Return values

bool

fetchLinks()

Get the full set of links for an entity


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

This function sits behind a cache so the heavy processing happens here.

Return values

array<string|int, mixed>

filterByPermission()


    private
                    filterByPermission(array<string|int, mixed> &$links) : void

Parameters

$links : array<string|int, mixed>

getAllowedEntityActions()


    private
                    getAllowedEntityActions(string $entityName) : array<string|int, mixed>

Parameters

$entityName : string

Return values

array<string|int, mixed>

isActionAllowed()


    private
                    isActionAllowed(string $entityName, string $actionName) : bool

Parameters

$entityName : string
$actionName : string

Return values

bool

replaceTokens()

Replace [square_bracket] tokens in the path and `%1` placeholders in the text.


    private
                    replaceTokens(array<string|int, mixed> &$links) : void

Parameters

$links : array<string|int, mixed>

sortCompare()


    private
                    sortCompare(mixed $a, mixed $b) : mixed

Parameters

$a : mixed
$b : mixed

walkFilters()


    private
                    walkFilters(array<string|int, mixed> $row, array<string|int, mixed> $filters) : bool

Parameters

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

Return values

bool

GetLinks extends BasicGetAction in package Application uses GetSetValueTrait

Table of Contents

Properties

Methods

Properties

$_debugOutput

$_actionName

$_entityName

$chain

$checkPermissions

$debug

$entityTitle

$expandMultiple

$language

Tags

$limit

$offset

$orderBy

$select

$values

$version

$where

$_arrayStorage

$_entityFields

$_id

Tags

$_paramInfo

$_reflection

$getter

Methods

__call()

Parameters

Tags

Return values

__construct()

Parameters

__set()

Parameters

Tags

_run()

Parameters

addChain()

Parameters

Return values

addClause()

Parameters

Tags

Return values

addOrderBy()

Parameters

Return values

addSelect()

Parameters

Return values

addValue()

Parameters

Return values

addWhere()

Parameters

Tags

Return values

compareValues()

Parameters

Return values

entityFields()

Tags

Return values

evaluateCondition()

Parameters

Tags

Return values

execute()

Tags

Return values

expandSelectClauseWildcards()

Tags

fields()

filterCompare()

Parameters

Tags

GetLinks extends BasicGetAction
in package

Application

uses GetSetValueTrait