Have you seen our new video tutorials? Check it out!

Settings Module

Powerful addon settings and management services.

Introduction

Powerful addon settings and management services.

Features

The Settings module comes with everything you need to manage settings values for addons.

  • Powered by Field Types
  • Compatible with any addon.
  • Easy integration with any project.

Installation

You can install the Settings module with the addon:install command:

php artisan addon:install anomaly.module.settings
Notice: The Settings module comes installed with PyroCMS out of the box.

Settings

Settings values are powered entirely by field types. This section will go over the basics of defining, managing, and using settings for addons.

Settings Keys

Settings values are defined by a key. The key is simply the dot namespace of the addon and the setting field slug.

anomaly.modules.files::max_upload_size

Defining Settings

Configuration is defined using field definitions located in the addon's resources/config/settings.php file:

<?php

return [
    'max_upload_size'      => [
        'type'     => 'anomaly.field_type.integer',
        'required' => true,
        'config'   => [
            'default_value' => function () {
                $post = str_replace('M', '', ini_get('post_max_size'));
                $file = str_replace('M', '', ini_get('upload_max_filesize'));

                return $file > $post ? $post : $file;
            },
            'max'           => function () {
                $post = str_replace('M', '', ini_get('post_max_size'));
                $file = str_replace('M', '', ini_get('upload_max_filesize'));

                return $file > $post ? $post : $file;
            },
            'min'           => 1,
        ],
    ],
    'max_parallel_uploads' => [
        'type'     => 'anomaly.field_type.integer',
        'required' => true,
        'config'   => [
            'default_value' => 3,
            'min'           => 1,
        ],
    ],
];

Defining Form Sections

You can also quickly define form sections the same as fields. To define sections move your resources/config/settings.php file to resources/settings/settings.php and include a resources/settings/sections.php file to define sections. The sections.php file simply returns an array of section definitions:

<?php

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

Displaying Settings Forms

Settings can be set by API just like any other Stream entry however you may want to display a settings form.

To get started you can extend or inject the \Anomaly\SettingsModule\Setting\Form\SettingFormBuilder class. The entry value for configuration form builders are the addon's dot namespace:

use \Anomaly\SettingsModule\Setting\Form\SettingFormBuilder;

public function edit(SettingFormBuilder $builder)
{
    return $builder->render('anomaly.module.files');
}
Pro Tip: The settings form builder is not much different than any other form builder so go crazy and extend or customize as needed in your own project.

Usage

This section will show you how to use the addon via API and in the view layer.

Settings

This section will go over how to utilize the settings values you have defined.

Setting Interface

This section will go over the \Anomaly\SettingsModule\Setting\Contract\SettingInterface class.

SettingInterface::field()

The field method returns the field type instance for the value or null if the value's field no longer exists.

Returns: \Anomaly\Streams\Platform\Addon\FieldType\FieldType or null
Example
$setting = $settings->get('anomaly.module.files::max_upload_size');

if ($field = $setting->field()) {
    echo $field->getValue();
}

Setting Repository

This section will go over the \Anomaly\SettingsModule\Setting\Contract\SettingRepositoryInterface class.

SettingRepositoryInterface::get()

The get method returns the setting instance.

Returns: \Anomaly\SettingsModule\Setting\Contract\SettingInterface
Arguments
Key Required Type Default Description

$key

true

string

none

The setting key.

Example
$max = $settings->value('anomaly.module.files::max_upload_size');

echo $max->getValue();
SettingRepositoryInterface::set()

The set method allows you to set a setting value.

Note: Values are passed through the setting's field modifier.
Returns: boolean
Arguments
Key Required Type Default Description

$key

true

string

none

The setting key.

$value

true

mixed

none

The setting value.

Example
$settings->set('anomaly.module.files::max_upload_size', 32);
SettingRepositoryInterface::value()

The value method returns the value as the setting field type normally would with getType.

Returns: mixed
Arguments
Key Required Type Default Description

$key

true

string

none

The setting key.

$default

false

mixed

null

The default value.

Example
$value = $settings->value('anomaly.module.files::max_upload_size', 2);
SettingRepositoryInterface::presenter()

The presenter method returns the setting value's field type presenter or null if the value's field no longer exists.

Returns: \Anomaly\Streams\Platform\Addon\FieldType\FieldTypePresenter or null
Arguments
Key Required Type Default Description

$key

true

string

none

The setting key.