Documentation

SqlFunction extends SqlExpression
in package

AbstractYes

Base class for all APIv4 Sql function definitions.

SqlFunction classes don't actually process data, SQL itself does the real work. The role of each SqlFunction class is to:

  1. Whitelist a standard SQL function, or define a custom one, for use by APIv4 (it doesn't allow any that don't have a SQLFunction class).
  2. Document what the function does and what arguments it accepts.
  3. Tell APIv4 how to treat the inputs and how to format the outputs.

Table of Contents

Constants

CATEGORY_AGGREGATE  = 'aggregate'
CATEGORY_COMPARISON  = 'comparison'
CATEGORY_DATE  = 'date'
CATEGORY_MATH  = 'math'
CATEGORY_STRING  = 'string'

Properties

$expr  : string
The raw expression, minus the alias.
$supportsExpansion  : bool
Whether or not pseudoconstant suffixes should be evaluated during output.
$alias  : string|null
The SELECT alias (if null it will be calculated by getAlias)
$args  : array<string|int, array<string|int, mixed>>
$category  : string
Used for categorizing functions in the UI
$dataType  : string
Data type output by this expression
$fields  : array<string|int, string>
Field names used in this expression
$suffix  : string
Pseudoconstant suffix (for functions with option lists)

Methods

__construct()  : mixed
SqlFunction constructor.
convert()  : SqlExpression
Converts a string to a SqlExpression object.
formatOutputValue()  : void
Set $dataType and convert value by suffix
getAlias()  : string
Returns the alias to use for SELECT AS.
getArgs()  : array<string|int, SqlExpression}>
Get the arguments passed to this sql function instance.
getCategory()  : string
getDataType()  : string|null
getDescription()  : string
getExpr()  : string
getFields()  : array<string|int, mixed>
Returns the field names of all sql columns that are arguments to this expression.
getName()  : string
Get the name of this sql function.
getOptions()  : array<string|int, mixed>|null
For functions which output a finite set of values, this allows the API to treat it as pseudoconstant options.
getParams()  : array<string|int, mixed>
Get the param metadata for this sql function.
getSerialize()  : int|null
Get value serialization method if any.
getTitle()  : string
getType()  : string
All functions return 'SqlFunction' as their type.
isType()  : bool
Checks the name of this sql expression class.
render()  : string
Render the expression for insertion into the sql query
renderExpression()  : string
Render the final expression
captureExpression()  : string
Scans the beginning of a string for an expression; stops when it hits delimiter
captureExpressions()  : array<string|int, SqlExpression>
Shifts 0 or more expressions off the argument string and returns them
captureKeyword()  : mixed|null
Shift a keyword off the beginning of the argument string and return it.
initialize()  : mixed
Parse the argument string into an array of function arguments
params()  : array<string|int, mixed>
munge()  : mixed
renderArg()  : string
setSuffix()  : void

Constants

CATEGORY_AGGREGATE

public mixed CATEGORY_AGGREGATE = 'aggregate'

CATEGORY_COMPARISON

public mixed CATEGORY_COMPARISON = 'comparison'

CATEGORY_STRING

public mixed CATEGORY_STRING = 'string'

Properties

$expr

The raw expression, minus the alias.

public string $expr = ''

$supportsExpansion

Whether or not pseudoconstant suffixes should be evaluated during output.

public bool $supportsExpansion = FALSE
Tags
see
FormattingUtil::formatOutputValues

$alias

The SELECT alias (if null it will be calculated by getAlias)

protected string|null $alias

$args

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

$category

Used for categorizing functions in the UI

protected static string $category

$dataType

Data type output by this expression

protected static string $dataType

$fields

Field names used in this expression

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

$suffix

Pseudoconstant suffix (for functions with option lists)

private string $suffix

Methods

__construct()

SqlFunction constructor.

public __construct(string $expr[, string|null $alias = NULL ]) : mixed
Parameters
$expr : string
$alias : string|null = NULL

convert()

Converts a string to a SqlExpression object.

public static convert(string $expression[, bool $parseAlias = FALSE ][, array<string|int, mixed> $mustBe = [] ]) : SqlExpression

E.g. the expression "SUM(foo)" would return a SqlFunctionSUM object.

Parameters
$expression : string
$parseAlias : bool = FALSE
$mustBe : array<string|int, mixed> = []
Tags
throws
CRM_Core_Exception
Return values
SqlExpression

formatOutputValue()

Set $dataType and convert value by suffix

public formatOutputValue(string|null &$dataType, array<string|int, mixed> &$values, string $key) : void
Parameters
$dataType : string|null
$values : array<string|int, mixed>
$key : string
Tags
see
FormattingUtil::formatOutputValues

getAlias()

Returns the alias to use for SELECT AS.

public getAlias() : string
Tags
inheritDoc
Return values
string

getArgs()

Get the arguments passed to this sql function instance.

public getArgs() : array<string|int, SqlExpression}>
Return values
array<string|int, SqlExpression}>

getCategory()

public static getCategory() : string
Return values
string

getDataType()

public static getDataType() : string|null
Return values
string|null

getDescription()

public abstract static getDescription() : string
Return values
string

getFields()

Returns the field names of all sql columns that are arguments to this expression.

public getFields() : array<string|int, mixed>
Return values
array<string|int, mixed>

getName()

Get the name of this sql function.

public static getName() : string
Return values
string

getOptions()

For functions which output a finite set of values, this allows the API to treat it as pseudoconstant options.

public static getOptions() : array<string|int, mixed>|null

e.g. MONTH() only returns integers 1-12, which can be formatted like [1 => January, 2 => February, etc.]

Return values
array<string|int, mixed>|null

getParams()

Get the param metadata for this sql function.

public final static getParams() : array<string|int, mixed>
Return values
array<string|int, mixed>

getSerialize()

Get value serialization method if any.

public getSerialize() : int|null
Return values
int|null

getTitle()

public abstract static getTitle() : string
Return values
string

getType()

All functions return 'SqlFunction' as their type.

public getType() : string

To get the function name @see SqlFunction::getName()

Return values
string

isType()

Checks the name of this sql expression class.

public isType(mixed $type) : bool
Parameters
$type : mixed
Return values
bool

render()

Render the expression for insertion into the sql query

public render(Api4Query $query[, bool $includeAlias = FALSE ]) : string
Parameters
$query : Api4Query
$includeAlias : bool = FALSE
Return values
string

renderExpression()

Render the final expression

public static renderExpression(string $output) : string
Parameters
$output : string
Return values
string

captureExpression()

Scans the beginning of a string for an expression; stops when it hits delimiter

protected captureExpression(mixed $arg) : string
Parameters
$arg : mixed
Return values
string

captureExpressions()

Shifts 0 or more expressions off the argument string and returns them

protected captureExpressions(string &$arg, array<string|int, mixed> $mustBe, int $max) : array<string|int, SqlExpression>
Parameters
$arg : string
$mustBe : array<string|int, mixed>
$max : int
Tags
throws
CRM_Core_Exception
Return values
array<string|int, SqlExpression>

captureKeyword()

Shift a keyword off the beginning of the argument string and return it.

protected captureKeyword(array<string|int, mixed> $keywords, string &$arg) : mixed|null
Parameters
$keywords : array<string|int, mixed>

Whitelist of keywords

$arg : string
Return values
mixed|null

initialize()

Parse the argument string into an array of function arguments

protected initialize() : mixed

params()

protected abstract static params() : array<string|int, mixed>
Return values
array<string|int, mixed>

munge()

private static munge(mixed $name[, mixed $char = '_' ][, mixed $len = 63 ]) : mixed
Parameters
$name : mixed
$char : mixed = '_'
$len : mixed = 63

renderArg()

private renderArg(array<string|int, mixed> $arg, Api4Query $query) : string
Parameters
$arg : array<string|int, mixed>
$query : Api4Query
Return values
string

setSuffix()

private setSuffix(string|null $suffix) : void
Parameters
$suffix : string|null 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results