Skip to content

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.

  1. Navigate into your extension

    cd myexample

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

  3. 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?'),
  ],
];

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

    cv flush

  5. 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 more about: