WordPress_AbstractThemeSniff

[khacoder]

[New Class] Create WordPress_AbstractThemeSniff Class

Create new theme sniff class that will create a $sniff_helper array that will be accessible by other sniffs during a theme check.
Replaces issue #43 New Theme Sniff Class

The purpose of the class is :

• To pull theme data from style.css to be accessed by other sniffs created for WordPress theme review.
• Do a once through of theme files to provide a array of switches used to satisfy checks that require a complete review of files before a positive or negative decision can be made.
• Conduct sniffs/checks that can't be done during a standard Code Sniffer run. Typically these are checks not associated with any file.
• Display results in a similar format to Code Sniffer report.

The class essentially allows integration of checks that can't be properly done with a file-token-sniff approach.

Array Content

$sniff_helper = array(
    'theme_data' => array(
        'name'        => '',
        'uri'         => '',
        'author'      => '',
        'author_uri'  => '',
        'description' => '',
        'version'     => '',
        'license'     => '',
        'license_uri' => '',
        'tags'        => '',
        'text_domain' => '',
    ),
    'theme_supports' => array(
        'custom-header' => false,
        'custom-background' => false,
        'custom-logo' => false,
        'post-formats' => false,
        'featured-images' => false,
        'featured-image-header' => false,
        'custom-menu' => false,
    ),
    'comment_reply' => array(
        'enqueued' => false,
        'comment_reply_term' => false,
    ),
    'comments_pagination' => false,
    'content_width' => false,
    'add_editor_style' => false,
    'avatar_check' => false,
    'custom_menu_support' => false,
    'post_pagination' => false,
    'post_format_support' => false,
    'post_thumbnail_support' => false,
    'post_tags_support' => false,
    'title_tag' => array(
        'theme_support' => false,
        'wp_title' => false,
    ),
    'sidebar_support' => array(
        'register_sidebar_used' => false,
        'dynamic_sidebar_used' => false,
        'widgets_init_used' => false,
    ),
    'basic_function_calls' => array(
        'wp_footer' => false,
        'wp_head' => false,
        'language_attributes' => false,
        'charset' => false,
        'automatic_feed_links' => false,
        'comments_template' => false,
        'wp_list_comments' => false,
        'comment_form' => false,
        'body_class' => false,
        'wp_link_pages' => false,
        'post_class' => false,
    ),
    'doctype' => false,
    'index_file_used' => false,
    'style_file_used' => false,
    'readme_file_used' => false,
    'screenshot' => array(
        'found' => false,
        'less_than_1200_wide' => false,
        'less_than_900_high' => false,
        'aspect_ratio_4_by_3' => false,
        'details_not_found' => false,
    ),
    'css_required' => array(
        'sticky' => false,
        'bypostauthor' => false,
        'alignleft' => false,
        'alignright' => false,
        'aligncenter' => false,
        'wp-caption' => false,
        'wp-caption-text' => false,
        'gallery-caption' => false,
        'screen-reader-text' => false,
    ),
);

Checks done in the Class

The following theme checks that require a once through are included in the class.
From WordPress/WordPress-Coding-Standards#578

Rules which can probably be turned into a sniff but would need to be run against every file before a positive/negative result can be determined:

ERROR | Verify that an add_theme_support() call is made for any feature the theme has been tagged with from the following list: custom-background, custom-header, custom-menu, featured-images/post-thumbnails, post-formats, custom-logo
ERROR | Check that the comment reply script is being enqueued (comments should always be supported by themes).
ERROR | Check that the comment_reply string or rather any HTML identifiers needed for the JS script to work are present (need more info) (comments should always be supported by themes, enqueuing the script alone is not enough)
ERROR | Check that comment pagination is supported. At least one of the following functions would need to be found in at least one of the template files, fail if none are found at all. paginate_comments_links(), the_comments_navigation(), the_comments_pagination(), next_comments_link() or previous_comments_link()
ERROR | Check that - normally in functions.php, but could be in another file - the global variable $content_width is set, so either in the global namespace using $content_width or within a function using global $content_width; $content_width =... or $GLOBALS['content_width']. Note: currently the Theme Check plugin also checks for filters on embed_defaults and content_width and passes if those are found. Those checks are outdated and should not be ported.
ERROR | Verify that an add_editor_style() call is made if the theme has been tagged with editor-style.
ERROR | Verify that get_avatar() or wp_list_comments() is used at least once.
WARNING | Verify that there are max one link each to the author's website and one link to wordpress.org in front-end visitor facing template, e.g. footer.php or similar.
WARNING | Verify that (register|wp)_nav_menu() is used at least once. This should become an error if the theme is tagged with custom-menu.
ERROR | Verify that (get_post_format()|has_format() or CSS rules covering .format are found, at least once if the theme has a add_theme_support( 'post-format' ) call. This should become an error if the theme is tagged with post-formats.
ERROR | Check that post pagination is supported. At least one of the following functions would need to be found in at least one of the template files, fail if none are found at all. posts_nav_link(), paginate_links(), the_posts_navigation(), the_posts_pagination(), next_posts_link() or previous_posts_link()
ERROR | Verify that the_post_thumbnail()is found at least once if the theme has a add_theme_support( 'post-thumbnails' ) call. This should become an error if the theme is tagged with featured-image.
ERROR | Check if a number of specific CSS identifiers have been given styles in any of the CSS files. See Theme-Check plugin - /checks/style_needed.php for the list.
ERROR | Check that post tags are supported in the theme. At least one of the following functions would need to be found in at least one of the template files, fail if none are found at all. the_tags(), get_the_tag_list(), get_the_term_list()
ERROR | Check that add_theme_support( 'title-tag' ) is used in at least one file.
WARNING | Check if at least one call to register_sidebar() or dynamic_sidebar() is made.
ERROR | If a call to register_sidebar() is found, make sure there is at least one call to dynamic_sidebar() as well and visa versa.
ERROR | Check that the register_sidebar() function is called with an add_action( 'widget_init', ... ) call.
ERROR | Check for a number of function calls which each theme has to contain. See Theme-Check plugin - /checks/basic.php for the list.
ERROR | Check that the theme contains a DOCTYPE headers somewhere.

Rules which would need another solution (like in the bootstrap file which would run PHPCS from the Theme-check plugin within an install):

WARNING | Have a default (always on) INFO item which will warn people not to use their own functions for features which should be supported through add_theme_support().
ERROR | Check that at the very least the following two files exist: index.php and style.css.
WARNING | Check that a readme.txt file exists.
ERROR | Check that at least one screenshot is found.
ERROR | Check that the screenshot is either a jpg or png.
ERROR | Check that the screenshot is smaller than 1200x900, has a 4:3 size ratio.
WARNING | Recommend a screenshot size of 1200 x 900 if the screenshot is smaller.

As we continue to push towards more automated theme checks, this class offers a way to add checks that do not conform to the file->token->sniff approach.

Sniffs that need the $sniff_helper array, should set up the class with extends WordPress_Abstract_ThemeSniff.

The array is a global array so to access in your sniff, simply add 'global $sniff_helper' to your process function.

Issues:
Conventional testing of sniffs that use this class is not possible because style.css will be required in addition to a test file.
This class does not run if a single file is being checked. It is designed for a theme check of all theme files.

This class has been designed and has been initially tested.
I can create a pull request if the group feels it is worth pursuing.

To do:

• develop and add Class
• test Class with a sniff that uses theme data