How to correctly use wp_enqueue_script and wp_enqueue_style in a WordPress child theme?

by

Summary

The developer attempted to add custom assets to a WordPress child theme by hardcoding links in header.php and later tried using functions.php. However, the provided code contains critical syntax errors that would trigger fatal PHP errors. The correct “WordPress way” involves using the wp_enqueue_scripts action hook with properly structured wp_enqueue_style() and wp_enqueue_script() calls inside a valid function. Additionally, file paths for child themes must utilize get_stylesheet_directory_uri() to ensure assets load from the child directory, not the parent.

Root Cause

The immediate failure stems from invalid PHP syntax and logic within the functions.php file.

  • Missing Parentheses and Scope: The function definition function my_theme_enqueue_assets() lacks the opening curly brace { to start the function scope and the closing parenthesis ) for the argument list.
  • Typo in Action Hook: The add_action call references my_theme_enqueue_as sets (with a space), which does not match the function name my_theme_enqueue_assets. This prevents WordPress from executing the function.
  • Incorrect Path Logic (Conceptual Root Cause): While the syntax kills the site, the logic uses get_template_directory_uri(). In a child theme context, this points to the parent theme’s folder. To load assets from the child theme, the developer must use get_stylesheet_directory_uri().

Why This Happens in Real Systems

WordPress development often involves rapid iteration, and developers frequently copy-paste snippets without strict adherence to PHP syntax rules.

  • Visual Similarity: get_template_directory_uri() and get_stylesheet_directory_uri() look nearly identical, leading to copy-paste errors.
  • Silent Failures on Typos: A typo in an action hook string (like the space in “as sets”) results in nothing loading without a specific PHP error, making the feature appear “broken” rather than “crashed.”
  • Hardcoding Habits: Developers moving from static HTML often attempt to inject <link> or <script> tags directly into template files because it feels familiar, bypassing the dependency management system WordPress provides.

Real-World Impact

Failing to implement asset loading correctly leads to three distinct categories of failure:

  • Site Crash (Syntax Error): The missing brace and parenthesis will trigger a 500 Internal Server Error on every page load, requiring immediate intervention via FTP/SFTP to fix the file.
  • Asset 404s (Path Error): If the syntax is fixed but the wrong directory function is used, the browser console will show 404 Not Found errors. The site may load, but functionality dependent on the JS/CSS will be broken.
  • Dependency Conflicts: If the developer hardcodes scripts or loads them without defining dependencies (like jQuery), it can lead to race conditions where JavaScript executes before the library is ready, causing console errors and unresponsive UI elements.

Example or Code

Below is the corrected code block for a child theme’s functions.php. This fixes the syntax errors, uses the correct child theme path function, and properly defines dependencies.

<?php
function my_theme_enqueue_assets() {
    // Use get_stylesheet_directory_uri() for child theme assets
    wp_enqueue_style(
        'my-main-style', 
        get_stylesheet_directory_uri() . '/style.css', 
        array(), 
        '1.0.0'
    );

    // Load script from child theme and explicitly depend on jquery
    wp_enqueue_script(
        'my-custom-js', 
        get_stylesheet_directory_uri() . '/js/custom-script.js', 
        array('jquery'), 
        '1.0.0', 
        true 
    );
}
add_action('wp_enqueue_scripts', 'my_theme_enqueue_assets');

How Senior Engineers Fix It

Senior engineers approach this by leveraging the framework’s architecture rather than fighting it.

  • Enforce Dependency Management: They explicitly list dependencies (e.g., array('jquery')) to ensure scripts load in the correct order, preventing race conditions.
  • Isolate Configuration: They often wrap enqueue functions in if ( ! function_exists( ... ) ) checks if the functionality might be copied to a plugin or elsewhere, preventing redeclaration errors.
  • Use Child Theme Constants: They strictly use get_stylesheet_directory_uri() for child themes to guarantee assets are served from the correct directory, regardless of whether the parent theme is active or switched later.

Why Juniors Miss It

Junior developers often miss these concepts because they are learning two languages (PHP and WordPress API) simultaneously.

  • Overlooking PHP Syntax: They focus on the WordPress function names but forget the strict PHP requirements like braces {} and semicolons ;.
  • Confusing Template vs. Stylesheet: The terms “Template” and “Stylesheet” in WordPress function names are counter-intuitive. Juniors often assume get_template_directory_uri() refers to “the file I am currently editing” rather than “the parent theme.”
  • Not Checking Browser Console: Juniors often look at the page (which might look fine if only the script is broken) rather than hitting F12 to see 404 errors or JS syntax errors caused by bad loading.