Theme Development Best Practices: Following WordPress Standards

By Krasen Slavov WordPress Theme Development

WordPress theme development best practices ensure code quality, security, and compatibility through coding standards, template organization, and performance optimization. From WPCS compliance and escaping output to accessibility requirements and translation readiness, professional themes follow established guidelines preventing common vulnerabilities and maintenance issues. This comprehensive guide teaches WordPress coding standards, security best practices, performance optimization, accessibility compliance, and theme review requirements creating maintainable production-ready themes.

WordPress Coding Standards

PHP Coding Standards:

<?php
/**
 * Theme Functions
 *
 * @package MyTheme
 */

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Setup theme defaults and register support for WordPress features.
 */
function mytheme_setup() {
    // Add theme support features.
    add_theme_support( 'title-tag' );
    add_theme_support( 'post-thumbnails' );
    add_theme_support( 'html5', array(
        'search-form',
        'comment-form',
        'comment-list',
        'gallery',
        'caption',
        'style',
        'script',
    ) );

    // Register navigation menus.
    register_nav_menus( array(
        'primary' => esc_html__( 'Primary Menu', 'mytheme' ),
    ) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

Key Standards:

  • Spaces, not tabs (4 spaces for indentation)
  • Yoda conditions: if ( true === $var )
  • Single quotes for strings unless interpolation needed
  • Braces on same line for control structures
  • Space after function name: function_name( $param )

Escaping Output

Always Escape Output:

<!-- Text -->
<?php echo esc_html( $text ); ?>
<?php echo esc_html__( 'Translatable text', 'mytheme' ); ?>

<!-- Attributes -->
<div class="<?php echo esc_attr( $class ); ?>">
<a href="<?php echo esc_url( $url ); ?>">

<!-- URLs -->
<?php echo esc_url( home_url( '/' ) ); ?>

<!-- HTML content (when intentional) -->
<?php echo wp_kses_post( $content ); ?>

<!-- JavaScript -->
<script>
var siteUrl = <?php echo wp_json_encode( home_url() ); ?>;
</script>

Common Escaping Functions:

  • esc_html() – Plain text
  • esc_attr() – Attributes
  • esc_url() – URLs
  • esc_js() – JavaScript strings
  • wp_kses_post() – HTML with allowed tags

Sanitizing Input

Sanitize All Input:

// Text fields
$text = sanitize_text_field( $_POST['user_input'] );

// Textarea
$textarea = sanitize_textarea_field( $_POST['description'] );

// Email
$email = sanitize_email( $_POST['email'] );

// URL
$url = esc_url_raw( $_POST['website'] );

// Integer
$number = absint( $_POST['count'] );

// HTML content
$content = wp_kses_post( $_POST['content'] );

// Checkboxes
$checkbox = isset( $_POST['option'] ) && '1' === $_POST['option'];

Nonce Verification

Always Verify Nonces for Forms:

// Create nonce
<form method="post">
    <?php wp_nonce_field( 'mytheme_action', 'mytheme_nonce' ); ?>
    <input type="text" name="user_field" />
    <input type="submit" value="Submit" />
</form>

// Verify nonce
if ( isset( $_POST['mytheme_nonce'] ) && wp_verify_nonce( $_POST['mytheme_nonce'], 'mytheme_action' ) ) {
    // Process form
    $user_input = sanitize_text_field( $_POST['user_field'] );
} else {
    wp_die( 'Security check failed' );
}

AJAX Nonces:

// Create nonce for AJAX
wp_localize_script( 'mytheme-ajax', 'mythemeAjax', array(
    'ajax_url' => admin_url( 'admin-ajax.php' ),
    'nonce'    => wp_create_nonce( 'mytheme_ajax_nonce' ),
) );

// Verify AJAX nonce
function mytheme_ajax_handler() {
    check_ajax_referer( 'mytheme_ajax_nonce', 'nonce' );

    // Process AJAX request
    $data = sanitize_text_field( $_POST['data'] );

    wp_send_json_success( array( 'message' => 'Success' ) );
}
add_action( 'wp_ajax_mytheme_action', 'mytheme_ajax_handler' );

Proper Enqueueing

Enqueue Scripts and Styles Correctly:

function mytheme_scripts() {
    // Enqueue stylesheet
    wp_enqueue_style(
        'mytheme-style',
        get_stylesheet_uri(),
        array(),
        wp_get_theme()->get( 'Version' )
    );

    // Enqueue custom CSS
    wp_enqueue_style(
        'mytheme-custom',
        get_template_directory_uri() . '/css/custom.css',
        array( 'mytheme-style' ),
        '1.0.0'
    );

    // Enqueue JavaScript with dependencies
    wp_enqueue_script(
        'mytheme-navigation',
        get_template_directory_uri() . '/js/navigation.js',
        array( 'jquery' ),
        '1.0.0',
        true // Load in footer
    );

    // Localize script for AJAX
    wp_localize_script(
        'mytheme-navigation',
        'mythemeData',
        array(
            'ajax_url' => admin_url( 'admin-ajax.php' ),
            'nonce'    => wp_create_nonce( 'mytheme_nonce' ),
        )
    );

    // Conditional loading
    if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
        wp_enqueue_script( 'comment-reply' );
    }
}
add_action( 'wp_enqueue_scripts', 'mytheme_scripts' );

Never Hardcode Assets:

<!-- BAD -->
<link rel="stylesheet" href="/wp-content/themes/mytheme/style.css">
<script src="/wp-content/themes/mytheme/js/script.js"></script>

<!-- GOOD -->
<?php wp_head(); ?> <!-- Enqueued styles/scripts output here -->

Translation Ready

Make All Strings Translatable:

// Simple string
__( 'Hello World', 'mytheme' );

// Echo string
_e( 'Hello World', 'mytheme' );

// With HTML escaping
esc_html__( 'Hello World', 'mytheme' );
esc_html_e( 'Hello World', 'mytheme' );

// Attribute escaping
esc_attr__( 'Hello World', 'mytheme' );
esc_attr_e( 'Hello World', 'mytheme' );

// Plurals
_n( '%s item', '%s items', $count, 'mytheme' );

// Context-specific
_x( 'Read', 'past tense', 'mytheme' );

Load Text Domain:

function mytheme_load_textdomain() {
    load_theme_textdomain( 'mytheme', get_template_directory() . '/languages' );
}
add_action( 'after_setup_theme', 'mytheme_load_textdomain' );

Template Organization

Proper File Structure:

mytheme/
├── style.css
├── functions.php
├── index.php
├── header.php
├── footer.php
├── sidebar.php
├── single.php
├── page.php
├── archive.php
├── search.php
├── 404.php
├── comments.php
├── template-parts/
│   ├── content.php
│   ├── content-page.php
│   └── content-none.php
├── inc/
│   ├── template-tags.php
│   └── template-functions.php
├── js/
│   └── navigation.js
├── css/
│   └── custom.css
└── languages/
    └── mytheme.pot

Use Template Parts:

// Include template part
get_template_part( 'template-parts/content', get_post_type() );

// With custom data
get_template_part( 'template-parts/content', 'page', array(
    'custom_data' => $data,
) );

Performance Best Practices

Optimize Database Queries:

// BAD - Multiple queries in loop
while ( have_posts() ) {
    the_post();
    $author = get_user_by( 'id', $post->post_author ); // Query per post
}

// GOOD - Single query before loop
$author_ids = wp_list_pluck( $posts, 'post_author' );
$authors = get_users( array( 'include' => array_unique( $author_ids ) ) );

while ( have_posts() ) {
    the_post();
    $author = $authors[ $post->post_author ];
}

Lazy Load Images:

// Add loading attribute to images
add_filter( 'wp_get_attachment_image_attributes', function( $attr ) {
    $attr['loading'] = 'lazy';
    return $attr;
} );

Limit Post Queries:

// Set default posts per page
function mytheme_posts_per_page( $query ) {
    if ( ! is_admin() && $query->is_main_query() && is_home() ) {
        $query->set( 'posts_per_page', 12 );
    }
}
add_action( 'pre_get_posts', 'mytheme_posts_per_page' );

Accessibility

Semantic HTML:

<!-- Proper heading hierarchy -->
<h1><?php the_title(); ?></h1>
<h2><?php _e( 'Related Posts', 'mytheme' ); ?></h2>

<!-- Skip links -->
<a class="skip-link screen-reader-text" href="#primary">
    <?php esc_html_e( 'Skip to content', 'mytheme' ); ?>
</a>

<!-- ARIA labels -->
<button class="menu-toggle" aria-controls="primary-menu" aria-expanded="false">
    <?php esc_html_e( 'Menu', 'mytheme' ); ?>
</button>

<!-- Alt text for images -->
<?php
if ( has_post_thumbnail() ) {
    the_post_thumbnail( 'large', array(
        'alt' => get_the_title(),
    ) );
}
?>

Keyboard Navigation:

/* Focus styles */
a:focus,
button:focus,
input:focus {
    outline: 2px solid #0073aa;
    outline-offset: 2px;
}

/* Skip link visible on focus */
.skip-link:focus {
    position: static;
    clip: auto;
    height: auto;
    width: auto;
}

Security Best Practices

Capability Checks:

// Check user capabilities
if ( current_user_can( 'edit_posts' ) ) {
    // Show edit link
    edit_post_link( __( 'Edit', 'mytheme' ) );
}

Direct File Access Prevention:

<?php
/**
 * Theme Functions
 */

// Prevent direct file access
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

// Rest of functions.php

SQL Injection Prevention:

global $wpdb;

// BAD - Direct variable in query
$results = $wpdb->get_results( "SELECT * FROM {$wpdb->posts} WHERE post_author = {$author_id}" );

// GOOD - Prepared statement
$results = $wpdb->get_results( $wpdb->prepare(
    "SELECT * FROM {$wpdb->posts} WHERE post_author = %d",
    $author_id
) );

Prefixing

Prefix All Functions and Variables:

// Function names
function mytheme_setup() {}

// Global variables
global $mytheme_options;

// Custom database tables
$wpdb->mytheme_custom_table

// Handles for scripts/styles
wp_enqueue_style( 'mytheme-style' );

// Hook names
do_action( 'mytheme_before_header' );

Theme Review Requirements

Required Features:

function mytheme_setup() {
    // Title tag (required)
    add_theme_support( 'title-tag' );

    // Automatic feed links (required)
    add_theme_support( 'automatic-feed-links' );

    // HTML5 support (recommended)
    add_theme_support( 'html5', array(
        'search-form',
        'comment-form',
        'comment-list',
        'gallery',
        'caption',
        'style',
        'script',
    ) );

    // Post thumbnails (recommended)
    add_theme_support( 'post-thumbnails' );

    // Custom logo (recommended)
    add_theme_support( 'custom-logo' );

    // Selective refresh (recommended)
    add_theme_support( 'customize-selective-refresh-widgets' );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

Prohibited:

  • No hardcoded links (except WordPress.org)
  • No analytics/tracking code
  • No advertisements
  • No encoded/obfuscated code
  • No external dependencies without user permission
  • No upselling in theme options

Testing

Use Theme Check Plugin:

Install Theme Check plugin to identify issues before submission.

Test With:

  • Fresh WordPress installation
  • Default content (Theme Unit Test)
  • Multiple browsers
  • Various screen sizes
  • Accessibility validators
  • PHP error reporting enabled

Enable Debugging:

// wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', true );

Conclusion

WordPress theme development best practices ensure quality through coding standards compliance, security measures, and accessibility requirements. Follow WPCS formatting guidelines, escape all output with esc_html/esc_attr/esc_url functions, sanitize user input preventing XSS vulnerabilities, implement proper script/style enqueueing, make themes translation-ready, and meet theme review requirements. Professional themes prioritize maintainability, performance, security, and user experience through established WordPress development standards.

  1. WordPress Coding Standards
  2. Theme Review Guidelines
  3. Data Validation
  4. Theme Check Plugin
  5. Accessibility Handbook

Call to Action

Professional themes need reliable backups. Backup Copilot Pro protects your WordPress theme files and development work automatically. Safeguard your code—start your free 30-day trial today!

Related Articles