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

Configuration Module

Powerful addon instance configuration and management services.

Introduction

Powerful object instance configuration and management services.

Features

The Configuration module comes with everything you need to manage configuration values for addon instances.

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

Installation

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

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

Configuration

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

Configuration Keys

Configuration values are defined by a key and scope. The key is simply the dot namespace of the addon and the configuration field slug.

anomaly.extension.xml_feed_widget::url

Because configuration can support multiple instances of the same addon you must also provide a scope. The scope is any value your decide but is often an ID of an associated model entry.

Consider the above Dashboard module widget. The widget extension provides a configurable XML URL which you can define per instance. Each instance is tied to a widget entry model that's related to the given dashboard. In this scenario the scope is the ID of the dashboard widget entry model.

Defining Configuration

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

<?php

return [
    'url' => [
        'type'   => 'anomaly.field_type.url',
        'config' => [
            'default_value' => 'http://www.pyrocms.com/posts/rss.xml',
        ],
    ],
];

Defining Form Sections

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

<?php

return [
    'general'      => [
        'context' => 'info',
        'title'   => 'example.module.test::label.general',
        'fields'  => [
            'name',
            'description',
        ],
    ],
];

Displaying Configuration Forms

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

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

use \Anomaly\ConfigurationModule\Configuration\Form\ConfigurationFormBuilder;

public function edit(ConfigurationFormBuilder $builder, $id)
{
    return $builder
        ->setScope($id)
        ->render('anomaly.extension.xml_feed_widget');
}
Pro Tip: The configuration 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.

Configuration

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

Configuration Interface

This section will go over the \Anomaly\ConfigurationModule\Configuration\Contract\ConfigurationInterface class.

ConfigurationInterface::field()

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

Returns: \Anomaly\Streams\Platform\Addon\FieldType\FieldType or null
Example
$config = $configuration->get('anomaly.extension.xml_feed_widget::url');

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

Configuration Repository

This section will go over the \Anomaly\ConfigurationModule\Configuration\Contract\ConfigurationRepositoryInterface class.

ConfigurationRepositoryInterface::get()

The get method returns the configuration instance.

Returns: \Anomaly\ConfigurationModule\Configuration\Contract\ConfigurationInterface
Arguments
Key Required Type Default Description

$key

true

string

none

The configuration key.

$scope

true

mixed

none

The configuration scope.

Example
$url = $configuration->value(
    'anomaly.extension.xml_feed_widget::url',
    $widget->getId()
);

echo $url->getValue();
ConfigurationRepositoryInterface::set()

The set method allows you to set a configuration value.

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

$key

true

string

none

The configuration key.

$scope

true

string

none

The configuration scope.

$value

true

mixed

none

The configuration value.

Example
$configuration->set(
    'anomaly.extension.xml_feed_widget::url',
    $this->widget->getId(),
    'http://www.pyrocms.com/posts/rss.xml'
);
ConfigurationRepositoryInterface::value()

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

Returns: mixed
Arguments
Key Required Type Default Description

$key

true

string

none

The configuration key.

$key

true

string

none

The configuration key.

$default

false

mixed

null

The default value.

Example
$value = $configuration->value(
    'anomaly.extension.xml_feed_widget::url',
    $this->widget->getId(),
    'http://www.pyrocms.com/posts/rss.xml'
)
ConfigurationRepositoryInterface::presenter()

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

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

$key

true

string

none

The configuration key.

$scope

true

mixed

none

The configuration scope.

Example
$url = $configuration->value(
    'anomaly.extension.xml_feed_widget::url',
    $this->widget->getId()
);

echo $url->link('Example Link!');