ClassicPress Plugin Development: Save an Options Page

This post is part of the ClassicPress Plugin Development series in which I am going to look at both best practice for developing plugins and how I approach some requirements as well as some of the functions I commonly use.

Once you have an options page created, you need to create the process to save the options when the user changes them.

The example I am using in this post is from my Remove Revisions plugin which uses a PHP namespace.

namespace azurecurve\RemoveRevisions;

The name of the function being used to save the options therefore does not need a prefix and is called save_options; if there was no namespace this would need vendor/plugin prefix and would be azrcrv_rr_save_options.

In the display_options function, the hidden input called action sets a value which is used by an ClassicPress action which is triggered by the click of the submit button:

<input type="hidden" name="action" value="azrcrv_rr_save_options" />

The action needs to be created using the add_action ClassicPress function:

add_action( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 )
Parameters
$tag (string) (Required) The name of the action to which the $function_to_add is hooked.

$function_to_add (callable) (Required) The name of the function you wish to be called.

$priority (int) (Optional) Used to specify the order in which the functions associated with a particular action are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.
Default value: 10

$accepted_args (int) (Optional) The number of arguments the function accepts.
Default value: 1
Return
(true) Will always return true.

In Remove Revisions, I only passed the first two parameters to add_action as I was happy to accept the defaults for the third and fourth. The $tag parameter is set to admin_post_ concatenated with the value of the hidden action input; the $function_to_add is the name of the save option function, which in this example is save_options.

However, as we are adding an action which takes place outside of the namepace, we need to prefix the function name with the namespace, which we can do using the namespace constant as shown below:

add_action('admin_post_azrcrv_rr_save_options', __NAMESPACE__.'\\save_options');

The code below is a copy of the save_options function from Remove Revisions plugin with the field handling removed. The submitted fields can be referenced using the standard PHP $_POST super global variable:

/**
 * Save settings.
 *
 * @since 1.0.0
 *
 */
function save_options(){

	// Check that user has proper security level
	if (!current_user_can('manage_options')){ wp_die(esc_html__('You do not have permissions to perform this action', 'remove-revisions')); }
	
	// Check that nonce field created in configuration form is present
	if (! empty($_POST) && check_admin_referer('azrcrv-rr', 'azrcrv-rr-nonce')){
	
		// Retrieve original plugin options array
		$options = get_option('azrcrv-rr');
		
		/*
			sanitize and prepare options
		*/
		
		// Store updated options array to database
		update_option('azrcrv-rr', $options);
		
		// Redirect the page to the configuration form that was processed
		wp_redirect(add_query_arg('page', 'azrcrv-rr&settings-updated', admin_url('admin.php')));
		exit;
	}
}

Two items to highlight from the above.

The first is the use of check_admin_referer to avoid security exploits; the passed parameters are declared in the display_options function within the form:

wp_nonce_field('azrcrv-rr', 'azrcrv-rr-nonce');