Documentation

CRM_Contact_BAO_Query
in package

CRM

This is the heart of the search query building mechanism.

Constants

MODE_ACTIVITY = 4096: The various search modes.
MODE_ALL = 17407: The various search modes.
MODE_CAMPAIGN = 8192: The various search modes.
MODE_CASE = 2048: The various search modes.
MODE_CONTACTS = 1: The various search modes.
MODE_CONTACTSRELATED = 32: The various search modes.
MODE_CONTRIBUTE = 2: The various search modes.
MODE_EVENT = 16: The various search modes.
MODE_GRANT = 128: The various search modes.
MODE_MAILING = 16384: The various search modes.
MODE_MEMBER = 8: The various search modes.
MODE_PLEDGE = 512: The various search modes.
MODE_PLEDGEBANK = 256: The various search modes.
NO_RETURN_PROPERTIES = 'CRM_Contact_BAO_Query::NO_RETURN_PROPERTIES': The various search modes.
SEARCH_OPERATOR_AND = 'AND': Constants for search operators
SEARCH_OPERATOR_OR = 'OR': Constants for search operators

Properties

$_activityRole : array<string|int, mixed>: The activity role
$_cfIDs : mixed
$_considerCompActivities : array<string|int, mixed>: Consider the component activity type during activity search.
$_customQuery : object: Reference to the query object for custom values.
$_defaultHierReturnProperties : array<string|int, mixed>: The default set of hier return properties.
$_defaultReturnProperties : array<string|int, mixed>: The default set of return properties.
$_dependencies : array<string|int, mixed>: The tables which have a dependency on location and/or address
$_displayRelationshipType : string: Should we display contacts with a specific relationship type.
$_distinctComponentClause : string: Use distinct component clause for component searches
$_element : array<string|int, mixed>: The name of the elements that are in the select clause used to extract the values.
$_fields : array<string|int, mixed>: All the fields that could potentially be involved in this query
$_fromClause : string: The from string
$_groupByComponentClause : string: Use groupBy component clause for component searches
$_groupKeys : mixed
$_groupUniqueKey : mixed
$_having : array<string|int, mixed>: The having values
$_includeContactIds : bool: Are contact ids part of the query.
$_locationSpecificCustomFields : array<string|int, mixed>: For search builder - which custom fields are location-dependent
$_locationSpecificFields : array<string|int, mixed>: List of location specific fields.
$_mode : mixed
$_onlyDeleted : int
$_openedPanes : array<string|int, mixed>: Track open panes, useful in advance search
$_operator : string: What operator to use to group the clauses.
$_paramLookup : mixed
$_params : array<string|int, mixed>: The set of input params.
$_permissionFromClause : string: Additional permission from clause
$_permissionWhereClause : string: Additional WHERE clause for permissions.
$_primaryLocation : bool: Should we only search on primary location.
$_pseudoConstantsSelect : mixed
$_qill : array<string|int, mixed>: The english language version of the query
$_relationshipTempTable : string: Set to the name of the temp table if one has been created.
$_relType : array<string|int, mixed>: The relationship type direction
$_returnProperties : array<string|int, mixed>: The set of output params
$_rowCountClause : mixed
$_search : bool: Are we in search mode.
$_select : array<string|int, mixed>: The select clause
$_simpleFromClause : string: The from clause for the simple select and alphabetical select
$_skipDeleteClause : bool: Should we skip adding of delete clause.
$_skipPermission : bool: Should we skip permission checking.
$_smartGroupCache : bool: Should we use the smart group cache.
$_sort : mixed
$_strict : bool: Are we in strict mode (use equality over LIKE)
$_tables : array<string|int, mixed>: The tables involved in the query.
$_useDistinct : bool: Should we enable the distinct clause, used if we are including more than one group
$_useGroupBy : bool: Should we just display one contact record
$_where : array<string|int, mixed>: Array of WHERE clause components.
$_whereClause : string: The WHERE clause as a string.
$_whereTables : array<string|int, mixed>: The table involved in the where clause.
$_withContactActivitiesOnly : array<string|int, mixed>: Consider with contact activities only, during activity search.
$_rangeCache : array<string|int, mixed>: Remember if we handle either end of a number or date range so we can skip the other
$_relationshipValuesAdded : bool: Set to true when $this->relationship is run to avoid adding twice.
$legacyHackedFields : array<string|int, mixed>: Fields hacked for legacy reasons.

Methods

__construct() : mixed: Class constructor which also does all the work.
addGroupContactCache() : string: Prime smart group cache for smart groups in the search, and join civicrm_group_contact_cache table into the query.
addHierarchicalElements() : mixed: If the return Properties are set in a hierarchy, traverse the hierarchy to get the return values.
addMultipleElements() : mixed: If the return Properties are set in a hierarchy, traverse the hierarchy to get the return values.
addRelationshipActivePeriodClauses() : mixed: Add start & end active period criteria in
addRelationshipDateClauses() : mixed: Add start & end date criteria in
addRelationshipPermissionClauses() : mixed: Add relationship permission criteria to where clause.
addSpecialFields() : mixed: Some composite fields do not appear in the fields array hack to make them part of the query.
ageRangeQueryBuilder() : mixed
alphabetQuery() : CRM_Core_DAO: Create and query the db for the list of all first letters used by contacts
apiQuery() : array<string|int, mixed>: These are stub comments as this function needs more explanation - particularly in terms of how it relates to $this->searchQuery and why it replicates rather than calles $this->searchQuery.
appendAnyValueToSelect() : string: For some special cases, grouping by subset of select fields becomes mandatory.
buildClause() : string: Given the field name, operator, value & its data type builds the where Clause for the query used for handling 'IS NULL'/'IS NOT NULL' operators
buildDateRangeQuery() : bool: Build the query for a date field if it is a _high or _low field.
buildParamsLookup() : mixed: Function for same purpose as convertFormValues.
buildQillForFieldValue() : array<string|int, mixed>: Build qill for field.
buildWhereForDate() : mixed
calcDateFromAge() : string: Calculate date from age.
caseImportant() : bool: See CRM-19811 for why this is database hurty without apparent benefit.
changeLog() : mixed: Where / qill clause for change log.
componentPresent() : bool
contactSubType() : mixed: Where / qill clause for contact_sub_type.
contactType() : mixed: Where / qill clause for contact_type
convertFormValues() : array<string|int, mixed>: Convert values from form-appropriate to query-object appropriate.
convertGroupIDStringToLabelString() : string: Convert a string of group IDs to a string of group labels.
convertToPseudoNames() : array<string|int, mixed>|null: Convert the pseudo constants id's to their names
country() : array<string|int, mixed>|null
county() : string: Where / qill clause for county (if present).
dateQueryBuilder() : mixed: Build query for a date field.
defaultHierReturnProperties() : array<string|int, mixed>: Default set of return default hier return properties.
defaultReturnProperties() : array<string|int, mixed>: Default set of return properties.
deletedContacts() : mixed: WHERE / QILL clause for deleted_contacts
demographics() : mixed
filterCountryFromValuesIfStateExists() : mixed: If the state and country are passed remove state.
filterRelatedContacts() : mixed
fixDateValues() : mixed: Fix date values.
fixWhereValues() : array<string|int, mixed>|null: Fix values from query from/to something no-one cared enough to document.
fromClause() : string: Create the from clause.
generatePermissionClause() : mixed: Populate $this->_permissionWhereClause with permission related clause and update other query related properties.
getCachedContacts() : CRM_Core_DAO: Fetch a list of contacts for displaying a search results page
getCustomFieldName() : string: Get the actual custom field name by stripping off the appended string.
getDataTypeForRealField() : string: Get the field datatype, using the type in the database rather than the pseudofield, if a pseudofield.
getFieldSpec() : array<string|int, mixed>: Get the specifications for the field, if available.
getGroupByFromOrderBy() : mixed: For some special cases, where if non-aggregate ORDER BY columns are not present in GROUP BY on full_group_by mode, then append the those missing columns to GROUP BY clause keyword to select fields not present in groupBy
getGroupByFromSelectColumns() : string: Include select columns in groupBy clause.
getGroupCacheTableKeys() : array<string|int, mixed>
getGroupsFromTypeCriteria() : array<string|int, mixed>: Function translates selection of group type into a list of groups.
getLocationTableName() : array<string|int, mixed>
getMetadataForRealField() : array<string|int, mixed>: Get the metadata for a given field, returning the 'real field' if it is a pseudofield.
getOperator() : string
getPrimaryCondition() : string|null: Get primary condition for a sql clause.
getQillForField() : string: Get the qill value for the field.
getQillValue() : string: Get the qill (search description for field) for the specified field.
getQuery() : string: Wrapper for a simple search query.
getRelationshipActivePeriodClauses() : string: Get start & end active period criteria
getSearchSQL() : string: Create the sql query for an contact search.
getSearchSQLParts() : array<string|int, mixed>: Get the component parts of the search query as an array.
getSelect() : string: Get Select Clause.
getWhereClause() : string: Generate the where clause (used in match contacts and permissions)
getWhereValues() : mixed: Get where values from the parameters.
getWildCardedValue() : string: Alter value to reflect wildcard settings.
greetings() : mixed: Where/qill clause for greeting fields.
group() : mixed: Where / qill clause for groups.
handleWhereFromMetadata() : mixed: Where handling for any field with adequately defined metadata.
includeContactIDs() : mixed: Where / qill clause for including contact ids.
includeContactSubTypes() : mixed
includePseudoFieldsJoin() : array<string|int, mixed>|null: Include pseudo fields LEFT JOIN.
initialize() : mixed: Function which actually does all the work for the constructor.
isAlreadyProcessedForQueryFormat() : mixed: Has this field already been reformatting to Query object syntax.
isCustomDateField() : bool: Are we dealing with custom field of type date.
legacyConvertFormValues() : mixed: Function to support legacy format for groups and tags.
locationType() : string: Where / qill clause for location type.
modifiedDates() : mixed
nameNullOrEmptyOp() : bool
notes() : mixed: Where/qill clause for notes
numberRangeBuilder() : mixed
openedSearchPanes() : array<string|int, mixed>
optionValueQuery() : mixed: Builds the necessary structures for all fields that are similar to option value look-ups.
parseSearchBuilderString() : bool|array<string|int, mixed>: Check and explode a user defined numeric string into an array this was the protocol used by search builder in the old old days before we had super nice js widgets to do the hard work
phone_numeric() : mixed: Where / qill clause for phone number
phone_option_group() : mixed: Where / qill clause for phone type/location
postalCode() : mixed: Where / qill clause for postal code.
preferredCommunication() : mixed
privacy() : mixed
privacyOptions() : mixed
processSpecialFormValue() : mixed: Process special fields of Search Form in OK (Operator in Key) format
qill() : array<string|int, mixed>: Getter for the qill object.
query() : array<string|int, mixed>: Generate the query based on what type of query we need.
relationship() : mixed: Where / qill clause for relationship.
restWhere() : mixed: Generate where clause for any parameters not already handled.
searchQuery() : string|null|CRM_Core_DAO: Create and query the db for an contact search.
selectClause() : mixed: Given a list of conditions in params and a list of desired return Properties generate the required select and from clauses. Note that since the where clause introduces new tables, the initial attempt also retrieves all variables used in the params list
setOperator() : mixed
setQillAndWhere() : mixed: Set the qill and where properties for a field.
setSkipPermission() : mixed
sortByCharacter() : mixed: Where / qill clause for sorting by character.
sortName() : mixed: Where / qill clause for sort_name
stateProvince() : string: Where / qill clause for state/province AND country (if present).
store() : array<string|int, mixed>: Given a result dao, extract the values and return that array
street_address() : mixed: Where / qill clause for street_address.
street_number() : mixed: Where / qill clause for street_unit.
summaryContribution() : array<string|int, mixed>
tables() : array<string|int, mixed>: Getter for tables array.
tag() : mixed: Where / qill clause for tag.
tagSearch() : void: All tag search specific.
ufUser() : mixed: Where / qill clause for cms users
whereClause() : string: Given a list of conditions in params generate the required where clause.
whereClauseSingle() : mixed: Get the where clause for a single field.
whereTables() : array<string|int, mixed>: Sometimes used to create the from clause, but, not reliably, set this AND set tables.
addAddressTable() : array<string|int, mixed>: Add the address table into the query.
addBasicCancelStatsToSummary() : mixed: Add basic stats about cancelled contributions to the summary.
addBasicSoftCreditStatsToStats() : mixed: Add basic soft credit statistics to summary array.
addBasicStatsToSummary() : array<string|int, mixed>: Add basic statistics to the summary.
addPseudoconstantFieldToSelect() : mixed: If we have a field that is better rendered via the pseudoconstant handled them here.
buildRelativeDateQuery() : mixed
convertCustomRelativeFields() : mixed: Convert submitted values for relative custom fields to query object format.
email() : mixed: Where / qill clause for email
getEntitySpecificJoins() : string: Get join statements for the from clause depending on entity type
getGroupStatusClause() : string: Get the clause for group status.
getMetadataForField() : array<string|int, mixed>: Get the metadata for a given field.
getQillForRelativeDateRange() : string: Get the qill for the relative date range.
getSelectedGroupStatuses() : array<string|int, mixed>: Get an array of the statuses that have been selected.
isADateRangeField() : bool: Is the field a relative date field.
isARelativeDateField() : bool: Is the field a relative date field.
isPseudoFieldAnFK() : bool: Is this pseudofield a foreign key constraint.
prepareOrderBy() : string: Parse and assimilate the various sort options.
createSqlCase() : string: Construct a SQL CASE expression.
pseudoConstantNameIsInReturnProperties() : bool: Has the pseudoconstant of the field been requested.

MODE_ACTIVITY

The various search modes.


    public
        int
    MODE_ACTIVITY
    = 4096

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_ALL

The various search modes.


    public
        int
    MODE_ALL
    = 17407

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_CAMPAIGN

The various search modes.


    public
        int
    MODE_CAMPAIGN
    = 8192

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_CASE

The various search modes.


    public
        int
    MODE_CASE
    = 2048

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_CONTACTS

The various search modes.


    public
        int
    MODE_CONTACTS
    = 1

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_CONTACTSRELATED

The various search modes.


    public
        int
    MODE_CONTACTSRELATED
    = 32

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_CONTRIBUTE

The various search modes.


    public
        int
    MODE_CONTRIBUTE
    = 2

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_EVENT

The various search modes.


    public
        int
    MODE_EVENT
    = 16

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_GRANT

The various search modes.


    public
        int
    MODE_GRANT
    = 128

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_MAILING

The various search modes.


    public
        int
    MODE_MAILING
    = 16384

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_MEMBER

The various search modes.


    public
        int
    MODE_MEMBER
    = 8

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_PLEDGE

The various search modes.


    public
        int
    MODE_PLEDGE
    = 512

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

MODE_PLEDGEBANK

The various search modes.


    public
        int
    MODE_PLEDGEBANK
    = 256

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

NO_RETURN_PROPERTIES

The various search modes.


    public
        int
    NO_RETURN_PROPERTIES
    = 'CRM_Contact_BAO_Query::NO_RETURN_PROPERTIES'

As of February 2017, entries not present for 4, 32, 64, 1024.

MODE_ALL seems to be out of sync with the available constants; if this is intentionally excluding MODE_MAILING then that may bear documenting?

Likewise if there's reason for the missing modes (4, 32, 64 etc).

SEARCH_OPERATOR_AND

Constants for search operators


    public
        mixed
    SEARCH_OPERATOR_AND
    = 'AND'

SEARCH_OPERATOR_OR

Constants for search operators


    public
        mixed
    SEARCH_OPERATOR_OR
    = 'OR'

$_activityRole

The activity role


    public
    static    array<string|int, mixed>
    $_activityRole

$_cfIDs


    public
        mixed
    $_cfIDs

$_considerCompActivities

Consider the component activity type during activity search.


    public
    static    array<string|int, mixed>
    $_considerCompActivities

$_customQuery

Reference to the query object for custom values.


    public
        object
    $_customQuery

$_defaultHierReturnProperties

The default set of hier return properties.


    public
    static    array<string|int, mixed>
    $_defaultHierReturnProperties

$_defaultReturnProperties

The default set of return properties.


    public
    static    array<string|int, mixed>
    $_defaultReturnProperties

$_dependencies

The tables which have a dependency on location and/or address


    public
    static    array<string|int, mixed>
    $_dependencies
     = ['civicrm_state_province' => 1, 'civicrm_country' => 1, 'civicrm_county' => 1, 'civicrm_address' => 1, 'civicrm_location_type' => 1]

$_displayRelationshipType

Should we display contacts with a specific relationship type.


    public
        string
    $_displayRelationshipType

$_distinctComponentClause

Use distinct component clause for component searches


    public
        string
    $_distinctComponentClause

$_element

The name of the elements that are in the select clause used to extract the values.


    public
        array<string|int, mixed>
    $_element

$_fields

All the fields that could potentially be involved in this query


    public
        array<string|int, mixed>
    $_fields

$_fromClause

The from string


    public
        string
    $_fromClause

$_groupByComponentClause

Use groupBy component clause for component searches


    public
        string
    $_groupByComponentClause

$_groupKeys


    public
        mixed
    $_groupKeys
     = []

$_groupUniqueKey


    public
        mixed
    $_groupUniqueKey

$_having

The having values


    public
        array<string|int, mixed>
    $_having

$_includeContactIds

Are contact ids part of the query.


    public
        bool
    $_includeContactIds
     = \FALSE

$_locationSpecificCustomFields

For search builder - which custom fields are location-dependent


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

$_locationSpecificFields

List of location specific fields.


    public
    static    array<string|int, mixed>
    $_locationSpecificFields
     = ['street_address', 'street_number', 'street_name', 'street_unit', 'supplemental_address_1', 'supplemental_address_2', 'supplemental_address_3', 'city', 'postal_code', 'postal_code_suffix', 'geo_code_1', 'geo_code_2', 'state_province', 'country', 'county', 'phone', 'email', 'im', 'address_name', 'master_id', 'location_type']

$_mode


    public
        mixed
    $_mode
     = 1

$_onlyDeleted


    public
        int
    $_onlyDeleted
     = 0

Set to 1 if Search in Trash selected.

$_openedPanes

Track open panes, useful in advance search


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

$_operator

What operator to use to group the clauses.


    public
        string
    $_operator
     = 'AND'

$_paramLookup


    public
        mixed
    $_paramLookup

$_params

The set of input params.


    public
        array<string|int, mixed>
    $_params

$_permissionFromClause

Additional permission from clause


    public
        string
    $_permissionFromClause

$_permissionWhereClause

Additional WHERE clause for permissions.


    public
        string
    $_permissionWhereClause

$_primaryLocation

Should we only search on primary location.


    public
        bool
    $_primaryLocation
     = \TRUE

$_pseudoConstantsSelect


    public
        mixed
    $_pseudoConstantsSelect
     = []

$_qill

The english language version of the query


    public
        array<string|int, mixed>
    $_qill

$_relationshipTempTable

Set to the name of the temp table if one has been created.


    public
    static    string
    $_relationshipTempTable

$_relType

The relationship type direction


    public
    static    array<string|int, mixed>
    $_relType

$_returnProperties

The set of output params


    public
        array<string|int, mixed>
    $_returnProperties

$_rowCountClause


    public
        mixed
    $_rowCountClause

$_search

Are we in search mode.


    public
        bool
    $_search
     = \TRUE

$_select

The select clause


    public
        array<string|int, mixed>
    $_select

$_simpleFromClause

The from clause for the simple select and alphabetical select


    public
        string
    $_simpleFromClause

$_skipDeleteClause

Should we skip adding of delete clause.


    public
        bool
    $_skipDeleteClause
     = \FALSE

$_skipPermission

Should we skip permission checking.


    public
        bool
    $_skipPermission
     = \FALSE

$_smartGroupCache

Should we use the smart group cache.


    public
        bool
    $_smartGroupCache
     = \TRUE

$_sort


    public
        mixed
    $_sort

$_strict

Are we in strict mode (use equality over LIKE)


    public
        bool
    $_strict
     = \FALSE

$_tables

The tables involved in the query.


    public
        array<string|int, mixed>
    $_tables

$_useDistinct

Should we enable the distinct clause, used if we are including more than one group


    public
        bool
    $_useDistinct
     = \FALSE

$_useGroupBy

Should we just display one contact record


    public
        bool
    $_useGroupBy
     = \FALSE

$_where

Array of WHERE clause components.


    public
        array<string|int, mixed>
    $_where

$_whereClause

The WHERE clause as a string.


    public
        string
    $_whereClause

$_whereTables

The table involved in the where clause.


    public
        array<string|int, mixed>
    $_whereTables

$_withContactActivitiesOnly

Consider with contact activities only, during activity search.


    public
    static    array<string|int, mixed>
    $_withContactActivitiesOnly

$_rangeCache

Remember if we handle either end of a number or date range so we can skip the other


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

$_relationshipValuesAdded

Set to true when $this->relationship is run to avoid adding twice.


    protected
        bool
    $_relationshipValuesAdded
     = \FALSE

$legacyHackedFields

Fields hacked for legacy reasons.


    protected
        array<string|int, mixed>
    $legacyHackedFields
     = ['gender_id' => 'gender', 'prefix_id' => 'individual_prefix', 'suffix_id' => 'individual_suffix', 'communication_style_id' => 'communication_style']

Generally where a field has a option group defining it's options we add them to the fields array as pseudofields - eg for gender we would add the key 'gender' to fields using CRM_Core_DAO::appendPseudoConstantsToFields($fields);

The rendered results would hold an id in the gender_id field and the label in the pseudo 'Gender' field. The heading for the pseudofield would come form the the option group name & for the id field from the xml.

These fields are handled in a more legacy way - ie overwriting 'gender_id' with the label on output via the convertToPseudoNames function. Ideally we would convert them but they would then need to be fixed in some other places & there are also some issues around the name (ie. Gender currently has the label in the schema 'Gender' so adding a second 'Gender' field to search builder & export would be confusing and the standard is not fully agreed here.

__construct()

Class constructor which also does all the work.


    public
                    __construct([array<string|int, mixed> $params = NULL ][, array<string|int, mixed> $returnProperties = NULL ][, array<string|int, mixed> $fields = NULL ][, bool $includeContactIds = FALSE ][, bool $strict = FALSE ][, bool|int $mode = 1 ][, bool $skipPermission = FALSE ][, bool $searchDescendentGroups = TRUE ][, bool $smartGroupCache = TRUE ][, null $displayRelationshipType = NULL ][, string $operator = 'AND' ][, string $apiEntity = NULL ][, bool|null $primaryLocationOnly = NULL ]) : mixed

Parameters

$params : array<string|int, mixed> = NULL

$returnProperties : array<string|int, mixed> = NULL

$fields : array<string|int, mixed> = NULL

$includeContactIds : bool = FALSE

$strict : bool = FALSE

$mode : bool|int = 1

mode the search is operating on

$skipPermission : bool = FALSE

$searchDescendentGroups : bool = TRUE

$smartGroupCache : bool = TRUE

$displayRelationshipType : null = NULL

$operator : string = 'AND'

$apiEntity : string = NULL

$primaryLocationOnly : bool|null = NULL

addGroupContactCache()

Prime smart group cache for smart groups in the search, and join civicrm_group_contact_cache table into the query.


    public
                    addGroupContactCache(array<string|int, mixed> $groups, string $tableAlias, string $joinTable, string $op[, string $joinColumn = 'id' ]) : string

Parameters

$groups : array<string|int, mixed>: IDs of groups specified in search criteria.
$tableAlias : string: Alias to use for civicrm_group_contact_cache table.
$joinTable : string: Table on which to join civicrm_group_contact_cache
$op : string: SQL comparison operator (NULL, IN, !=, IS NULL, etc.)
$joinColumn : string = 'id': Column in $joinTable on which to join civicrm_group_contact_cache.contact_id

Return values

string —

WHERE clause component for smart group criteria.

addHierarchicalElements()

If the return Properties are set in a hierarchy, traverse the hierarchy to get the return values.


    public
                    addHierarchicalElements() : mixed

addMultipleElements()

If the return Properties are set in a hierarchy, traverse the hierarchy to get the return values.


    public
                    addMultipleElements() : mixed

addRelationshipActivePeriodClauses()

Add start & end active period criteria in


    public
                    addRelationshipActivePeriodClauses(string $grouping, array<string|int, mixed> &$where) : mixed

Parameters

$grouping : string
$where : array<string|int, mixed>: = array to add where clauses to, in case you are generating a temp table. not the main query.

addRelationshipDateClauses()

Add start & end date criteria in


    public
                    addRelationshipDateClauses(string $grouping, array<string|int, mixed> &$where) : mixed

Parameters

$grouping : string
$where : array<string|int, mixed>: = array to add where clauses to, in case you are generating a temp table. not the main query.

addRelationshipPermissionClauses()

Add relationship permission criteria to where clause.


    public
                    addRelationshipPermissionClauses(string $grouping, array<string|int, mixed> &$where) : mixed

Parameters

$grouping : string
$where : array<string|int, mixed>: Array to add "where" criteria to, in case you are generating a temp table. Not the main query.

addSpecialFields()

Some composite fields do not appear in the fields array hack to make them part of the query.


    public
                    addSpecialFields(mixed $apiEntity) : mixed

Parameters

$apiEntity : mixed: The api entity being called. This sort-of duplicates $mode in a confusing way. Probably not by design.

ageRangeQueryBuilder()


    public
                    ageRangeQueryBuilder(mixed &$values, string $tableName, string $fieldName, string $dbFieldName, mixed $fieldTitle[, null $options = NULL ]) : mixed

Parameters

$values : mixed
$tableName : string
$fieldName : string
$dbFieldName : string
$fieldTitle : mixed
$options : null = NULL

alphabetQuery()

Create and query the db for the list of all first letters used by contacts


    public
                    alphabetQuery() : CRM_Core_DAO

Return values

CRM_Core_DAO

apiQuery()

These are stub comments as this function needs more explanation - particularly in terms of how it relates to $this->searchQuery and why it replicates rather than calles $this->searchQuery.


    public
            static        apiQuery([array<string|int, mixed> $params = NULL ][, array<string|int, mixed> $returnProperties = NULL ][, null $fields = NULL ][, string $sort = NULL ][, int $offset = 0 ][, int $row_count = 25 ][, bool $smartGroupCache = TRUE ][, bool $count = FALSE ][, bool $skipPermissions = TRUE ][, int $mode = CRM_Contact_BAO_Query::MODE_CONTACTS ][, string $apiEntity = NULL ][, bool|null $primaryLocationOnly = NULL ]) : array<string|int, mixed>

since 5.71 - will be removed after all core usages are fully removed.

This function was originally written as a wrapper for the api query but is called from multiple places in the core code directly so the name is misleading. This function does not use the searchQuery function but it is unclear as to whehter that is historical or there is a reason CRM-11290 led to the permissioning action being extracted from searchQuery & shared with this function

Parameters

$params : array<string|int, mixed> = NULL
$returnProperties : array<string|int, mixed> = NULL
$fields : null = NULL
$sort : string = NULL
$offset : int = 0
$row_count : int = 25
$smartGroupCache : bool = TRUE: ?? update smart group cache?.
$count : bool = FALSE: Return count obnly.
$skipPermissions : bool = TRUE: Should permissions be ignored or should the logged in user's permissions be applied.
$mode : int = CRM_Contact_BAO_Query::MODE_CONTACTS: This basically correlates to the component.
$apiEntity : string = NULL: The api entity being called. This sort-of duplicates $mode in a confusing way. Probably not by design.
$primaryLocationOnly : bool|null = NULL

Return values

array<string|int, mixed>

appendAnyValueToSelect()

For some special cases, grouping by subset of select fields becomes mandatory.


    public
            static        appendAnyValueToSelect(array<string|int, mixed> $selectClauses, array<string|int, mixed> $groupBy[, string $aggregateFunction = 'ANY_VALUE' ]) : string

Hence, full_group_by mode is handled by appending any_value keyword to select fields not present in groupBy

Parameters

$selectClauses : array<string|int, mixed>

$groupBy : array<string|int, mixed>

Columns already included in GROUP By clause.

$aggregateFunction : string = 'ANY_VALUE'

Return values

string

buildClause()

Given the field name, operator, value & its data type builds the where Clause for the query used for handling 'IS NULL'/'IS NOT NULL' operators


    public
            static        buildClause(string $field, string $op[, string $value = NULL ][, string $dataType = 'String' ][, bool $isAlreadyEscaped = FALSE ]) : string

Parameters

$field : string: Fieldname.
$op : string: Operator.
$value : string = NULL: Value.
$dataType : string = 'String': Data type of the field.
$isAlreadyEscaped : bool = FALSE: Ideally we would be consistent about whether we escape before calling this or after, but the code is a fearsome beast and poking the sleeping dragon could throw a cat among the can of worms. Hence we just schmooze this parameter in to prevent double escaping where it is known to occur.

Return values

string —

Where clause for the query.

buildDateRangeQuery()

Build the query for a date field if it is a _high or _low field.


    public
                    buildDateRangeQuery(mixed $values) : bool

Parameters

$values : mixed

Return values

bool

buildParamsLookup()

Function for same purpose as convertFormValues.


    public
                    buildParamsLookup() : mixed

Like convert form values this function exists to pre-Process parameters from the form.

It is unclear why they are different functions & likely relates to advances search versus search builder.

The direction we are going is having the form convert values to a standardised format & moving away from weird & wonderful where clause switches.

Fix and handle contact deletion nicely.

this code is primarily for search builder use case where different clauses can specify if they want deleted.

buildQillForFieldValue()

Build qill for field.


    public
            static        buildQillForFieldValue(string $daoName, string $fieldName, mixed $fieldValue, string $op[, array<string|int, mixed> $pseudoExtraParam = [] ][, int $type = CRM_Utils_Type::T_STRING ]) : array<string|int, mixed>

Qill refers to the query detail visible on the UI.

Parameters

$daoName : string
$fieldName : string
$fieldValue : mixed
$op : string
$pseudoExtraParam : array<string|int, mixed> = []
$type : int = CRM_Utils_Type::T_STRING: Type of the field per CRM_Utils_Type

Return values

array<string|int, mixed>

buildWhereForDate()


    public
                    buildWhereForDate() : mixed

calcDateFromAge()

Calculate date from age.


    public
            static        calcDateFromAge(string $asofDate, int $age, string $type) : string

Parameters

$asofDate : string
$age : int
$type : string

Return values

string

caseImportant()

See CRM-19811 for why this is database hurty without apparent benefit.


    public
            static        caseImportant(mixed $op) : bool

Parameters

$op : mixed

Return values

bool

changeLog()

Where / qill clause for change log.


    public
                    changeLog(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

componentPresent()


    public
            static        componentPresent(mixed &$returnProperties, mixed $prefix) : bool

Parameters

$returnProperties : mixed
$prefix : mixed

Return values

bool

contactSubType()

Where / qill clause for contact_sub_type.


    public
                    contactSubType(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

contactType()

Where / qill clause for contact_type


    public
                    contactType(mixed &$values) : mixed

Parameters

$values : mixed

convertFormValues()

Convert values from form-appropriate to query-object appropriate.


    public
            static        convertFormValues(array<string|int, mixed> &$formValues[, int $wildcard = 0 ][, bool $useEquals = FALSE ][, string $apiEntity = NULL ][, array<string|int, mixed> $entityReferenceFields = [] ]) : array<string|int, mixed>

The query object is increasingly supporting the sql-filter syntax which is the most flexible syntax. So, ideally we would convert all fields to look like array( 0 => $fieldName // Set the operator for legacy reasons, but it is ignored 1 => '=' // array in sql filter syntax 2 => array('BETWEEN' => array(1,60), 3 => null 4 => null );

More notes at CRM_Core_DAO::createSQLFilter and a list of supported operators in CRM_Core_DAO

Parameters

$formValues : array<string|int, mixed>
$wildcard : int = 0
$useEquals : bool = FALSE
$apiEntity : string = NULL
$entityReferenceFields : array<string|int, mixed> = []: Field names of any entity reference fields (which will need reformatting to IN syntax).

Return values

array<string|int, mixed>

convertGroupIDStringToLabelString()

Convert a string of group IDs to a string of group labels.


    public
                    convertGroupIDStringToLabelString(CRM_Core_DAO &$dao, string $val) : string

The original string may include duplicates and groups the user does not have permission to see.

Parameters

$dao : CRM_Core_DAO
$val : string

Return values

string

convertToPseudoNames()

Convert the pseudo constants id's to their names


    public
                    convertToPseudoNames(CRM_Core_DAO &$dao[, bool $return = FALSE ][, bool $usedForAPI = FALSE ]) : array<string|int, mixed>|null

Parameters

$dao : CRM_Core_DAO
$return : bool = FALSE
$usedForAPI : bool = FALSE

Return values

array<string|int, mixed>|null

country()


    public
                    country(mixed &$values[, bool $fromStateProvince = TRUE ]) : array<string|int, mixed>|null

Parameters

$values : mixed
$fromStateProvince : bool = TRUE

Return values

array<string|int, mixed>|null

county()

Where / qill clause for county (if present).


    public
                    county(array<string|int, mixed> &$values[, null $status = NULL ]) : string

Parameters

$values : array<string|int, mixed>
$status : null = NULL

Return values

string

dateQueryBuilder()

Build query for a date field.


    public
                    dateQueryBuilder(array<string|int, mixed> $values, string $tableName, string $fieldName, string $dbFieldName, string $fieldTitle[, bool $appendTimeStamp = TRUE ][, string $dateFormat = 'YmdHis' ][, string|null $highDBFieldName = NULL ]) : mixed

Parameters

$values : array<string|int, mixed>
$tableName : string
$fieldName : string
$dbFieldName : string
$fieldTitle : string
$appendTimeStamp : bool = TRUE
$dateFormat : string = 'YmdHis'
$highDBFieldName : string|null = NULL: Optional field name for when the 'high' part of the calculation uses a different field than the 'low' part. This is an obscure situation & one we don't want to do more of but supporting them here is the only way for now. Examples are event date & relationship active date -in both cases we are looking for things greater than the start date & less than the end date.

defaultHierReturnProperties()

Default set of return default hier return properties.


    public
            static    &    defaultHierReturnProperties() : array<string|int, mixed>

Return values

array<string|int, mixed>

defaultReturnProperties()

Default set of return properties.


    public
            static    &    defaultReturnProperties([int $mode = 1 ]) : array<string|int, mixed>

Parameters

$mode : int = 1

Return values

array<string|int, mixed> —

derault return properties

deletedContacts()

WHERE / QILL clause for deleted_contacts


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

Parameters

$values : array<string|int, mixed>

demographics()


    public
                    demographics(mixed &$values) : mixed

Parameters

$values : mixed

filterCountryFromValuesIfStateExists()

If the state and country are passed remove state.


    public
            static        filterCountryFromValuesIfStateExists(array<string|int, mixed> &$formValues) : mixed

Country is implicit from the state, but including both results in a poor query as there is no combined index on state AND country.

Parameters

$formValues : array<string|int, mixed>

filterRelatedContacts()


    public
                    filterRelatedContacts(mixed &$from, mixed &$where, mixed &$having) : mixed

Parameters

$from : mixed
$where : mixed
$having : mixed

fixDateValues()

Fix date values.


    public
            static        fixDateValues(bool $relative, string &$from, string &$to) : mixed

Parameters

$relative : bool
$from : string
$to : string

fixWhereValues()

Fix values from query from/to something no-one cared enough to document.


    public
            static        fixWhereValues(int $id, array<string|int, mixed> &$values[, int $wildcard = 0 ][, bool $useEquals = FALSE ][, string $apiEntity = NULL ]) : array<string|int, mixed>|null

Parameters

$id : int
$values : array<string|int, mixed>
$wildcard : int = 0
$useEquals : bool = FALSE
$apiEntity : string = NULL

Return values

array<string|int, mixed>|null

fromClause()

Create the from clause.


    public
            static        fromClause(array<string|int, mixed> &$tables[, array<string|int, mixed> $inner = NULL ][, array<string|int, mixed> $right = NULL ][, bool $primaryLocation = TRUE ][, int $mode = 1 ][, string|null $apiEntity = NULL ][, int $onlyDeleted = 0 ]) : string

Parameters

$tables : array<string|int, mixed>: Tables that need to be included in this from clause. If null, return mimimal from clause (i.e. civicrm_contact).
$inner : array<string|int, mixed> = NULL: Tables that should be inner-joined.
$right : array<string|int, mixed> = NULL: Tables that should be right-joined.
$primaryLocation : bool = TRUE: Search on primary location. See note below.
$mode : int = 1: Determines search mode based on bitwise MODE_* constants.
$apiEntity : string|null = NULL: Determines search mode based on entity by string.
$onlyDeleted : int = 0: Determines if we are only looking for deleted contacts

The $primaryLocation flag only seems to be used when locationType() has been called. This may be a search option exposed, or perhaps it's a "search all details" approach which predates decoupling of location types and primary fields?

Return values

string —

the from clause

generatePermissionClause()

Populate $this->_permissionWhereClause with permission related clause and update other query related properties.


    public
                    generatePermissionClause([bool $onlyDeleted = FALSE ][, bool $count = FALSE ]) : mixed

Function calls ACL permission class and hooks to filter the query appropriately

Note that these 2 params were in the code when extracted from another function and a second round extraction would be to make them properties of the class

Parameters

$onlyDeleted : bool = FALSE: Only get deleted contacts.
$count : bool = FALSE: Return Count only.

getCachedContacts()

Fetch a list of contacts for displaying a search results page


    public
                    getCachedContacts(array<string|int, mixed> $cids, bool $includeContactIds) : CRM_Core_DAO

Parameters

$cids : array<string|int, mixed>: List of contact IDs
$includeContactIds : bool

Return values

CRM_Core_DAO

getCustomFieldName()

Get the actual custom field name by stripping off the appended string.


    public
            static        getCustomFieldName(string $parameterName) : string

The string could be _relative, _from, or _to

Parameters

$parameterName : string: The name of the parameter submitted to the form. e.g custom_3_relative custom_3_from

Return values

string

getDataTypeForRealField()

Get the field datatype, using the type in the database rather than the pseudofield, if a pseudofield.


    public
                    getDataTypeForRealField(string $fieldName) : string

Parameters

$fieldName : string

Return values

string

getFieldSpec()

Get the specifications for the field, if available.


    public
                    getFieldSpec(string $fieldName) : array<string|int, mixed>

Parameters

$fieldName : string: Fieldname as displayed on the form.

Return values

array<string|int, mixed>

getGroupByFromOrderBy()

For some special cases, where if non-aggregate ORDER BY columns are not present in GROUP BY on full_group_by mode, then append the those missing columns to GROUP BY clause keyword to select fields not present in groupBy


    public
            static        getGroupByFromOrderBy(string &$groupBy, array<string|int, mixed> $orderBys) : mixed

Parameters

$groupBy : string

GROUP BY clause where missing ORDER BY columns will be appended if not present

$orderBys : array<string|int, mixed>

ORDER BY sub-clauses

getGroupByFromSelectColumns()

Include select columns in groupBy clause.


    public
            static        getGroupByFromSelectColumns(array<string|int, mixed> $selectClauses[, array<string|int, mixed>|string|null $groupBy = NULL ]) : string

Parameters

$selectClauses : array<string|int, mixed>

$groupBy : array<string|int, mixed>|string|null = NULL

Columns already included in GROUP By clause.

Return values

string

getGroupCacheTableKeys()


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

Return values

array<string|int, mixed>

getGroupsFromTypeCriteria()

Function translates selection of group type into a list of groups.


    public
                    getGroupsFromTypeCriteria(mixed $value) : array<string|int, mixed>

Parameters

$value : mixed

Return values

array<string|int, mixed>

getLocationTableName()


    public
            static        getLocationTableName(mixed &$where, mixed &$locType) : array<string|int, mixed>

Parameters

$where : mixed
$locType : mixed

Return values

array<string|int, mixed>

getMetadataForRealField()

Get the metadata for a given field, returning the 'real field' if it is a pseudofield.


    public
                    getMetadataForRealField(string $fieldName) : array<string|int, mixed>

Parameters

$fieldName : string

Return values

array<string|int, mixed>

getOperator()


    public
                    getOperator() : string

Return values

string

getPrimaryCondition()

Get primary condition for a sql clause.


    public
            static        getPrimaryCondition(int $value) : string|null

Parameters

$value : int

Return values

string|null

getQillForField()

Get the qill value for the field.


    public
                    getQillForField(string $name, array<string|int, mixed>|int|string $value, string $op[, array<string|int, mixed> $fieldSpec = [] ][, string $labelOverride = NULL ]) : string

Parameters

$name : string
$value : array<string|int, mixed>|int|string
$op : string
$fieldSpec : array<string|int, mixed> = []
$labelOverride : string = NULL: Label override, if required.

Return values

string

getQillValue()

Get the qill (search description for field) for the specified field.


    public
            static        getQillValue(string $daoName, string $name, string $value, string|array<string|int, mixed> $op, string $label) : string

Parameters

$daoName : string
$name : string
$value : string
$op : string|array<string|int, mixed>
$label : string

Return values

string

getQuery()

Wrapper for a simple search query.


    public
            static        getQuery([array<string|int, mixed> $params = NULL ][, array<string|int, mixed> $returnProperties = NULL ][, bool $count = FALSE ]) : string

Parameters

$params : array<string|int, mixed> = NULL
$returnProperties : array<string|int, mixed> = NULL
$count : bool = FALSE

Return values

string

getRelationshipActivePeriodClauses()

Get start & end active period criteria


    public
            static        getRelationshipActivePeriodClauses(mixed $from, mixed $to, mixed $forceTableName) : string

Parameters

$from : mixed
$to : mixed
$forceTableName : mixed

Return values

string

getSearchSQL()

Create the sql query for an contact search.


    public
                    getSearchSQL([int $offset = 0 ][, int $rowCount = 0 ][, string|CRM_Utils_Sort $sort = NULL ][, bool $count = FALSE ][, bool $includeContactIds = FALSE ][, bool $sortByChar = FALSE ][, bool $groupContacts = FALSE ][, string $additionalWhereClause = NULL ][, null $sortOrder = NULL ][, string $additionalFromClause = NULL ]) : string

Parameters

$offset : int = 0: The offset for the query.
$rowCount : int = 0: The number of rows to return.
$sort : string|CRM_Utils_Sort = NULL: The order by string.
$count : bool = FALSE: Is this a count only query ?.
$includeContactIds : bool = FALSE: Should we include contact ids?.
$sortByChar : bool = FALSE: If true returns the distinct array of first characters for search results.
$groupContacts : bool = FALSE: If true, return only the contact ids.
$additionalWhereClause : string = NULL: If the caller wants to further restrict the search (used for components).
$sortOrder : null = NULL
$additionalFromClause : string = NULL: Should be clause with proper joins, effective to reduce where clause load.

Return values

string

getSearchSQLParts()

Get the component parts of the search query as an array.


    public
                    getSearchSQLParts([int $offset = 0 ][, int $rowCount = 0 ][, string|CRM_Utils_Sort $sort = NULL ][, bool $count = FALSE ][, bool $includeContactIds = FALSE ][, bool $sortByChar = FALSE ][, bool $groupContacts = FALSE ][, string $additionalWhereClause = NULL ][, null $sortOrder = NULL ][, string $additionalFromClause = NULL ]) : array<string|int, mixed>

Parameters

$offset : int = 0: The offset for the query.
$rowCount : int = 0: The number of rows to return.
$sort : string|CRM_Utils_Sort = NULL: The order by string.
$count : bool = FALSE: Is this a count only query ?.
$includeContactIds : bool = FALSE: Should we include contact ids?.
$sortByChar : bool = FALSE: If true returns the distinct array of first characters for search results.
$groupContacts : bool = FALSE: If true, return only the contact ids.
$additionalWhereClause : string = NULL: If the caller wants to further restrict the search (used for components).
$sortOrder : null = NULL
$additionalFromClause : string = NULL: Should be clause with proper joins, effective to reduce where clause load.

Return values

array<string|int, mixed>

getSelect()

Get Select Clause.


    public
                    getSelect() : string

Return values

string

getWhereClause()

Generate the where clause (used in match contacts and permissions)


    public
            static        getWhereClause(array<string|int, mixed> $params, array<string|int, mixed> $fields, array<string|int, mixed> &$tables, mixed &$whereTables[, bool $strict = FALSE ]) : string

Parameters

$params : array<string|int, mixed>
$fields : array<string|int, mixed>
$tables : array<string|int, mixed>
$whereTables : mixed
$strict : bool = FALSE

Return values

string

getWhereValues()

Get where values from the parameters.


    public
                    getWhereValues(string $name, mixed $grouping) : mixed

Parameters

$name : string
$grouping : mixed

getWildCardedValue()

Alter value to reflect wildcard settings.


    public
            static        getWildCardedValue(bool $wildcard, string $op, string $value) : string

The form will have tried to guess whether this is a good field to wildcard but there is also a site-wide setting that specifies whether it is OK to append the wild card to the beginning or only the end of the string

Parameters

$wildcard : bool: This is a bool made on an assessment 'elsewhere' on whether this is a good field to wildcard.
$op : string: Generally '=' or 'LIKE'.
$value : string: The search string.

Return values

string

greetings()

Where/qill clause for greeting fields.


    public
                    greetings(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

group()

Where / qill clause for groups.


    public
                    group(mixed $values) : mixed

Parameters

$values : mixed

handleWhereFromMetadata()

Where handling for any field with adequately defined metadata.


    public
                    handleWhereFromMetadata(array<string|int, mixed> $fieldSpec, string $name, string|array<string|int, mixed>|int $value, string $op[, string|int $grouping = 0 ]) : mixed

Parameters

$fieldSpec : array<string|int, mixed>
$name : string
$value : string|array<string|int, mixed>|int
$op : string
$grouping : string|int = 0

includeContactIDs()

Where / qill clause for including contact ids.


    public
                    includeContactIDs() : mixed

includeContactSubTypes()


    public
                    includeContactSubTypes(mixed $value, mixed $grouping[, string $op = 'LIKE' ]) : mixed

Parameters

$value : mixed
$grouping : mixed
$op : string = 'LIKE'

includePseudoFieldsJoin()

Include pseudo fields LEFT JOIN.


    public
                    includePseudoFieldsJoin(string|array<string|int, mixed> $sort) : array<string|int, mixed>|null

Parameters

$sort : string|array<string|int, mixed>: can be a object or string

Return values

array<string|int, mixed>|null

initialize()

Function which actually does all the work for the constructor.


    public
                    initialize([string $apiEntity = NULL ]) : mixed

Parameters

$apiEntity : string = NULL: The api entity being called. This sort-of duplicates $mode in a confusing way. Probably not by design.

isAlreadyProcessedForQueryFormat()

Has this field already been reformatting to Query object syntax.


    public
            static        isAlreadyProcessedForQueryFormat(mixed $values) : mixed

The form layer passed formValues to this function in preProcess & postProcess. Reason unknown. This seems to come with associated double queries & is possibly damaging performance.

However, here we add a tested function to ensure convertFormValues identifies pre-processed fields & returns them as they are.

Parameters

$values : mixed: Value in formValues for the field.

isCustomDateField()

Are we dealing with custom field of type date.


    public
            static        isCustomDateField(mixed $fieldName) : bool

Parameters

$fieldName : mixed

Return values

bool

legacyConvertFormValues()

Function to support legacy format for groups and tags.


    public
            static        legacyConvertFormValues(string $id, array<string|int, mixed>|int &$values) : mixed

Parameters

$id : string
$values : array<string|int, mixed>|int

locationType()

Where / qill clause for location type.


    public
                    locationType(array<string|int, mixed> &$values[, null $status = NULL ]) : string

Parameters

$values : array<string|int, mixed>
$status : null = NULL

Return values

string

modifiedDates()


    public
                    modifiedDates(mixed $values) : mixed

Parameters

$values : mixed

nameNullOrEmptyOp()


    public
                    nameNullOrEmptyOp(string $name, mixed $op, mixed $grouping) : bool

Parameters

$name : string
$op : mixed
$grouping : mixed

Return values

bool

notes()

Where/qill clause for notes


    public
                    notes(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

numberRangeBuilder()


    public
                    numberRangeBuilder(mixed &$values, string $tableName, string $fieldName, string $dbFieldName, mixed $fieldTitle[, null $options = NULL ]) : mixed

Parameters

$values : mixed
$tableName : string
$fieldName : string
$dbFieldName : string
$fieldTitle : mixed
$options : null = NULL

openedSearchPanes()


    public
                    openedSearchPanes([bool $reset = FALSE ]) : array<string|int, mixed>

Parameters

$reset : bool = FALSE

Return values

array<string|int, mixed>

optionValueQuery()

Builds the necessary structures for all fields that are similar to option value look-ups.


    public
                    optionValueQuery(string $name, string $op, string $value, int $grouping, string $daoName, array<string|int, mixed> $field, string $label[, string $dataType = 'String' ]) : mixed

Parameters

$name : string: the name of the field.
$op : string: the sql operator, this function should handle ALL SQL operators.
$value : string: depends on the operator and who's calling the query builder.
$grouping : int: the index where to place the where clause.
$daoName : string: DAO Name.
$field : array<string|int, mixed>: an array that contains various properties of the field identified by $name.
$label : string: The label for this field element.
$dataType : string = 'String'

parseSearchBuilderString()

Check and explode a user defined numeric string into an array this was the protocol used by search builder in the old old days before we had super nice js widgets to do the hard work


    public
            static        parseSearchBuilderString(string $string[, string $dataType = 'Integer' ]) : bool|array<string|int, mixed>

Parameters

$string : string
$dataType : string = 'Integer': The dataType we should check for the values, default integer.

Return values

bool|array<string|int, mixed> —

false if string does not match the pattern array of numeric values if string does match the pattern

phone_numeric()

Where / qill clause for phone number


    public
                    phone_numeric(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

phone_option_group()

Where / qill clause for phone type/location


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

Parameters

$values : array<string|int, mixed>

postalCode()

Where / qill clause for postal code.


    public
                    postalCode(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

preferredCommunication()


    public
                    preferredCommunication(mixed &$values) : mixed

Parameters

$values : mixed

privacy()


    public
                    privacy(mixed &$values) : mixed

Parameters

$values : mixed

privacyOptions()


    public
                    privacyOptions(mixed $values) : mixed

Parameters

$values : mixed

processSpecialFormValue()

Process special fields of Search Form in OK (Operator in Key) format


    public
            static        processSpecialFormValue(array<string|int, mixed> &$formValues, array<string|int, mixed> $specialFields[, array<string|int, mixed> $changeNames = [] ]) : mixed

Parameters

$formValues : array<string|int, mixed>
$specialFields : array<string|int, mixed>: Special params to be processed
$changeNames : array<string|int, mixed> = []: Array of fields whose name should be changed

qill()

Getter for the qill object.


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

Return values

array<string|int, mixed>

query()

Generate the query based on what type of query we need.


    public
                    query([bool $count = FALSE ][, bool $sortByChar = FALSE ][, bool $groupContacts = FALSE ][, int $onlyDeleted = 0 ]) : array<string|int, mixed>

Parameters

$count : bool = FALSE
$sortByChar : bool = FALSE
$groupContacts : bool = FALSE
$onlyDeleted : int = 0

Return values

array<string|int, mixed> —

sql query parts as an array

relationship()

Where / qill clause for relationship.


    public
                    relationship(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

restWhere()

Generate where clause for any parameters not already handled.


    public
                    restWhere(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

searchQuery()

Create and query the db for an contact search.


    public
                    searchQuery([int $offset = 0 ][, int $rowCount = 0 ][, string|CRM_Utils_Sort $sort = NULL ][, bool $count = FALSE ][, bool $includeContactIds = FALSE ][, bool $sortByChar = FALSE ][, bool $groupContacts = FALSE ][, bool $returnQuery = FALSE ][, string $additionalWhereClause = NULL ][, null $sortOrder = NULL ][, string $additionalFromClause = NULL ][, bool $skipOrderAndLimit = FALSE ]) : string|null|CRM_Core_DAO

Parameters

$offset : int = 0: The offset for the query.
$rowCount : int = 0: The number of rows to return.
$sort : string|CRM_Utils_Sort = NULL: The order by string.
$count : bool = FALSE: Is this a count only query ?.
$includeContactIds : bool = FALSE: Should we include contact ids?.
$sortByChar : bool = FALSE: If true returns the distinct array of first characters for search results.
$groupContacts : bool = FALSE: If true, return only the contact ids.
$returnQuery : bool = FALSE: Should we return the query as a string.
$additionalWhereClause : string = NULL: If the caller wants to further restrict the search (used for components).
$sortOrder : null = NULL
$additionalFromClause : string = NULL: Should be clause with proper joins, effective to reduce where clause load.
$skipOrderAndLimit : bool = FALSE

Return values

string|null|CRM_Core_DAO

selectClause()

Given a list of conditions in params and a list of desired return Properties generate the required select and from clauses. Note that since the where clause introduces new tables, the initial attempt also retrieves all variables used in the params list


    public
                    selectClause([string $apiEntity = NULL ]) : mixed

Parameters

$apiEntity : string = NULL: The api entity being called. This sort-of duplicates $mode in a confusing way. Probably not by design.

setOperator()


    public
                    setOperator(mixed $operator) : mixed

Parameters

$operator : mixed

setQillAndWhere()

Set the qill and where properties for a field.


    public
                    setQillAndWhere(string $name, string $op, string|array<string|int, mixed> $value, string $grouping, array<string|int, mixed> $field) : mixed

This function is intended as a short-term function to encourage refactoring & re-use - but really we should just have less special-casing.

Parameters

$name : string
$op : string
$value : string|array<string|int, mixed>
$grouping : string
$field : array<string|int, mixed>

setSkipPermission()


    public
                    setSkipPermission(mixed $val) : mixed

Parameters

$val : mixed

sortByCharacter()

Where / qill clause for sorting by character.


    public
                    sortByCharacter(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

sortName()

Where / qill clause for sort_name


    public
                    sortName(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

stateProvince()

Where / qill clause for state/province AND country (if present).


    public
                    stateProvince(array<string|int, mixed> &$values[, null $status = NULL ]) : string

Parameters

$values : array<string|int, mixed>
$status : null = NULL

Return values

string

store()

Given a result dao, extract the values and return that array


    public
                    store(CRM_Core_DAO $dao) : array<string|int, mixed>

Parameters

$dao : CRM_Core_DAO

Return values

array<string|int, mixed> —

values for this query

street_address()

Where / qill clause for street_address.


    public
                    street_address(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

street_number()

Where / qill clause for street_unit.


    public
                    street_number(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

summaryContribution()


    public
                    summaryContribution([string|null $context = NULL ]) : array<string|int, mixed>

Parameters

$context : string|null = NULL

Return values

array<string|int, mixed>

tables()

Getter for tables array.


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

Return values

array<string|int, mixed>

tag()

Where / qill clause for tag.


    public
                    tag(array<string|int, mixed> &$values) : mixed

Parameters

$values : array<string|int, mixed>

tagSearch()

All tag search specific.


    public
                    tagSearch(array<string|int, mixed> $values) : void

Parameters

$values : array<string|int, mixed>

ufUser()

Where / qill clause for cms users


    public
                    ufUser(mixed &$values) : mixed

Parameters

$values : mixed

whereClause()

Given a list of conditions in params generate the required where clause.


    public
                    whereClause([bool $isForcePrimaryEmailOnly = NULL ]) : string

Parameters

$isForcePrimaryEmailOnly : bool = NULL

Return values

string

whereClauseSingle()

Get the where clause for a single field.


    public
                    whereClauseSingle(array<string|int, mixed> &$values[, bool $isForcePrimaryOnly = FALSE ]) : mixed

Parameters

$values : array<string|int, mixed>
$isForcePrimaryOnly : bool = FALSE

whereTables()

Sometimes used to create the from clause, but, not reliably, set this AND set tables.


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

It's unclear the intent - there is a 'simpleFrom' clause which takes whereTables into account & a fromClause which doesn't.

logic may have eroded?

Return values

array<string|int, mixed>

addAddressTable()

Add the address table into the query.


    protected
                    addAddressTable(string $tableKey, string $joinCondition) : array<string|int, mixed>

Parameters

$tableKey : string
$joinCondition : string

Return values

array<string|int, mixed> —

alias name
address join.

addBasicCancelStatsToSummary()

Add basic stats about cancelled contributions to the summary.


    protected
                    addBasicCancelStatsToSummary(array<string|int, mixed> &$summary, string $where, string $from) : mixed

Parameters

$summary : array<string|int, mixed>
$where : string
$from : string

addBasicSoftCreditStatsToStats()

Add basic soft credit statistics to summary array.


    protected
                    addBasicSoftCreditStatsToStats(array<string|int, mixed> &$summary, string $where, string $from) : mixed

Parameters

$summary : array<string|int, mixed>
$where : string
$from : string

addBasicStatsToSummary()

Add basic statistics to the summary.


    protected
                    addBasicStatsToSummary(array<string|int, mixed> &$summary, string $where, string $from) : array<string|int, mixed>

Parameters

$summary : array<string|int, mixed>
$where : string
$from : string

Return values

array<string|int, mixed>

addPseudoconstantFieldToSelect()

If we have a field that is better rendered via the pseudoconstant handled them here.


    protected
                    addPseudoconstantFieldToSelect(string $name) : mixed

Rather than joining in the additional table we render the option value on output.

Parameters

$name : string

buildRelativeDateQuery()


    protected
                    buildRelativeDateQuery(mixed &$values) : mixed

Parameters

$values : mixed

convertCustomRelativeFields()

Convert submitted values for relative custom fields to query object format.


    protected
            static        convertCustomRelativeFields(array<string|int, mixed> &$formValues, array<string|int, mixed> &$params, string $values, string $fieldName) : mixed

The query will support the sqlOperator format so convert to that format.

Parameters

$formValues : array<string|int, mixed>: Submitted values.
$params : array<string|int, mixed>: Converted parameters for the query object.
$values : string: Submitted value.
$fieldName : string: Submitted field name. (Matches form field not DB field.)

email()

Where / qill clause for email


    protected
                    email(array<string|int, mixed> &$values, string $isForcePrimaryOnly) : mixed

Parameters

$values : array<string|int, mixed>
$isForcePrimaryOnly : string

getEntitySpecificJoins()

Get join statements for the from clause depending on entity type


    protected
            static        getEntitySpecificJoins(string $name, int $mode, string $side, string $primaryLocation[, int $onlyDeleted = 0 ]) : string

Parameters

$name : string
$mode : int
$side : string
$primaryLocation : string
$onlyDeleted : int = 0

Return values

string

getGroupStatusClause()

Get the clause for group status.


    protected
                    getGroupStatusClause(int $grouping) : string

Parameters

$grouping : int

Return values

string

getMetadataForField()

Get the metadata for a given field.


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

Parameters

$fieldName : string

Return values

array<string|int, mixed>

getQillForRelativeDateRange()

Get the qill for the relative date range.


    protected
                    getQillForRelativeDateRange(string|null $from, string|null $to, string $fieldTitle, string $relativeRange) : string

Parameters

$from : string|null
$to : string|null
$fieldTitle : string
$relativeRange : string

Return values

string

getSelectedGroupStatuses()

Get an array of the statuses that have been selected.


    protected
                    getSelectedGroupStatuses(string $grouping) : array<string|int, mixed>

Parameters

$grouping : string

Return values

array<string|int, mixed>

isADateRangeField()

Is the field a relative date field.


    protected
                    isADateRangeField(string $fieldName) : bool

Parameters

$fieldName : string

Return values

bool

isARelativeDateField()

Is the field a relative date field.


    protected
                    isARelativeDateField(string $fieldName) : bool

Parameters

$fieldName : string

Return values

bool

isPseudoFieldAnFK()

Is this pseudofield a foreign key constraint.


    protected
                    isPseudoFieldAnFK(mixed $fieldSpec) : bool

We are trying to cautiously expand our pseudoconstant handling. This check allows us to extend to a narrowly defined type (and then only if the pseudofield is in the fields array which is done for contributions which are mostly handled as pseudoconstants.

Parameters

$fieldSpec : mixed

Return values

bool

prepareOrderBy()

Parse and assimilate the various sort options.


    protected
                    prepareOrderBy(string|CRM_Utils_Sort $sort, string|null $sortOrder) : string

Side-effect: if sorting on a common column from a related table (city, postal_code, email), the related table may be joined automatically.

At time of writing, this code is deeply flawed and should be rewritten. For the moment, it's been extracted to a standalone function.

Parameters

$sort : string|CRM_Utils_Sort: The order by string.
$sortOrder : string|null: ASC or DESC

Return values

string —

list(string $orderByClause, string $additionalFromClause).

createSqlCase()

Construct a SQL CASE expression.


    private
                    createSqlCase(string $idCol, array<string|int, mixed> $cids) : string

Parameters

$idCol : string: The name of a column with ID's (eg 'contact_a.id').
$cids : array<string|int, mixed>: Array(int $weight => int $id).

Return values

string —

CASE WHEN id=123 THEN 1 WHEN id=456 THEN 2 END

pseudoConstantNameIsInReturnProperties()

Has the pseudoconstant of the field been requested.


    private
                    pseudoConstantNameIsInReturnProperties(array<string|int, mixed> $field[, string $fieldName = NULL ]) : bool

For example if the field is payment_instrument_id then it has been requested if either payment_instrument_id or payment_instrument have been requested. Payment_instrument is the option groun name field value.

Parameters

$field : array<string|int, mixed>
$fieldName : string = NULL: The unique name of the field - ie. the one it will be aliased to in the query.

Return values

bool

CRM_Contact_BAO_Query in package CRM

Table of Contents

Constants

Properties

Methods

Constants

MODE_ACTIVITY

MODE_ALL

MODE_CAMPAIGN

MODE_CASE

MODE_CONTACTS

MODE_CONTACTSRELATED

MODE_CONTRIBUTE

MODE_EVENT

MODE_GRANT

MODE_MAILING

MODE_MEMBER

MODE_PLEDGE

MODE_PLEDGEBANK

NO_RETURN_PROPERTIES

SEARCH_OPERATOR_AND

SEARCH_OPERATOR_OR

Properties

$_activityRole

$_cfIDs

$_considerCompActivities

$_customQuery

$_defaultHierReturnProperties

$_defaultReturnProperties

$_dependencies

$_displayRelationshipType

$_distinctComponentClause

$_element

$_fields

$_fromClause

$_groupByComponentClause

$_groupKeys

$_groupUniqueKey

$_having

$_includeContactIds

$_locationSpecificCustomFields

$_locationSpecificFields

$_mode

$_onlyDeleted

$_openedPanes

$_operator

$_paramLookup

$_params

$_permissionFromClause

$_permissionWhereClause

$_primaryLocation

$_pseudoConstantsSelect

$_qill

$_relationshipTempTable

$_relType

$_returnProperties

$_rowCountClause

$_search

$_select

$_simpleFromClause

$_skipDeleteClause

$_skipPermission

$_smartGroupCache

$_sort

$_strict

$_tables

$_useDistinct

$_useGroupBy

$_where

$_whereClause

$_whereTables

$_withContactActivitiesOnly

$_rangeCache

$_relationshipValuesAdded

$legacyHackedFields

Methods

__construct()

Parameters

Tags

addGroupContactCache()

CRM_Contact_BAO_Query
in package

CRM