The WordPress settings API is there to “help authors manage their plugin custom options“, but does it? Many lengthy tutorials pointed to from the codex hints that the answer is probably “not really”. To quote Olly Benson from yet another settings API tutorial/example (emphasize mine)
WordPress does make a habit of creating mountains out of molehills sometimes, and the Settings API seems to be a fantastic example of this. Trying to follow the instructions on the initial page got me hopelessly lost, and it was only when I went through Otto’s WordPress Settings API tutorial that I begin to understand how to implement it.
And the problem is not with the codex, the problem is in the structure of the API itself. Instead of having a simple fast and dirty code like
add_action('admin_init','my_init');
function my_init() {
add_page('title','title',10,'my_options_page');
}
function my_options_page() {
if (isset($_POST['my_value'])) {
validate_value();
update_option('my_option',$_POST['my_value']);
}
<form>
Enter value <input type="text" name="my_value" value="<?echo get_option('my_option')?>
</form>
}
Where all the logic of handling the change of values is placed in the same place as the presentation, the my_options_page function, which makes it much easier to understand and debug.
The settings API basically moves your options handling away from your presentation code. To use it you need to call at least 3 initialization functions to which you have to supply 3 callback functions, and all the handling is done in a “black box” that doesn’t give you any hint for misconfiguration and it is hard to debug.
When trying to use the API I end spending more time to make myself feel good about following coding best practices then needed to code the same functionality in an equally accessible and secure way.