{"id":1241,"date":"2009-05-05T12:50:54","date_gmt":"2009-05-05T10:50:54","guid":{"rendered":"http:\/\/planetozh.com\/blog\/?p=1241"},"modified":"2009-05-05T12:55:31","modified_gmt":"2009-05-05T10:55:31","slug":"handling-plugins-options-in-wordpress-28-with-register_setting","status":"publish","type":"post","link":"https:\/\/planetozh.com\/blog\/2009\/05\/handling-plugins-options-in-wordpress-28-with-register_setting\/","title":{"rendered":"Handling Plugins Options in WordPress 2.8 with register_setting()"},"content":{"rendered":"

In the upcoming WordPress 2.8 there's an interesting function set meant to help authors manage their plugin custom options. In a nutshell: whitelist your options, define how you want them to be validated, and just lean back and rely on the API to handle everything for you.<\/p>\n

Your new best friend is function register_setting()<\/tt>, and I'm going to recapitulate how it's supposed to be used.
\n<\/p>\n

The (very) old (deprecated) way (that sucks)<\/h2>\n

If you began coding plugin a long time ago, you may have sticked to the habit of doing everything yourself, re-inventing and re-coding the wheel everytime.<\/p>\n

Does something like checking for $_POST on your plugin admin page ring a bell? Time to evolve to a hassle free way of coding stuff.<\/p>\n

The (new) register_setting() way (that pwnz)<\/h2>\n

The concept is the following: do the little tasks, let WordPress manage the dirty job.<\/p>\n

– on init, tell WordPress that you're going to use some new options
\n– optional but cool, tell WordPress what function you'd like to be used for data validation (the user is supposed to enter text on your plugin admin page? Make sure it's only text, then)
\n– optional but cool, store all your options in one DB entry (yeah, those who've been reading this blog for a while know that it's my favorite pet peeve)
\n– don't handle POST data, let WordPress do it
\n– don't update\/create the DB entry in the options, let WordPress do it
\n– don't bother with all the security, nonces, anti XSS stuff you have to throw in, let WordPress do it<\/p>\n

Code, dissected<\/h2>\n

First, tell WordPress that you're going to use new options<\/p>\n

\n\n\t\t
\n\n\t\t
\n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
php<\/div>\n\n\t\t\n\t\t
\n\n\t<\/div>\n\t\n\t
\n\t\t
  1. add_action('admin_init', 'ozh_sampleoptions_init' );<\/div><\/li>\n
  2. function ozh_sampleoptions_init(){<\/div><\/li>\n
  3.     register_setting( 'ozh_sampleoptions_options', 'ozh_sample' );<\/div><\/li>\n
  4. }<\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

    This function says: I'm going to need a new set of options, named 'ozh_sampleoptions_options', it will be stored in the DB entry 'ozh_sample'. There can a third parameter, a callback function to sanitize data: we'll see this later.<\/p>\n

    Then, we need to draw the plugin option page itself. Nothing really new here, except just one new thing. The function that echoes the admin form would be something like:<\/p>\n

    \n\n\t\t
    \n\n\t\t
    \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
    php<\/div>\n\n\t\t\n\t\t
    \n\n\t<\/div>\n\t\n\t
    \n\t\t
    1. \/\/ Draw the menu page itself<\/div><\/li>\n
    2. function ozh_sampleoptions_do_page() {<\/div><\/li>\n
    3.     ?><\/div><\/li>\n
    4.     <div class="wrap"><\/div><\/li>\n
    5.         <h2>Ozh's Sample Options<\/h2><\/div><\/li>\n
    6.         <form method="post" action="options.php"><\/div><\/li>\n
    7.             <?php<\/span> settings_fields(<\/span>'ozh_sampleoptions_options'<\/span>)<\/span>;<\/span> ?><\/span><\/div><\/li>\n
    8.             <?php<\/span> $options<\/span> =<\/span> get_option(<\/span>'ozh_sample'<\/span>)<\/span>;<\/span> ?><\/span><\/div><\/li>\n
    9.             <table class="form-table"><\/div><\/li>\n
    10.                 <tr valign="top"><th scope="row">A Checkbox<\/th><\/div><\/li>\n
    11.                     <td><input name="ozh_sample&#91;option1&#93;" type="checkbox" value="1" <?php<\/span> checked(<\/span>'1'<\/span>,<\/span> $options<\/span>&<\/span>#91;'option1'&#93;); <\/span>?><\/span> \/><\/td><\/div><\/li>\n
    12.                 <\/tr><\/div><\/li>\n
    13.                 <tr valign="top"><th scope="row">Some text<\/th><\/div><\/li>\n
    14.                     <td><input type="text" name="ozh_sample&#91;sometext&#93;" value="<?php<\/span> echo<\/span> $options<\/span>&<\/span>#91;'sometext'&#93;; <\/span>?><\/span>" \/><\/td><\/div><\/li>\n
    15.                 <\/tr><\/div><\/li>\n
    16.             <\/table><\/div><\/li>\n
    17.             <p class="submit"><\/div><\/li>\n
    18.             <input type="submit" class="button-primary" value="<?php<\/span> _e(<\/span>'Save Changes'<\/span>)<\/span> ?><\/span>" \/><\/div><\/li>\n
    19.             <\/p><\/div><\/li>\n
    20.         <\/form><\/div><\/li>\n
    21.     <\/div><\/div><\/li>\n
    22.     <?php<\/span>   <\/div><\/li>\n
    23. }<\/span><\/div><\/li>\n
    24. &<\/span>#91;\/php&#93;<\/span><\/div><\/li>\n
    25.  <\/div><\/li>\n
    26. Notice the <<\/span>tt><\/span>settings_fields(<\/span>)<\/span><\/<\/span>tt><\/span> call.<\/span> This tells WordPress to add all the hidden fields our form needs (<\/span>nonce,<\/span> referrer check...<\/span>)<\/span>,<\/span> and that we're going to use our option set previously defined as '<\/span>ozh_sampleoptions_options'.<\/span><\/div><\/li>\n
    27.  <\/div><\/li>\n
    28. And that'<\/span>s all,<\/span> basically.<\/span> You don't need to check if user submits the form, to check whether the options need to be updated or not, to handle things passed to $_POST. WordPress takes care of it.<\/span><\/div><\/li>\n
    29.  <\/div><\/li>\n
    30.  <\/div><\/li>\n
    31. <h2>Data sanitization<\/h2><\/span><\/div><\/li>\n
    32.  <\/div><\/li>\n
    33. Function <tt>register_setting()<\/tt> accepts 3 parameters: the option group name, the option name to save and sanitize, and a callback function that does the sanitization.<\/span><\/div><\/li>\n
    34.  <\/div><\/li>\n
    35. If you want the user to submit integers, and only integers (say, they age), you would for instance use:<\/span><\/div><\/li>\n
    36. [php]<\/span><\/div><\/li>\n
    37. register_setting( '<\/span>my_options', '<\/span>your_age', '<\/span>intval<\/span>' );<\/span><\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

      If you're allowing safe text with a limited set of HTML tags:<\/p>\n

      \n\n\t\t
      \n\n\t\t
      \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
      php<\/div>\n\n\t\t\n\t\t
      \n\n\t<\/div>\n\t\n\t
      \n\t\t
      1. register_setting( 'my_options', 'your_bio', 'wp_filter_nohtml_kses' );<\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

        Now, in the previous example, since we want to store everything in a single DB entry, we'll define our own validation function:<\/p>\n

        \n\n\t\t
        \n\n\t\t
        \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
        php<\/div>\n\n\t\t\n\t\t
        \n\n\t<\/div>\n\t\n\t
        \n\t\t
        1. function ozh_sampleoptions_init(){<\/div><\/li>\n
        2.     register_setting( 'ozh_sampleoptions_options', 'ozh_sample', 'ozh_sampleoptions_validate' );<\/div><\/li>\n
        3. }<\/div><\/li>\n
        4.  <\/div><\/li>\n
        5. \/\/ Sanitize and validate input. Accepts an array, return a sanitized array.<\/div><\/li>\n
        6. function ozh_sampleoptions_validate($input) {<\/div><\/li>\n
        7.     \/\/ Our first value is either 0 or 1<\/div><\/li>\n
        8.     $input['option1'] = ( $input['option1'] == 1 ? 1 : 0 );<\/div><\/li>\n
        9.     <\/div><\/li>\n
        10.     \/\/ Say our second option must be safe text with no HTML tags<\/div><\/li>\n
        11.     $input['sometext'] =  wp_filter_nohtml_kses($input['sometext']);<\/div><\/li>\n
        12.     <\/div><\/li>\n
        13.     return $input;<\/div><\/li>\n
        14. }<\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

          All wrapped up<\/h2>\n

          For your convenience, you'll find all the code of this article in the following plugin: ozh-sampleoptions-plugin.php<\/a> (rename as .php)<\/p>\n

          Happy coding!<\/p>\n","protected":false},"excerpt":{"rendered":"

          In the upcoming WordPress 2.8 there's an interesting function set meant to help authors manage their plugin custom options. In a nutshell: whitelist your options, define how you want them to be validated, and just lean back and rely on the API to handle everything for you. Your new best friend is function register_setting(), and I'm going to recapitulate how\u2026<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[21],"tags":[2,85,353,245],"class_list":["post-1241","post","type-post","status-publish","format-standard","hentry","category-published","tag-code","tag-plugins","tag-register_setting","tag-wordpress"],"_links":{"self":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/posts\/1241","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/comments?post=1241"}],"version-history":[{"count":0,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/posts\/1241\/revisions"}],"wp:attachment":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/media?parent=1241"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/categories?post=1241"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/tags?post=1241"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}