Skip to content

Pseudoconstant (Option List) Reference

Introduction

CiviCRM defines a Pseudoconstant as: "A list of options associated with a field, the contents of which rarely changes." This documentation uses the terms "pseudoconstant" and "option list" interchangeably.

Field

Option lists are applicable to any type of field with selectable options (radio, checkbox, select, autocomplete, etc.).

Attributes

Each option in a list is made up of multiple attributes which serve different purposes. These are also sometimes referred to as "suffixes", since APIv4 can reference them by appending the attribute name as a suffix like 'state_province_id:abbr'.

Required attributes:

All option lists have at least these 3 attributes:

  • id Unique identifier (string or int), this is the value that is stored in the field to indicate this option.
  • name 2nd unique identifier (string). Useful especially when id is an auto-increment integer, to give a stable, readable handle for the option. In other cases where id is already a string, name will be identical & redundant.
  • label: This is the localized string shown to the user to represent the option. Labels should not be relied on by developers since they are subject to change, translation, and string-replacement.

Additional attributes:

Some options have one or more of these additional attributes:

  • description: Extra descriptive text, shown below the label in a lighter font.
  • color: Hex-notation value for color-coded options.
  • icon: String representing an icon's css class.
  • abbr: Short abbreviation for e.g. State/Province options.
  • grouping: Misc. use flag for classifying options, e.g. "should this participant status be counted".
  • url: Url if the option represents a hyperlink.

Option List Storage

  • Most option lists are stored in the database in the civicrm_option_value table. The name of each list is specified in the civicrm_option_group table.
    • The OptionValue api allows CRUD functions on option lists stored in this table.
    • Additionally, the CustomField api provides a convenient method for creating a field and an associated option list at once.
  • Other larger or more complex option lists have their own dedicated tables, e.g. civicrm_relationship_type, civicrm_state_province, civicrm_location_type
    • Each of these tables has its own api for manipulating the values.
  • Some option lists are supplied via callback functions.

Option List Modification

To modify a field's options programmatically, or to supply a new list of options for a field, use hook_civicrm_fieldOptions.

Option List Retrieval

Recommended Methods:

  • APIv4.getFields: For details see the chapter APIv4 Pseudoconstants (Option Lists).

  • Civi::entity($entityName)->getOptions($fieldName): Will retrieve the complete option list with all attributes.

Deprecated Methods:

The following older methods of option list retrieval are deprecated and code using them should be updated:

  • CRM_Core_Pseudoconstant::get
  • CRM_Core_Pseudoconstant::getName
  • CRM_Core_Pseudoconstant::getLabel
  • CRM_Core_Pseudoconstant::getKey
  • CRM_*_BAO_*::buildOptions
  • api3.getoptions

Caching

Option lists are cached in memory for performance, so in writing your code you should not have to worry about the impact of retrieving the same option list twice.

In most circumstances, this cache is automatically flushed if an option list gets modified. To manually flush CiviCRM's metadata cache, call:

Civi::cache('metadata')->clear();