README

This package provides an easy way to let users configure your addon.

Requirements

PHP 8.2+
Laravel 10.0+
Statamic 4.0+

Installation

You can install this package via composer using:

composer require edalzell/forma

The package will automatically register itself.

Usage

First, create a config.yaml file in resources\blueprints that contains the blueprint for your configuration. As an example, see Mailchimp's, here.

Then, in the boot method of your addon's Service Provider add:

parent::boot();
\Edalzell\Forma\Forma::add('statamic-rad-pack/mailchimp', ConfigController::class);

The second parameter is optional and only needed if you need custom config handling (see Extending below)

There is a 3rd parameter handle you can use if the config file is NOT the addon's handle.

Once you do that, you get a menu item in the cp that your users can access and use. All data is saved into your addon_handle.php (or $handle as per above) in the config folder.

Permissions

There is a Manage Addon Settings permission that must be enabled to allow a user to update the settings of any Forma-enabled addons.

Extending

If your addon needs to wangjangle the config before loading and after saving, create your own controller that extends \Edalzell\Forma\ConfigController and use the preProcess and postProcess methods.

For example, the Mailchimp addon stores a config like this:

'user' => [
    'check_consent' => true,
    'consent_field' => 'permission',
    'merge_fields' => [
        [
            'field_name' => 'first_name',
        ],
    ],
    'disable_opt_in' => true,
    'interests_field' => 'interests',
],

But there is no Blueprint that supports that, so it uses a grid, which expects the data to look like:

'user' => [
    [
        'check_consent' => true,
        'consent_field' => 'permission',
        'merge_fields' => [
            [
                'field_name' => 'first_name',
            ],
        ],
        'disable_opt_in' => true,
        'interests_field' => 'interests',
    ]
],

Therefore in its ConfigController:

protected function postProcess(array $values): array
{
    $userConfig = Arr::get($values, 'user');

    return array_merge(
        $values,
        ['user' => $userConfig[0]]
    );
}

protected function preProcess(string $handle): array
{
    $config = config($handle);

    return array_merge(
        $config,
        ['user' => [Arr::get($config, 'user', [])]]
    );
}

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email addon-security@silentz.co instead of using the issue tracker.

License

MIT License

edalzell / forma

Maintainers

Details