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

Preferences Module

Powerful user specific addon preferences and management services.

Introduction

Powerful user specific addon preferences and management services.

Features

The Preferences module comes with everything you need to manage user preference values for addons.

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

Installation

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

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

Preferences

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

Preferences Keys

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

anomaly.modules.files::parallel_uploads

Defining Preferences

Preferences are defined using field definitions located in the addon's resources/config/preferences.php file:

<?php

return [
    '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/preferences.php file to resources/preferences/preferences.php and include a resources/preferences/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',
        ],
    ],
];

Displaying Preferences Forms

Preferences 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\PreferencesModule\Preference\Form\PreferenceFormBuilder class. The entry value for configuration form builders are the addon's dot namespace and the user is detected automatically:

use \Anomaly\PreferencesModule\Preference\Form\PreferenceFormBuilder;

public function edit(PreferenceFormBuilder $builder)
{
    return $builder->render('anomaly.module.files');
}
Pro Tip: The preferences 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.

Preferences

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

Preference Interface

This section will go over the \Anomaly\PreferencesModule\Preference\Contract\PreferenceInterface class.

PreferenceInterface::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_parallel_uploads');

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

Preference Repository

This section will go over the \Anomaly\PreferencesModule\Preference\Contract\PreferenceInterface class.

PreferenceRepositoryInterface::get()

The get method returns the preference instance.

Returns: \Anomaly\PreferencesModule\Preference\Contract\PreferenceInterface
Arguments
Key Required Type Default Description

$key

true

string

none

The preference key.

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

echo $max->getValue();
PreferenceRepositoryInterface::get()

The get method returns the preference instance.

Returns: \Anomaly\PreferencesModule\Preference\Contract\PreferenceInterface
Arguments
Key Required Type Default Description

$key

true

string

none

The preference key.

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

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

The set method allows you to set a preference value.

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

$key

true

string

none

The preference key.

$value

true

mixed

none

The preference value.

PreferenceRepositoryInterface::value()

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

Returns: mixed
Arguments
Key Required Type Default Description

$key

true

string

none

The preference key.

$default

false

mixed

null

The preference value.

Example
$value = $settings->value('anomaly.module.files::max_parallel_uploads', 5);
PreferenceRepositoryInterface::presenter()

The presenter method returns the preference 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 preference key.

Example
$decorated = $settings->presenter('anomaly.module.files::max_parallel_uploads');

echo $decorated->value;