Options
All plugins need some options. You may put your options model array in config/options.php
:
<?php
/*
|--------------------------------------------------------------------------
| Plugin options
|--------------------------------------------------------------------------
|
| Here is where you can insert the options model of your plugin.
| These options model will be stored in WordPress options table
| (usually wp_options).
| You'll get these options by using $plugin->options property
|
*/
return [
'version' => '1.0',
'General' => [
'option_1' => 'true',
'option_2' => 'true',
'option_3' => [
'sub_option_of_3' => 'Hello'
],
'option_4' => 'to delete'
],
'Special' => [
'Name' => 'James Kirk'
]
];
The options are subjected to case sensitive. So, have a look to first key General
. You should get it by using $plugin->options->get('General.option_1')
for instance.
The plugin options are created on the first activation of the plugin into the wp_options
database table. The name of option (option_name
) will be the plugin slug. The options array will be converted in JSON and stored in option_value
.
Get options
To acquire an option from your model, simply call the get
method:
echo $plugin->options->get( 'General.option_1');
Secondly, you may access the options like an array, since it implements PHP's ArrayAccess
interface:
echo $plugin->options[ 'General.option_1' ];
Of course, you may get a branch from your model by using:
echo $plugin->options->get( 'General.options_4');
That will return an array [ "sub_options_of_3" => 'Hello' ]
.
Whether the option doesn't exist, you may define a default value:
echo $plugin->options->get( 'General.doNotExists', 'default');
Update options
To update a single or branch option, simply call the set
method:
$plugin->options->set( 'General.options_2', false );
or by using the array access:
$plugin->options[ 'General.options_2' ] = false;
The set
method is also used to create a new option:
$plugin->options->set( 'Special.time', time() );
The value set may be a mixed value:
$plugin->options->set( 'Special.Name', [ 'John', 'Good' ] );
or by using the array access:
$plugin->options[ 'Special.Name' ] = [ 'Robin', 'Hood' ];
You may also use the update
method to update a set of options:
$plugin->options->update(
[
'General' => [
'option_4' => [
'color' => 'red',
'background' => 'transparent'
]
]
]
);
Or insert a set of options:
$plugin->options->update(
[
'General' => [
'option_5' => [
'color' => 'red',
'background' => 'transparent'
]
]
]
);
If you wish to delete an option, you may also use:
$plugin->options->set( 'Special.Name', null );
or
$plugin->options->set( 'Special.Name' );
Delete options
To delete a single option use:
$plugin->options->delete( 'General.option_4' );
To delete all options use:
$plugin->options->delete();
Reset to default options
To reset the options to last version, please use:
$plugin->options->reset();
New version of options
When you release a new version of your plugin, you could add, remove or delete some options. To do so, just edit your options array. When your plugin is updated and activated again, the new options will apply through a delta process.
Display options in pretty format
You may display all options plugin in JSON by using echo $plugin->options
. This feature is useful to inject your options like a Javascript object:
add_action( 'wp_head', 'wp_head' );
public function wp_head()
{
?>
<script>
window.MyJavascriptGlobalObject = <?php echo MyPluginGlobalFunction()->options ?>;
</script>
<?php
}
Then you'll find the following, in your HTML source page:
<script>
window.MyJavascriptGlobalObject = {
"General": {
"option_1": true,
"option_2": true
}
}
</script>
Get options as an array
If you wish to get the options as a flat array, please use:
$result = MyPluginGlobalFunction()->options->toArray();