WordPress Theme Requirements Part 4 - Coding

Summary: This article is the Coding requirements for WordPress Theme authors. This article is Part 4 of the requirements for WordPress Theme authors. WordPress is a large topic, so you will also need Parts 1 - 6 of the requirements below; 

- WordPress Theme Requirements Part 1 - General
- WordPress Requirements Part 2 -  Features
- WordPress Requirements Part 3 - Theme Plugins
- WordPress Requirements Part 4 - Coding  (you are here!)
- WordPress Requirements Part 5 - Theme Security 
- WordPress Requirements Part 6 - Gutenberg

If you are a Code author looking for more information on Wordpress Plugins to upload to a code category, please refer to the Plugin Requirements.

General Requirements

Prefixing

     Required Prefixes

     Third-Party Scripts

     Reserved Prefixes

Loading Files

     File Paths

     WordPress Assets

     Combining Scripts

     Font Loading

WordPress Code

PHP Code

      PHP Version

HTML/CSS Code

JavaScript Code

Translation Ready

General Requirements

Themes must not include unused code fragments (ie., commented out code), todo lists in comments, or any other comments that do not contribute to understanding the code.

Themes must not obfuscate or hide code in any way, including through the use of base64 encoding.

Prefixing

Required Prefixes

A unique prefix must be used for all function names, classes, hooks, public/global variables, action/filter hooks, custom image sizes, constants, database entries, theme-specific scripts and theme-specific styles to avoid conflicts with plugins and other themes.

Prefixes should consist of either themename_, authorname_ or frameworkname_. While multiple prefixes are allowed (theme-specific, framework and external PHP libraries), they must be consistent, at least three characters, and unique (ie not using a common term such as ‘seo’). For more information, refer to Prefix all the things article.  

Third-Party Scripts

Third-party scripts/styles must not be prefixed or suffixed to avoid double loading. For more reference, follow this github link.

Reserved Prefixes

The wp_ prefix is reserved for WordPress core functionality and must not be used by a theme. Prefixes must never begin with an underscore or hyphen.

Loading Files

File Paths

Hard-coded URIs must not be used when including or referencing files. The helper functions provided by WordPress should be used where possible.

Note: A fallback may be required for users on versions of WordPress prior to 4.7.

These functions should be used in preference to basename, dirname, pathinfo, etc.

For example, you should use:

include get_theme_file_path( '/includes/myscript.php' );

In preference to:

include dirname( __FILE__ ) . '/myscript.php';

For more information, refer to the following:

• File Path Example
• Backwards Compatibility/Fallback Example
• Further reading

WordPress Assets

Following are the requirements for WordPress assets:

• The wp_enqueue_style() function must be used to enqueue all stylesheets. For more information, refer to wp_enqueue_style().
  
• The wp_enqueue_script() function must be used to enqueue JavaScript code. For more information, refer to wp_enqueue_script().  
• Themes must use the scripts shipped with WordPress instead of including their own copy of the script or using one from a CDN. This includes jQuery, jQuery UI, Backbone, Underscore, etc. For more information, refer to the list of scripts included with WordPress.
• If a CDN version of a library is included (only allowed if not shipped with WordPress), a local copy must be provided as a fallback.
• All assets must be loaded using an SSL-friendly approach. Assets loaded from the theme directory must use get_template_directory_uri() or get_stylesheet_directory_uri() to build the URL. These functions will automatically use the appropriate protocol. For external assets, the theme must either use check is_ssl() and set the appropriate protocol prefix or use protocol-relative formats such as //example.com/file.js instead of http://example.com/file.js.

Strongly Recommended!

Themes should make sure that any scripts/stylesheets they use are only loaded on the pages that they are actually needed on. 

Combining Scripts

Third-party scripts and libraries must not be combined. They must be enqueued individually to ensure that:

• They are not loaded a second time by a plugin.
• Users can deregister scripts if required.

Font Loading

The @import rule must not be used when loading fonts, as this blocks parallel downloads and slows down the loading of the page. Instead, the fonts must be enqueued using wp_enqueue_style(). 

If using the Google Fonts library:

• The theme must only include variants that will actually be used, as seen in this example where only weight 700 of Inconsolata is loaded:
  

  fonts.googleapis.com/css?family=Inconsolata:700

• The theme must load multiple typefaces (if required) via a single HTTP request, using the pipe | operator, as seen in this example:
  

  fonts.googleapis.com/css?family=Lora:400,700|Inconsolata:700

• Here is an example of how to load fonts correctly.

Strongly Recommended!

The theme should not simply include a drop-down list of all Google Fonts in the options, as this can be confusing for users. Consider choosing a subset of font combinations that suit the design instead. 

WordPress Code

Following are the WordPress coding requirements:

• Deprecated template tags or functions are not allowed.
• The following functions must be present:
  
  • wp_head() - just before </head>
  • wp_footer() - just before </body>
  • body_class() - inside <body> or <html> tags
  • post_class()
• The theme must let WordPress add and manage the title. This is done by adding add_theme_support( 'title-tag' ); to functions.php instead of using wp_title() in the document head.
• If the theme includes custom template files, they must be called using get_template_part() or locate_template().
• WordPress theme files and directories must be named using lowercase letters. Words must be separated by hyphens, not camelCase or underscores. The theme filenames recognized by WordPress must be used where applicable.
• Themes must not add any entries to the admin bar and must not remove, hide, or otherwise block the admin bar from appearing.
• The $content_width variable must be used to define the maximum allowed width for images, videos, and oEmbeds displayed within a theme. This is set in functions.php, for an example, refer to this sample.
• Themes must not remove any filters added by WordPress core, for example, wpautop, wptexturize, etc.
• Default WordPress CSS classes must be covered in the stylesheet.
• WP_Filesystem methods must be used where available instead of direct PHP filesystem calls. For example, mkdir, fopen, fread, fwrite, fputs, etc., must not be used.

PHP Code

Note: It is strongly recommended that your themes follow the WordPress PHP Coding Standards.

Following are the PHP coding requirements:

• Themes must not have any PHP notices, warnings, or errors.
  
  Strongly Recommended!
  
  It is recommended that development is done with errors enabled and WP_DEBUG set to true.
• The create_function() function has been deprecated as of PHP 7.2.0 and must no longer be used.
• The "@" operator must not be used to suppress error messages or notices.
• The use of PHP short tags is not allowed.
• Tabs must be used for indentation, refer to the WordPress PHP Coding Standards.
• Themes must not include code to support PHP4. For example, themes must not use &$this when calling add_action. For more information, refer to this article. 
• PHP references (ie using &) must be avoided unless absolutely necessary. For more information, refer to Do not use PHP references.
• The creation of global variables is discouraged. They should be used only if absolutely necessary. If used, they must follow the prefixing rules.
• Single-statement inline control structures are prohibited. Either curly braces should be used (even where they are optional) or where appropriate the alternative syntax for control structures may be used.
  
  For example,
  
  

  Do not use:

  if ( empty( $somevar ) )
  return false;

  Instead use:

  if ( empty( $somevar ) ) {
    return false;
  }

  Or in the context of a template file or other predominantly HTML file, use:

  if ( empty( $somevar ) ) :
    return false;
  endif;

• The eval() function must not be used.

PHP Version

Themes must work with the latest release of PHP. There is no required minimum supported version of PHP, but:

• The decision on which versions to support should be made with the stats in mind.
• The requirements should be made clear to customers, so as to avoid dissatisfaction.

HTML/CSS Code

Note:  It is strongly recommended that your theme follows both the WordPress HTML Coding Standards and the WordPress CSS Coding Standards.

Following are the HTML/CSS coding requirements:

• CSS styling must not be hardcoded anywhere within a theme, either inline or in a <style> tag.
• Dynamic styling must be added via wp_add_inline_style() with the exception of adding a background image to an element. In this instance, the following would be permitted:
  

  <div id="header-background" style="background-image: url( <?php echo esc_url( 
  '$header-background' ); ?> );"></div>

  Any other styling for that element such as background-size: cover; must be added with wp_add_inline_style().
• Dynamic styling must be attached to the appropriate stylesheets in order to prevent loading CSS where it is not needed. For example, dynamic styling for WooCommerce must be attached to a woocommerce-inline-styles stylesheet rather than the main theme stylesheet.
• IDs and classes must be appropriately named and follow a naming convention.
• Selectors must be human readable and describe what elements are being styled.
• Overqualified selectors should not be used. For example, .container should be used instead of div.container. 
• When using CSS (or JavaScript) to manipulate elements, you must make sure that only your elements are affected. For example, when applying CSS to jQuery UI elements you’ve added to a page, you must make sure any jQuery UI elements that may be added by another item are not affected.

JavaScript Code

Note:  It is strongly recommended that your theme follow the WordPress JavaScript Coding Standards.

Following are the JavaScript coding requirements:

• JavaScript code must be placed in external files whenever possible.
• External JavaScript files must be enqueued correctly.
• If PHP variables or data need to be passed to JavaScript, wp_localize_script() must be used.
• JavaScript files must be loaded via the footer using the $in_footer parameter of wp_enqueue_script(), except where it must be in the head element for it to work.
• There must be no JavaScript notices or errors created.
• The use of eval() is not allowed.
• If using jQuery, then .on() must be used instead of .click(), .bind(), .hover(), etc.
• Strict mode must be used for all JavaScript. For example, for jQuery:

      (function($) {
          "use strict";
          // your code here
       })(jQuery);

• Redundant events must not be used. For example, there is no need for multiple $(document).ready() or $(window).load() events.
• Development and debugging code such as console.log() must be removed.

Translation Ready

Following are the WordPress Internationalization requirements: 

• Translatable Text: All theme text strings must be internationalized and properly escaped so that the theme can be translated and localized without parent theme modifications. For more information, refer to this Internationalization article.
• Translation Variables: Text strings must not contain variables or constants, as dynamic content is not translatable. Instead, use the printf family of functions with a placeholder or PHP argument swapping (for multiple variables). For more information, refer to Variables section in this Internationalization article.
• Text Domains: Constants, variables or definitions must not be used to define the theme’s text domain. The text domain must use dashes rather than underscores and be lowercase plain-text.

  Strongly Recommended!
  
  It is recommended that the text domain match the theme’s slug to help ensure uniqueness. For more information, refer to Internationalization article.

• Irrelevant Text Domains: Text domains that are unrelated to the theme are not allowed and must be removed. Packaged PHP libraries (i.e. TGMPA), frameworks and plugin template text domains are relevant and therefore allowed. 
• Translation File: The localization file should be in English and delivered as a .pot file. The .pot will contain all translation strings. The .pot file name should match the theme-slug (i.e. themeslug.pot).
  • Themes can include actual translation files (.po/.mo) for any variety of specific languages, but must not add the en_US.mo or en_US.po because English is already implied.
  • Ensure the .POT translation file is up-to-date. Having an outdated .POT file limits the translatable functionality of the theme, which will negatively affect international customers.

  Strongly Recommended!
  
  Right To Left (RTL) Support: It is recommended that you add support to your theme for languages that are read from right to left (RTL). This is relatively easy to do and makes your theme appealing to wide range of customers. For more information, refer to RTL support in themes article.