edalzell / forma
Give control panel access to your addon's config
Installs: 34 748
Dependents: 8
Suggesters: 0
Security: 0
Stars: 8
Watchers: 2
Forks: 4
Open Issues: 0
Type:statamic-addon
Requires
- php: ^8.0
- laravel/framework: ^10.0 || ^11.0
- statamic/cms: ^4.0 || ^5.0
- stillat/proteus: ^4.0
Requires (Dev)
- mockery/mockery: ^1.3.1
- nunomaduro/collision: ^7.0 || ^8.0
- orchestra/testbench: ^8.0 || ^9.0
- phpunit/phpunit: ^10.0 || ^11.0
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 bootAddon
method of your addon's Service Provider add:
\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