Skip to content

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.

  1. Navigate into your extension

    bash cd myexample

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

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

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

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

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