Settings: Tutorial¶

About this document

This is a step-by-step walk-through for adding settings to an extension.

For a conceptual overview about the general purpose and shape of "Settings", please skim the Settings: Introduction.

Let's suppose you have created an extension called myexample:

civix generate:module myexample

For this extension, we will add a new setting ("Turbo Charge: Yes or No?") and present an admin form.

Navigate into your extension
```
cd myexample
```
Enable the standard mixins for settings:
```
civix mixin --enable=setting-php@1,setting-admin@1
```
These two mixins sound similar, but they have distinct purposes:
- setting-php@1: Load *.setting.php files.
- setting-admin@1: Generate an administrative UI for your settings.

Create a settings file, e.g.

mkdir settings
nano settings/myexample.setting.php

The file should return an array of settings. By convention, each setting is prefixed with the extension-name. For our "Turbo Charged" setting, we will call it myexample_turbocharged.

<?php
use CRM_Myexample_ExtensionUtil as E;
return [
  'myexample_turbocharged' => [
    'group' => 'myexample',
    'name' => 'myexample_turbocharged',
    'type' => 'Boolean',
    'default' => FALSE,
    'html_type' => 'YesNo',
    'quick_form_type' => 'YesNo',
    'title' => E::ts('Turbo Charge'),
    'is_domain' => 1,
    'is_contact' => 0,
    'description' => E::ts('Should the example extension be turbo-charged?'),
  ],
  // Example Setting that gets stored encrypted in the database.
  'myexample_apikey' => [
    'name' => 'myexample_apikey',
    'type' => 'String',
    'default' => '',
    'htmlType' => 'password',
    'title' => E::ts('API Key'),
    'is_domain' => 1,
    'is_contact' => 0,
    'post_update' => [
      'CRM_Myexample_Utils::updateAPIKey',
    ],
  ],
];

For the 2nd one then do the following

nano CRM/Myexample/Utils.php

php<?phpuse CRM_Myexample_ExtensionUtil as E;class CRM_Myexample_Utils {private static $beenHereAlready = FALSE;public static function updateAPIKey($oldValue, $newValue, $metadata) {if (!self::$beenHereAlready) {try {$oldValue = Civi::service('crypto.token')->decrypt($oldValue, ['plain', 'CRED']);}catch (\Throwable $e) {\Civi::log()->debug('Could Not decrpt original password');$oldValue = '';}try {$newValue = Civi::service('crypto.token')->decrypt($newValue, ['plain', 'CRED']);}catch (\Throwable $e) {\Civi::log()->debug('Could Not decrpt new password');$newValue = '';}if ($oldValue == $newValue) {return;}self::$beenHereAlready = TRUE;$encryptedNewValue = Civi::service('crypto.token')->encrypt($newValue, 'CRED');Civi::settings()->set('myexample_apikey', $encryptedNewValue);}}}

After any update to the settings definition, you should flush the system, e.g.
```
cv flush
```

You can now read and write values of this setting, as in:

Admin UI: As an administrator, navigate to "Administer > System Settings > myexample Settings".

Admin CLI: To read or write settings on the command-line, use cv.

# Set the value to true
cv vset myexample_turbocharged=1

# Skim the settings in your extension
cv vget /myexample/

# Inspect the setting
cv vget myexample_turbocharged -a

Programmatic APIs: You can update your extension to manipulate the setting programmatically. For example:

// Set the value to ture
Civi::settings()->set('myexample_turbocharged', TRUE);

// Get the current value
Civi::settings()->get('myexample_turbocharged');

To develop this example further, you should read more about:

Settings: Definitions: Learn how to use metadata to tweak the definition and behavior.
Settings: Forms: Learn how to control the GUI form
Settings: Usage: Learn to how to read/write settings in PHP, APIv4, Smarty, and other contexts. See also example of decrypting the setting before use which is important if you have implented such a post update