4.2.5. Configuration

⁠4.2.5. Configuration

Similar to events, plugins have a simplified method for declaring configuration options, as well as API functions for retrieving or setting those values at runtime.

Declaring a new configuration option is achieved just like declaring events. By overriding the config() method on your plugin class, your plugin can return an associative array of configuration options, with the option name as the key, and the default option as the array value. Our Example plugin will declare an option "foo_or_bar", with a default value of "foo":

Example/Example.php

<?php
class ExamplePlugin extends MantisPlugin {
    ...

    function config() {
        return array(
            'foo_or_bar' => 'foo',
        );
    }
}

Retrieving the current value of a plugin's configuration option is achieved by using the plugin API's plugin_config_get() function, and can be set to a modified value in the database using plugin_config_set(). With these functions, the config option is prefixed with the plugin's name, in an attempt to automatically avoid conflicts in naming.

Our Example plugin will demonstrate this by adding a secure form to a new configuration page we'll call config.php, and handling the form on a separate config_update.php page that will modify the value in the database, and redirect back to the config page, just like any other form and action page in MantisBT:

Note

This code sample is a bare-bones implementation, focusing on functionality and meant for illustration purposes. Please refer to Section 4.2.7, “Layout” for a more realistic example, including layout and styling.

Example/pages/config.php

<?php
$t_foo_or_bar = plugin_config_get( 'foo_or_bar' );
?>

<form action="<?php echo plugin_page( 'config_update' )?>" method="post">
    <?php echo form_security_field( 'plugin_Example_config_update' ) ?>
    <label>
        Foo or Bar?
        <input name="foo_or_bar" value="<?php echo string_attribute( $t_foo_or_bar ) ?>" />
    </label>
    <br>
    <label>
        Reset
        <input type="checkbox" name="reset" />
    </label>
    <br>
    <input type="submit" />
</form>

Example/pages/config_update.php

<?php
form_security_validate( 'plugin_Example_config_update' );

$f_foo_or_bar = gpc_get_string( 'foo_or_bar' );
$f_reset = gpc_get_bool( 'reset', false );

form_security_purge( 'plugin_Example_config_update' );

if( $f_reset ) {
    plugin_config_delete( 'foo_or_bar' );
} elseif( $f_foo_or_bar == 'foo' || $f_foo_or_bar == 'bar' ) {
    plugin_config_set( 'foo_or_bar', $f_foo_or_bar );
} else {
    error_parameters( 'foo_or_bar', string_attribute( $f_foo_or_bar ) );
    trigger_error( ERROR_CONFIG_OPT_INVALID, ERROR );
}

print_successful_redirect( plugin_page( 'config', true ) );

Note

The form_security_*() functions are part of the Form API, and prevent CSRF attacks against forms that make changes to the system.

The last step is to add a link our new config page from the Manage Plugins page. This is as simple as referencing the config page's name in the register() method, which will turn the Plugin's name into an hyperlink.

Example/Example.php

	function register() {
		...
		$this->page = 'config';     # Default plugin page