Hotaru Docs

 [həʊdɒks]

Save and Access Plugin Settings

Here are all the common functions that plugins need for settings, using a fictitious "Rainbow" plugin as an example:

Include default settings when a plugin is first activated

In your plugin, put the install_plugin in your "hooks" list at the top, then include a function with the hook's name, e.g:

public function install_plugin($h)
{
    if (!$h->isSetting('color')) {
        $h->updateSetting('color', 'blue');
    }
}

When your plugin is activated, that function will be automatically called and the word blue will be stored in pluginsettings in the database with the name rainbow_color for the plugin rainbow.

Update a setting in the database

At anytime, in any of your functions, just include that same line and you'll overwrite the existing setting:

$h->updateSetting('color', 'green');

Add a new setting in the database

You can add a new setting the same way. If it doesn't exist, it creates it:

$h->updateSetting('pot_of', 'gold');

Remove a setting from the database

You can remove a setting just as easily:

$h->deleteSettings('color');

or remove all settings for your plugin:

$h->deleteSettings('', 'rainbow');

Check if a setting exists

if ($h->isSetting('color')) {
        echo "Yes, there is a color";
    }

Get a setting from the database

Get the value stored in 'color' like this:

$color = $h->getSetting('color');

Multiple values in a single setting

You might be wondering how to add all the colors to our example Rainbow plugin. Hotaru doesn't allow multiple rows with the same plugin and setting because each time you add a new row, it will just overwrite the previous one because the plugin name and settings value are the same. So, we can't do this:

$h->updateSetting('color', 'red');
$h->updateSetting('color', 'green');
$h->updateSetting('color', 'blue');
...

Instead, we can serialize the colors like this:

$colors = array('red', 'green', 'blue');
$h->updateSetting('colors', serialize($colors));

Get them back like this:

$colors = $this->getSetting('colors');
$colors = unserialize($colors);
// so $colors = array('red', 'green', 'blue');

Alternatively, you could get the settings already unserialized, like this:

$colors = $h->getSerializedSettings('rainbow', 'colors');

Pro Tip: That last one is commonly used in plugin install functions and uses the plugin folder parameter first as a shortcut - if no parameters are specified, Hotaru takes the plugin folder name and appends "_settings" on the end, so if we had called our example settings "rainbow_settings", we could have just said $h->getSerializedSettings(); with no parameters.

Multiple values as an array

If serializing the settings isn't an option, you can use this trick: Instead of calling the updateSetting function with Setting, Value and Plugin as arguments, replace the plugin argument with a group name, assign the value to the setting argument and leave the value argument empty, like this:

$h->updateSetting('red', '', 'rainbow_colors');
$h->updateSetting('green', '', 'rainbow_colors');
$h->updateSetting('blue', '', 'rainbow_colors');
...

That way, each setting is unique so we don't have to worry about overwriting the others. To work with this data, we'll need a new function to extract it all as an array:

$rainbow_colors = $h->getSettingsArray('rainbow_colors');

That will return something like this:

[0] => [plugin_setting] => red
       [plugin_value] => 
 
[1] => [plugin_setting] => green
       [plugin_value] => 
 
[2] => [plugin_setting] => blue
       [plugin_value] =>
Getting StartedDesign and LayoutPlugin DevelopmentAdvanced TopicsFunction ReferenceTroubleshooting