Settings

Accessing Values

You can use the SettingRepositoryInterface to access setting values. To get started include the repository interface within your code.

<?php namespace Anomaly\ExampleModule\Example\Command;

use \Anomaly\SettingsModule\Setting\Contract\SettingRepositoryInterface;

public function handle(SettingRepositoryInterface $settings)
{
    // Handle the command.
}

You can also simply resolve the interface from Laravel's service container using the app helper:

$settings = app(\Anomaly\SettingsModule\Setting\Contract\SettingRepositoryInterface:class);

Settings Keys

Settings are accessed by their key. Setting keys consist of a hint and the setting's field_slug like hint::field_slug.

All addons can be hinted with their dot notation namespace like anomaly.module.example::field_slug and the Streams Platform can be hinted like streams::field_slug.

Retrieving Values

Raw Values

Use the value method to return the raw setting value by it's key. An optional default value can be passed as well.

$value = $settings->value($key, $default = null);

$max = $settings->value('anomaly.module.files::max_upload_size', 5);
// 32

{{ settings_value($key, $default = null) }}

{{ settings_value('anomaly.module.files::max_upload_size', 5) }}
// 32

Decorated Values

Use the presenter method to return the decorated field type for a setting key. Default is not supported here.

$fieldType = $settings->presenter($key);

For example the GitHub token setting for the GitHub extension uses the encrypted field type. In order to work with the value you must obtain the decorated value and use it's decrypt method:

$token = $settings->presenter('anomaly.extension.github::token');

echo $token->decrypt();

{{ settings('anomaly.extension.github::token').decrypt() }}

Storing Values

You can again use the SettingRepositoryInterface to store setting values.

Use the set method to set a setting key to a specific value.

$setting->set($key, $value);

$setting->set('anomaly.module.files::max_upload_size', 5);

The value must be supported by the setting's configured field type.{.note}

Configuring Settings

You can define your own settings for your addons or override existing settings using configuration.

Defining Settings

To get started create a settings.php file in the config directory of the addon you're working on and define some settings:

<?php

return [
    'token' => [
        'required' => true,
        'type'     => 'anomaly.field_type.encrypted',
    ],
];

Binding Settings to Configuration

You can automatically set config values based on settings by defining the bind parameter.

In this way you can decouple the settings module from your own and standardize accessing values by using config(key) where key is the bind value of your setting:

return [
    'token' => [
        'required' => true,
        'type'     => 'anomaly.field_type.encrypted',
        'bind'     => 'anomaly.extension.github::github.token',
    ],
];

The above setting value (decrypted as well) can be accessed with configuration:

config('anomaly.extension.github::github.token');

{{ config('anomaly.extension.github::github.token') }}

Locking Environmental Settings

Some settings may be bound to configuration that is also settable from your .env file. In order to indicate this use the env parameter.

When the env value is set then the settings UI will be locked to prevent changing.

return [
    'token' => [
        'required' => true,
        'env'      => 'GITHUB_TOKEN',
        'type'     => 'anomaly.field_type.encrypted',
        'bind'     => 'anomaly.extension.github::github.token',
    ],
];

In the above example, if GITHUB_TOKEN=somevalue in your .env file then the UI for this setting will be disabled.

Defining Settings Form Sections

You can also quickly define form sections to organize your settings using a sections.php configuration file. When using sections you must place the sections.php and settings.php files in a settings directory within the addon's config directory like config/settings/sections.php.

Learn more about form sections.

<?php

return [
    'details'      => [
        'title'   => 'streams::label.details',
        'fields'  => [
            'name',
            'description',
        ],
    ],
    'contact'      => [
        'context' => 'primary',
        'title'   => 'streams::label.contact',
        'fields'  => [
            'business',
            'phone',
            'address',
            'address2',
            'city',
            'state',
            'postal_code',
            'country',
        ],
    ],
];

Rendering Settings Forms

All settings can be accessed from the Settings module. However you can display settings forms yourself if desired as well by using the included form builder.

To get started simply include the \Anomaly\SettingsModule\Setting\Form\SettingFormBuilder class into your controller and specify the addon you would like to display settings for:

<?php namespace Anomaly\ExampleModule\Http\Controller\Admin\SettingsController;

use \Anomaly\SettingsModule\Setting\Form\SettingFormBuilder;
use \Anomaly\Streams\Platform\Http\Controller\AdminController;

class SettingsController extends AdminController
{
    public function edit(SettingFormBuilder $builder)
    {
        return $builder->render('anomaly.module.example');
    }
}