Settings & Option Reference

CiviCRM Settings & Option Reference — How to Use

CiviCRM uses two complementary systems for configuration: system settings stored in the civicrm_setting table, and option groups which store lists of selectable values for dropdowns and multi-select fields throughout the UI and API.

This reference covers all major system settings and option groups you'll encounter when building CiviCRM extensions, writing API calls, or configuring a CiviCRM installation. Use the search to find any setting or option group by name or description, and filter by type to focus on either settings or option groups.

System Settings

System settings are key-value pairs read with Civi::settings()->get('setting_name') in PHP or civicrm_api4('Setting', 'get', { select: ['setting_name'] }) via API. They can be overridden in civicrm.settings.php using define('CIVICRM_SETTING_NAME', value). Settings control behavior like debug mode, email configuration, attachment limits, date formats, and UI resources.

Option Groups

Option groups (also called pseudoconstants) power almost every dropdown in CiviCRM. The values are stored in civicrm_option_value and reference a parent civicrm_option_group record. To fetch all values in an option group via APIv4: civicrm_api4('OptionValue', 'get', { where: [['option_group_id:name', '=', 'group_name']] }). Never hard-code option value IDs in extension code — they differ between installations. Always look up by name or label.

Why This Matters for Extension Developers

• Option value IDs (e.g., activity_type_id = 1 for "Phone Call") are not fixed across CiviCRM installations. Use APIv4 pseudoconstant lookups or name-based filtering.
• System settings can be overridden at the domain level in multi-site setups using Civi::settings()->setDomain($domainId)->set('key', 'value').
• New option values should be added via a managed entity in your extension's managed/ folder to ensure they are created on install and cleaned up on uninstall.