Documentation

WhitelistRule
in package

A WhitelistRule is used to determine if an API call is authorized.

For example:

new WhitelistRule(array(
  'entity' => 'Contact',
  'actions' => array('get','getsingle'),
  'required' => array('contact_type' => 'Organization'),
  'fields' => array('id', 'display_name', 'sort_name', 'created_date'),
));

This rule would allow API requests that attempt to get contacts of type "Organization", but only a handful of fields ('id', 'display_name', 'sort_name', 'created_date') can be filtered or returned.

Class WhitelistRule

Table of Contents

Properties

$actions  : string|array<string|int, mixed>
List of actions which match, or '*' (all actions)
$entity  : string
Entity name or '*' (all entities)
$fields  : array<string|int, mixed>
List of fields which may be optionally inputted or returned, or '*" (all fields)
$IGNORE_FIELDS  : mixed
$required  : array<string|int, mixed>
List of key=>value pairs that *must* appear in $params.
$version  : int

Methods

__construct()  : mixed
createAll()  : array<string|int, mixed>
Create a batch of rules from an array.
filter()  : array<string|int, mixed>
Ensure that the return values comply with the whitelist's "fields" policy.
isValid()  : bool
matches()  : string|true
filterFields()  : array<string|int, mixed>
Determine which elements in $keys are acceptable under the whitelist policy.

Properties

$actions

List of actions which match, or '*' (all actions)

public string|array<string|int, mixed> $actions

$entity

Entity name or '*' (all entities)

public string $entity

$fields

List of fields which may be optionally inputted or returned, or '*" (all fields)

public array<string|int, mixed> $fields

$IGNORE_FIELDS

public static mixed $IGNORE_FIELDS = ['check_permissions', 'debug', 'offset', 'option_offset', 'option_limit', 'option_sort', 'options', 'return', 'rowCount', 'sequential', 'sort', 'version']

$required

List of key=>value pairs that *must* appear in $params.

public array<string|int, mixed> $required

If there are no required fields, use an empty array.

Methods

__construct()

public __construct(mixed $ruleSpec) : mixed
Parameters
$ruleSpec : mixed

createAll()

Create a batch of rules from an array.

public static createAll(array<string|int, mixed> $rules) : array<string|int, mixed>
Parameters
$rules : array<string|int, mixed>
Return values
array<string|int, mixed>

filter()

Ensure that the return values comply with the whitelist's "fields" policy.

public filter(array<string|int, mixed> $apiRequest, array<string|int, mixed> $apiResult) : array<string|int, mixed>

Most API's follow a convention where the result includes a 'values' array (which in turn is a list of records). Unfortunately, some don't. If the API result doesn't meet our expectation, then we probably don't know what's going on, so we abort the request.

This will probably break some of the layered-sugar APIs (like getsingle, getvalue). Just use the meat-and-potatoes API instead. Or craft a suitably targeted patch.

Parameters
$apiRequest : array<string|int, mixed>

API request.

$apiResult : array<string|int, mixed>

API result.

Tags
throws
CRM_Core_Exception
Return values
array<string|int, mixed> —

Modified API result.

matches()

public matches(array<string|int, mixed> $apiRequest) : string|true
Parameters
$apiRequest : array<string|int, mixed>

Parsed API request.

Return values
string|true —

If match, return TRUE. Otherwise, return a string with an error code.

filterFields()

Determine which elements in $keys are acceptable under the whitelist policy.

protected filterFields(array<string|int, mixed> $keys) : array<string|int, mixed>
Parameters
$keys : array<string|int, mixed>

List of possible keys.

Return values
array<string|int, mixed> —

List of acceptable keys.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results