{"id":4505,"date":"2018-02-10T17:11:19","date_gmt":"2018-02-10T16:11:19","guid":{"rendered":"https:\/\/florianbrinkmann.com\/en\/?p=4505"},"modified":"2020-02-09T11:29:12","modified_gmt":"2020-02-09T10:29:12","slug":"validating-customize-settings-with-displaying-error-messages","status":"publish","type":"post","link":"https:\/\/florianbrinkmann.com\/en\/validating-customize-settings-with-displaying-error-messages-4505\/","title":{"rendered":"Validating customize settings with displaying error messages"},"content":{"rendered":"

Since WordPress 4.6 it is relatively simple to add validation to customize settings, to give helpful error messages to the user. Here I show you how that works.<\/p>\n\n\n\n\n\n\n\n

There are three ways to add validation:<\/p>\n\n\n\n

  1. By defining a validate_callback<\/code> when registering a setting.<\/li>
  2. By using the sanitize_callback<\/code> of a setting.<\/li>
  3. By creating a custom validate<\/code> method of the WP_Customize_Setting<\/code> class.<\/li><\/ol>\n\n\n\n

    This post describes the second way \u2013 you can find examples and more information about the topic in the post \u00bbCustomizer APIs in 4.6 for Setting Validation and Notifications<\/a>\u00ab by Weston Ruter.<\/p>\n\n\n\n

    That is, for example, the sanitize function for checking the value of a select field that contains all categories of the WordPress site:<\/p>\n\n\n

    \/**\n * Select sanitization callback for categories select control.\n *\n * @param<\/span> string $input Value of select field.\n *\n * @return<\/span> string\n *\/<\/span>\nfunction<\/span> hannover_sanitize_categories_select<\/span>( $input )<\/span> <\/span>{\n\t$can_validate = method_exists( 'WP_Customize_Setting'<\/span>, 'validate'<\/span> );\n\n\t$term = get_term( $input );\n\n\tif<\/span> ( 'category'<\/span> !== $term->taxonomy ||  is_wp_error( $term ) || null<\/span> === $term ) {\n\t\treturn<\/span> $can_validate ? new<\/span> WP_Error( 'nan'<\/span>, __( 'The ID does not match a category.'<\/span>, 'hannover'<\/span> ) ) : null<\/span>;\n\t}\n\n\treturn<\/span> $input;\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
    To display a specific error message, we can return a WP_Error<\/code> object to which we pass an error code as the first parameter and the error message as the second. However, this behavior does not work until WordPress 4.6, so we first check whether the validate<\/code> method of the WP_Customize_Setting<\/code> class exists.<\/p>\n\n\n\n
    Afterwards, we check if the input is a category and in case of an error we return either a specific error message (in WordPress 4.6 and later) or null<\/code> if we are dealing with an older version. In this case, the user would receive a general error message that the value is invalid. If everything is okay, we return the input value.<\/p>\n\n\n\n
    Displaying of the error message looks like that (takes a while after changing the value, while the preview refreshes):<\/p>\n\n\n\n