WordPress MU

If you're following the latest dev release hold back on upgrading to 1188 until you read this post and check your plugins.

The way options work in the backend has been overhauled. There is now a whitelist for each options page hardcoded in the options page. It's possible to add options to the whitelist if you're developing plugins but unfortunately this means that any old plugin that submits to /wp-admin/options.php will break.

New API:
add_option_update_handler($option_group, $option_name, $sanitize_callback = '')
This function adds an option called $option_name to the group(or page) $option_group. Optionally, $sanitize_callback is the name of a function used to sanitize the option value before saving.

remove_option_update_handler($option_group, $option_name, $sanitize_callback = '')
This function removes an option in the same way as above.

There are another two functions, add_option_whitelist( $new_options, $options = '' ) and remove_option_whitelist( $del_options, $options = '' ) which are useful for adding and removing options in bulk, but they're mostly for internal use by the first two functions.
See the function mu_options() in wp-admin/includes/mu.php for an example of usage.

Thanks for the warning, D.

Donncha,

I tried upgrade to 1188, but when I click update in option page. The url of Siteurl has removed. any advice. Thanks.

mypatricks - thanks for the quick report. Fixed that in 1189!

Should I expect any problems when adding an option using the get_site_option() function?

It took me a while to figure this out. To use the add_option_update_handler() function you have to call it at the right point. Calling it at init won't work.

This works for me.
add_action('admin_menu', 'blah_admin_menu');
function blah_admin_menu() {
add_option_update_handler('blah', 'blah_option_name');
}

There might be a better place to call it though, I'd welcome any suggestions on that front. :)

Hi,

I have MU 2.6.1 and did exactly what chmac said here inside a mu-plugin, and it doesn't work.

It seems that at the time that add_option_update_handler is called, $whitelist_options is still empty, and then after the merge with my $new_whitelist_options, it gets overwritten along the way and my options are not visible.

Any ideas? Maybe inside a mu-plugin it's different than in a regular plugin?

@orensol: That code is running for me in mu-plugins and working fine. Perhaps your error lies elsewhere?

Did you read through the add_option_update_handler() code? You need to add some hidden form variables to the page to set the option group, then create the function to save the data.

In the admin page:

<form action="options.php" method="POST">
<input type='hidden' name='option_page' value='blah' />
...
<input id="blah_option_name" type="checkbox" name="blah_option_name" value="1" <?php checked('1', get_option('blah_option_name')); ?>/>
...
<input type="hidden" name="action" value="update" />
<input type="submit" name="Submit" value="Save Changes" class="button" />

That code, along with the stuff above, works for me on WPMU, running pretty up to date code (couldn't swear it's 2.6.3).

@chmac: It now works, by doing the following code:

add_action('admin_menu', 'blah_admin_menu');
function blah_admin_menu()
{
add_options_page('blah', 'blah', 8, __FILE__, 'blah_admin_page');
add_option_update_handler('blah', 'blah_locale');
}
function blah_admin_page()
{
?>
<form action="options.php" method="POST">
<?php wp_nonce_field('blah-options'); ?>
<input type='hidden' name='option_page' value='blah' />
blah_locale:
<input id="blah_locale" type="text" name="blah_locale" value="<?php echo get_option('blah_locale'); ?>"/>
<input type="hidden" name="action" value="update" />
<input type="submit" name="Submit" value="Save Changes" class="button" />
</form>
<?php
}


The nonce action argument and the option_page input took some time to figure through the code (it kept failing on check_admin_referrer).

Anyway, the only weird thing now is, that when I access option.php directly, I get the following warning:

Warning: array_search() [function.array-search]: Wrong datatype for second argument in /home/oren/workspace/wordpress/wp-mu/wp-admin/includes/mu.php on line 498

When var_dumping $whitelist_options at that location, the 'blah' option group is missing. Since I don't access options.php directly I don't mind, but is there something else that is affected, or that i'm doing wrong?

@orensol Interesting, I haven't looked at options.php so I'm not sure what's going on in there. Sounds weird.

Without looking at the code, I'd guess that the add_option_update_handler() function doesn't get called properly, or doesn't create the option group. Maybe there's another filter that needs to be set to create the option group and populate it.

I'm just guessing though, don't have time to look into it right now. Let us know if you find a solution. :)

I've just created a new custom options page by creating a new PHP file in the wp-admin folder. The add_options_page() function wasn't an option, so instead I used something like this:

function blah_whitelist_options( $options ) {
	$options['blah'] = array('blah_option_1', 'blah_option_2', 'blah_option_3', 'blah_option_4');
	return $options;
}
add_filter('whitelist_options', 'psu_whitelist_options');

Then on the actual page (which could equally be a plugin page, not a physical file):

<form method="post" action="options.php">
<?php wp_nonce_field('blah-options'); ?>
<input type="hidden" name="option_page" value="blah" />
...
<input type="text" name="blah_option_1" value="<?php echo get_option('blah_option_1'); ?>" />
<input type="text" name="blah_option_2" value="<?php echo get_option('blah_option_2'); ?>" />
<input type="text" name="blah_option_3" value="<?php echo get_option('blah_option_3'); ?>" />
<input type="text" name="blah_option_4" value="<?php echo get_option('blah_option_4'); ?>" />
...
</form>

It's working like a charm. :)

chmac, thanks for sharing this whitelist_options filter route. It seems to be the easiest way to register multiple options without having to resort to something like a foreach looping many times add_option_update_handler()...

To render the aditionally required form fields automatically, the function settings_fields('blah'); can be used. It creates the option_page as well as nonce and other hidden fields in one go.