Documentation

ValidateValuesEvent extends GenericHookEvent
in package
uses RequestTrait

The ValidateValuesEvent ('civi.api4.validate') is emitted when creating or saving an entire record via APIv4.

It is emitted once for every record is updated.

Example #1: Walk each record and validate some fields

function(ValidateValuesEvent $e) { if ($e->entity !== 'Foozball') return; foreach ($e->records as $r => $record) { if (strtotime($record['start_time']) < CRM_Utils_Time::time()) { $e->addError($r, 'start_time', 'past', ts('Start time has already passed.')); } if ($record['length'] * $record['width'] * $record['height'] > VOLUME_LIMIT) { $e->addError($r, ['length', 'width', 'height'], 'excessive_volume', ts('The record is too big.')); } } }

Example #2: Prohibit recording Contribution records on Student contacts.

function(ValidateValuesEvent $e) { if ($e->entity !== 'Contribution') return; $contactSubTypes = CRM_Utils_SQL_Select::from('civicrm_contact') ->where('id IN (#ids)', ['ids' => array_column($e->records, 'contact_id')]) ->select('id, contact_sub_type') ->execute()->fetchMap('id', 'contact_sub_type'); foreach ($e->records as $r => $record) { if ($contactSubTypes[$record['contact_id']] === 'Student') { $e->addError($r, 'contact_id', 'student_prohibited', ts('Donations from student records are strictly prohibited.')); } } }

Table of Contents

Properties

$diffs  : array<string|int, mixed>|CRM_Utils_LazyArray
Detailed, side-by-side comparison of old and new values.
$errors  : array<string|int, mixed>
List of error messages.
$records  : array<string|int, mixed>|CRM_Utils_LazyArray
List of updated records.
$apiRequest  : AbstractAction|array<string|int, mixed>
$hookFields  : array<string|int, mixed>
$hookFieldsFlip  : array<string|int, mixed>
$hookValues  : array<string|int, mixed>
$BLACKLIST  : array<string|int, mixed>
List of field names that are prohibited due to conflicts in the class-hierarchy.
$returnValues  : mixed
Some legacy hooks expect listener-functions to return a value.

Methods

__construct()  : mixed
ValidateValuesEvent constructor.
__get()  : mixed
__isset()  : mixed
__set()  : mixed
__unset()  : mixed
addError()  : $this
Add an error.
addReturnValues()  : GenericHookEvent
create()  : GenericHookEvent
Create a GenericHookEvent using key-value pairs.
createOrdered()  : GenericHookEvent
Create a GenericHookEvent using ordered parameters.
getActionName()  : string
getApiRequest()  : AbstractAction|array<string|int, mixed>
getApiRequestSig()  : string
Create a brief string identifying the entity/action. Useful for pithy matching/switching.
getEntityName()  : string
getHookValues()  : array<string|int, mixed>
getReturnValues()  : mixed
hasField()  : bool
Determine whether the hook supports the given field.
toException()  : CRM_Core_Exception
Convert the list of errors an exception.
setApiRequest()  : static
assertValidHookFields()  : mixed

Properties

$diffs

Detailed, side-by-side comparison of old and new values.

public array<string|int, mixed>|CRM_Utils_LazyArray $diffs

This requires loading the list of old values from the database. Consequently, reading $diffs is more expensive than reading $records, so you should only use it if really necessary.

The list of $diffs may be important if you are enforcing a rule that involves multiple fields. (Ex: "Validate that the state_id and country_id match.")

When possible, $records and $diffs will have the same number of items (with corresponding keys). However, in the case of a batch update(), the list of diffs will be longer.

Each item is a record of the form ['old' => $fieldValues, 'new' => $fieldValues]

$errors

List of error messages.

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

Array(string $errorName => string $errorMessage) Note:

$records

List of updated records.

public array<string|int, mixed>|CRM_Utils_LazyArray $records

The list of $records reflects only the list of new values assigned by this action. It may or may not correspond to an existing row in the database. It is similar to the $records list used by save().

Tags
see
AbstractSaveAction::$records

$apiRequest

protected AbstractAction|array<string|int, mixed> $apiRequest

The full description of the API request.

Tags
see
Request::create

$hookFields

protected array<string|int, mixed> $hookFields

Ex: array(0 => 'contactID', 1 => 'contentPlacement').

$hookFieldsFlip

protected array<string|int, mixed> $hookFieldsFlip

Ex: array('contactID' => 0, 'contentPlacement' => 1).

$hookValues

protected array<string|int, mixed> $hookValues

Ex: array(0 => &$contactID, 1 => &$contentPlacement).

$BLACKLIST

List of field names that are prohibited due to conflicts in the class-hierarchy.

private static array<string|int, mixed> $BLACKLIST = ['name', 'dispatcher', 'propagationStopped', 'hookBlacklist', 'hookValues', 'hookFields', 'hookFieldsFlip']

$returnValues

Some legacy hooks expect listener-functions to return a value.

private mixed $returnValues = []

OOP listeners may set the $returnValue.

This field is not recommended for use in new hooks. The return-value convention is not portable across different implementations of the hook system. Instead, it's more portable to provide an alterable, named field.

Methods

__construct()

ValidateValuesEvent constructor.

public __construct(AbstractAction $apiRequest, array<string|int, mixed>|CRM_Utils_LazyArray $records, array<string|int, mixed>|CRM_Utils_LazyArray $diffs) : mixed
Parameters
$apiRequest : AbstractAction
$records : array<string|int, mixed>|CRM_Utils_LazyArray

List of updates (akin to SaveAction::$records).

$diffs : array<string|int, mixed>|CRM_Utils_LazyArray

List of differences (comparing old values and new values).

__get()

public & __get(mixed $name) : mixed
Parameters
$name : mixed
Tags
inheritDoc

__isset()

public __isset(mixed $name) : mixed
Parameters
$name : mixed
Tags
inheritDoc

__set()

public __set(mixed $name, mixed $value) : mixed
Parameters
$name : mixed
$value : mixed
Tags
inheritDoc

__unset()

public __unset(mixed $name) : mixed
Parameters
$name : mixed
Tags
inheritDoc

addError()

Add an error.

public addError(string|int $recordKey, string|array<string|int, mixed> $field, string $name[, string|null $message = NULL ]) : $this
Parameters
$recordKey : string|int

The validator may work with multiple records. This should identify the specific record. Each record is identified by its offset ($records[$recordKey] === [...the record...]).

$field : string|array<string|int, mixed>

The name of the field which has an error. If the error is multi-field (e.g. mismatched password-confirmation), then use an array. If the error is independent of any field, then use [].

$name : string
$message : string|null = NULL
Return values
$this

create()

Create a GenericHookEvent using key-value pairs.

public static create(array<string|int, mixed> $params) : GenericHookEvent
Parameters
$params : array<string|int, mixed>

Ex: array('contactID' => &$contactID, 'contentPlacement' => &$contentPlacement).

Return values
GenericHookEvent

createOrdered()

Create a GenericHookEvent using ordered parameters.

public static createOrdered(array<string|int, mixed> $hookFields, array<string|int, mixed> $hookValues) : GenericHookEvent
Parameters
$hookFields : array<string|int, mixed>

Ex: array(0 => 'contactID', 1 => 'contentPlacement').

$hookValues : array<string|int, mixed>

Ex: array(0 => &$contactID, 1 => &$contentPlacement).

Return values
GenericHookEvent

getActionName()

public getActionName() : string
Return values
string —

Ex: 'create', 'update'

getApiRequestSig()

Create a brief string identifying the entity/action. Useful for pithy matching/switching.

public getApiRequestSig() : string

Ex: if ($e->getApiRequestSig() === '3.contact.get') { ... }

Return values
string —

Ex: '3.contact.get'

getEntityName()

public getEntityName() : string
Return values
string —

Ex: 'Contact', 'Activity'

getHookValues()

public getHookValues() : array<string|int, mixed>
Tags
inheritDoc
Return values
array<string|int, mixed> —

Ex: array(0 => &$contactID, 1 => &$contentPlacement).

hasField()

Determine whether the hook supports the given field.

public hasField(string $name) : bool

The field may or may not be empty. Use isset() or empty() to check that.

Parameters
$name : string
Return values
bool

setApiRequest()

protected setApiRequest(AbstractAction|array<string|int, mixed> $apiRequest) : static
Parameters
$apiRequest : AbstractAction|array<string|int, mixed>

The full description of the API request.

Return values
static

assertValidHookFields()

private static assertValidHookFields(array<string|int, mixed> $fields) : mixed
Parameters
$fields : array<string|int, mixed>

List of field names.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results