I am developing a plugin using Tom McFarlin’s Boilerplate repository as a template, which utilizes OOP practices. I’ve been trying to figure out exactly why I’m unable to correctly submit my settings. I’ve tried setting the action attribute to an empty string as suggested on another question around here, but that hasn’t helped…
Below is the general code setup I am using…
The Form (/views/admin.php):
<div class="wrap">
<h2><?php echo esc_html( get_admin_page_title() ); ?></h2>
<form action="options.php" method="post">
<?php
settings_fields( $this->plugin_slug );
do_settings_sections( $this->plugin_slug );
submit_button( 'Save Settings' );
?>
</form>
</div>
For the following code, assume all of the callbacks for add_settings_field() and add_settings_section() exist, except for ‘option_list_selection’.
The Plugin Admin Class(/{plugin_name}-class-admin.php):
namespace wp_plugin_name;
class Plugin_Name_Admin
{
/**
* Note: Some portions of the class code and method functions are missing for brevity
* Let me know if you need more information...
*/
private function __construct()
{
$plugin = Plugin_Name::get_instance();
$this->plugin_slug = $plugin->get_plugin_slug();
$this->friendly_name = $plugin->get_name(); // Get "Human Friendly" presentable name
// Adds all of the options for the administrative settings
add_action( 'admin_init', array( $this, 'plugin_options_init' ) );
// Add the options page and menu item
add_action( 'admin_menu', array( $this, 'add_plugin_admin_menu' ) );
}
public function add_plugin_admin_menu()
{
// Add an Options Page
$this->plugin_screen_hook_suffix =
add_options_page(
__( $this->friendly_name . " Options", $this->plugin_slug ),
__( $this->friendly_name, $this->plugin_slug ),
"manage_options",
$this->plugin_slug,
array( $this, "display_plugin_admin_page" )
);
}
public function display_plugin_admin_page()
{
include_once( 'views/admin.php' );
}
public function plugin_options_init()
{
// Update Settings
add_settings_section(
'maintenance',
'Maintenance',
array( $this, 'maintenance_section' ),
$this->plugin_slug
);
// Check Updates Option
register_setting(
'maintenance',
'plugin-name_check_updates',
'wp_plugin_name\validate_bool'
);
add_settings_field(
'check_updates',
'Should ' . $this->friendly_name . ' Check For Updates?',
array( $this, 'check_updates_field' ),
$this->plugin_slug,
'maintenance'
);
// Update Period Option
register_setting(
'maintenance',
'plugin-name_update_period',
'wp_plugin_name\validate_int'
);
add_settings_field(
'update_frequency',
'How Often Should ' . $this->friendly_name . ' Check for Updates?',
array( $this, 'update_frequency_field' ),
$this->plugin_slug,
'maintenance'
);
// Plugin Option Configurations
add_settings_section(
'category-option-list', 'Widget Options List',
array( $this, 'option_list_section' ),
$this->plugin_slug
);
}
}
Some Requested Updates:
Changing the action attribute to:
<form action="../../options.php" method="post">
…simply results in a 404 Error. The following below is the excerpt of the Apache Logs. Note that the default WordPress scripts and CSS en-queues are removed:
# Changed to ../../options.php
127.0.0.1 - - [01/Apr/2014:15:59:43 -0400] "GET /wp-admin/options-general.php?page=pluginname-widget HTTP/1.1" 200 18525
127.0.0.1 - - [01/Apr/2014:15:59:43 -0400] "GET /wp-content/plugins/PluginName/admin/assets/css/admin.css?ver=0.1.1 HTTP/1.1" 304 -
127.0.0.1 - - [01/Apr/2014:15:59:43 -0400] "GET /wp-content/plugins/PluginName/admin/assets/js/admin.js?ver=0.1.1 HTTP/1.1" 304 -
127.0.0.1 - - [01/Apr/2014:15:59:52 -0400] "POST /options.php HTTP/1.1" 404 1305
127.0.0.1 - - [01/Apr/2014:16:00:32 -0400] "POST /options.php HTTP/1.1" 404 1305
#Changed to options.php
127.0.0.1 - - [01/Apr/2014:16:00:35 -0400] "GET /wp-admin/options-general.php?page=pluginname-widget HTTP/1.1" 200 18519
127.0.0.1 - - [01/Apr/2014:16:00:35 -0400] "GET /wp-content/plugins/PluginName/admin/assets/css/admin.css?ver=0.1.1 HTTP/1.1" 304 -
127.0.0.1 - - [01/Apr/2014:16:00:35 -0400] "GET /wp-content/plugins/PluginName/admin/assets/js/admin.js?ver=0.1.1 HTTP/1.1" 304 -
127.0.0.1 - - [01/Apr/2014:16:00:38 -0400] "POST /wp-admin/options.php HTTP/1.1" 500 2958
Both the php-errors.log file and the debug.log file when WP_DEBUG is true are empty.
The Plugin Class (/{plugin-name}-class.php)
namespace wp_plugin_name;
class Plugin_Name
{
const VERSION = '1.1.2';
const TABLE_VERSION = 1;
const CHECK_UPDATE_DEFAULT = 1;
const UPDATE_PERIOD_DEFAULT = 604800;
protected $plugin_slug = 'pluginname-widget';
protected $friendly_name="PluginName Widget";
protected static $instance = null;
private function __construct()
{
// Load plugin text domain
add_action( 'init',
array(
$this,
'load_plugin_textdomain' ) );
// Activate plugin when new blog is added
add_action( 'wpmu_new_blog',
array(
$this,
'activate_new_site' ) );
// Load public-facing style sheet and JavaScript.
add_action( 'wp_enqueue_scripts',
array(
$this,
'enqueue_styles' ) );
add_action( 'wp_enqueue_scripts',
array(
$this,
'enqueue_scripts' ) );
/* Define custom functionality.
* Refer To http://codex.wordpress.org/Plugin_API#Hooks.2C_Actions_and_Filters
*/
}
public function get_plugin_slug()
{
return $this->plugin_slug;
}
public function get_name()
{
return $this->friendly_name;
}
public static function get_instance()
{
// If the single instance hasn't been set, set it now.
if ( null == self::$instance )
{
self::$instance = new self;
}
return self::$instance;
}
/**
* The member functions activate(), deactivate(), and update() are very similar.
* See the Boilerplate plugin for more details...
*
*/
private static function single_activate()
{
if ( !current_user_can( 'activate_plugins' ) )
return;
$plugin_request = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
check_admin_referer( "activate-plugin_$plugin_request" );
/**
* Test to see if this is a fresh installation
*/
if ( get_option( 'plugin-name_version' ) === false )
{
// Get the time as a Unix Timestamp, and add one week
$unix_time_utc = time() + Plugin_Name::UPDATE_PERIOD_DEFAULT;
add_option( 'plugin-name_version', Plugin_Name::VERSION );
add_option( 'plugin-name_check_updates',
Plugin_Name::CHECK_UPDATE_DEFAULT );
add_option( 'plugin-name_update_frequency',
Plugin_Name::UPDATE_PERIOD_DEFAULT );
add_option( 'plugin-name_next_check', $unix_time_utc );
// Create options table
table_update();
// Let user know PluginName was installed successfully
is_admin() && add_filter( 'gettext', 'finalization_message', 99, 3 );
}
else
{
// Let user know PluginName was activated successfully
is_admin() && add_filter( 'gettext', 'activate_message', 99, 3 );
}
}
private static function single_update()
{
if ( !current_user_can( 'activate_plugins' ) )
return;
$plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
check_admin_referer( "activate-plugin_{$plugin}" );
$cache_plugin_version = get_option( 'plugin-name_version' );
$cache_table_version = get_option( 'plugin-name_table_version' );
$cache_deferred_admin_notices = get_option( 'plugin-name_admin_messages',
array() );
/**
* Find out what version of our plugin we're running and compare it to our
* defined version here
*/
if ( $cache_plugin_version > self::VERSION )
{
$cache_deferred_admin_notices[] = array(
'error',
"You seem to be attempting to revert to an older version of " . $this->get_name() . ". Reverting via the update feature is not supported."
);
}
else if ( $cache_plugin_version === self::VERSION )
{
$cache_deferred_admin_notices[] = array(
'updated',
"You're already using the latest version of " . $this->get_name() . "!"
);
return;
}
/**
* If we can't determine what version the table is at, update it...
*/
if ( !is_int( $cache_table_version ) )
{
update_option( 'plugin-name_table_version', TABLE_VERSION );
table_update();
}
/**
* Otherwise, we'll just check if there's a needed update
*/
else if ( $cache_table_version < TABLE_VERSION )
{
table_update();
}
/**
* The table didn't need updating.
* Note we cannot update any other options because we cannot assume they are still
* the defaults for our plugin... ( unless we stored them in the db )
*/
}
private static function single_deactivate()
{
// Determine if the current user has the proper permissions
if ( !current_user_can( 'activate_plugins' ) )
return;
// Is there any request data?
$plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
// Check if the nonce was valid
check_admin_referer( "deactivate-plugin_{$plugin}" );
// We'll, technically the plugin isn't included when deactivated so...
// Do nothing
}
public function load_plugin_textdomain()
{
$domain = $this->plugin_slug;
$locale = apply_filters( 'plugin_locale', get_locale(), $domain );
load_textdomain( $domain,
trailingslashit( WP_LANG_DIR ) . $domain . "https://wordpress.stackexchange.com/" . $domain . '-' . $locale . '.mo' );
load_plugin_textdomain( $domain, FALSE,
basename( plugin_dir_path( dirname( __FILE__ ) ) ) . '/languages/' );
}
public function activate_message( $translated_text, $untranslated_text,
$domain )
{
$old = "Plugin <strong>activated</strong>.";
$new = FRIENDLY_NAME . " was <strong>successfully activated</strong> ";
if ( $untranslated_text === $old )
$translated_text = $new;
return $translated_text;
}
public function finalization_message( $translated_text, $untranslated_text,
$domain )
{
$old = "Plugin <strong>activated</strong>.";
$new = "Captain, The Core is stable and PluginName was <strong>successfully installed</strong> and ready for Warp speed";
if ( $untranslated_text === $old )
$translated_text = $new;
return $translated_text;
}
}
References:
-
The Settings API
- add_settings_section()
- add_settings_field()
- register_setting()
-
Creating Options Pages
“Error: Options Page Not Found” Bug
This is a known issue in the WP Settings API. There was a ticket opened years ago, and it was marked as solved — but the bug persists in the latest versions of WordPress. This is what the (now removed) Codex page said about this:
The “Error: options page not found.” problem (including a solution and
explanation):The problem then is, that the ‘whitelist_options’ filter
hasn’t got the right index for your data. It gets applied on
options.php#98 (WP 3.4).
register_settings()adds your data to the
global$new_whitelist_options. This then gets merged with the global
$whitelist_optionsinside theoption_update_filter()(resp.
add_option_whitelist()) callback(s). Those callbacks add your data to the global$new_whitelist_optionswith the$option_groupas index.
When you encounter “Error: options page not found.” it means your
index hasn’t been recognized. The misleading thing is that the first
argument is used as index and named$options_group, when the actual check in options.php#112 happens against$options_page, which is the$hook_suffix, which you get as @return value fromadd_submenu_page().In short, an easy solution is to make
$option_groupmatch$option_name. Another cause for this error is having an invalid value for$pageparameter when calling eitheradd_settings_section( $id, $title, $callback, $page )oradd_settings_field( $id, $title, $callback, $page, $section, $args ).Hint:
$pageshould match$menu_slugfrom Function Reference/add theme page.
Simple Fix
Using the custom page name (in your case: $this->plugin_slug) as your section id would get around the issue. However, all your options would have to be contained in a single section.
Solution
For a more robust solution, make these changes to your Plugin_Name_Admin class:
Add to constructor:
// Tracks new sections for whitelist_custom_options_page()
$this->page_sections = array();
// Must run after wp's `option_update_filter()`, so priority > 10
add_action( 'whitelist_options', array( $this, 'whitelist_custom_options_page' ),11 );
Add these methods:
// White-lists options on custom pages.
// Workaround for second issue: http://j.mp/Pk3UCF
public function whitelist_custom_options_page( $whitelist_options ){
// Custom options are mapped by section id; Re-map by page slug.
foreach($this->page_sections as $page => $sections ){
$whitelist_options[$page] = array();
foreach( $sections as $section )
if( !empty( $whitelist_options[$section] ) )
foreach( $whitelist_options[$section] as $option )
$whitelist_options[$page][] = $option;
}
return $whitelist_options;
}
// Wrapper for wp's `add_settings_section()` that tracks custom sections
private function add_settings_section( $id, $title, $cb, $page ){
add_settings_section( $id, $title, $cb, $page );
if( $id != $page ){
if( !isset($this->page_sections[$page]))
$this->page_sections[$page] = array();
$this->page_sections[$page][$id] = $id;
}
}
And change add_settings_section() calls to: $this->add_settings_section().
Other notes on your code
- Your form code is correct. Your form has to submit to options.php, as pointed out to me by @Chris_O, and as indicated in the WP Settings API documentation.
- Namespacing has it’s advantages, but it can make it more complex to debug, and lowers the compatibility of your code (requires PHP>=5.3, other plugins/themes that use autoloaders, etc). So if there is no good reason to namespace your file, don’t. You are already avoiding naming conflicts by wrapping your code in a class. Make your class names more specific, and bring your
validate()callbacks into the class as public methods. - Comparing your cited plugin boilerplate with your code, it looks like your code is actually based off a fork or an old version of the boilerplate. Even the filenames and paths are different. You could migrate your plugin to the latest version, but note that this plugin boilerplate may not be right for your needs. It makes use of singletons, which are generally discouraged. There are cases where the singleton pattern is sensible, but this should be conscious decision, not the goto solution.
