Home > Developer Guide > Framework > Settings

Settings: Tutorial

???+ tldr "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](./index.md).

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

bash cd myexample
Enable the standard mixins for settings:

bash 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.

bash 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 <?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' => '', 'html_type' => '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 bash nano CRM/Myexample/Utils.php

    <?php
    use 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.

bash 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.
  
```bash

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:
  
```php // 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

Settings: Tutorial

Set the value to true

Skim the settings in your extension

Inspect the setting