Classic Theme Anatomy and The Loop

A classic theme needs only style.css and index.php. Every other template file is optional: it is a more specific candidate in the template hierarchy, or a partial that templates include. The file names are fixed by WordPress, not by convention, so a misspelt name is silently ignored.

Source: Theme Handbook: Template Files

The lumen-classic theme built on this page has these files. style.css and functions.php are the ones shown in Themes Overview, unchanged: the setup function lumen_classic_setup declares title-tag, post-thumbnails and html5, and lumen_classic_enqueue_assets enqueues style.css under the handle lumen-classic-style.

Source: Theme Handbook: Organizing Theme Files

The book post type lp_book, its lp_genre taxonomy and the lp_isbn meta field come from the lumen-catalog plugin (see Custom Post Types and Taxonomies); the theme only displays them. A theme that registered them itself would lose the catalogue on a theme switch.

Templates do not repeat the document head and the site header; they include them. get_header( $name, $args ) loads header-{name}.php or else header.php; get_footer() and get_sidebar() work the same way, and get_template_part( $slug, $name, $args ) loads {slug}-{name}.php or else {slug}.php, firing the get_template_part_{slug} and get_template_part actions. get_search_form() loads searchform.php (else the core form) and comments_template() loads comments.php. All of them go through locate_template(), which looks for each candidate in the child theme, then the parent theme, then wp-includes/theme-compat/.

Source: Code Reference: get_template_part()

Three details matter in practice:

header.php opens the document and must call language_attributes(), wp_head(), body_class() and wp_body_open(). It ends by opening <main>, which footer.php closes:

Source: Theme Handbook: Template Files

There is no <title> and no stylesheet <link>: wp_head() prints both, from the title-tag support and the wp_enqueue_style() call in functions.php. The site name is an <h1> only on the front page.

Source: Code Reference: wp_footer()

Plugins and core output most of what a page needs through a handful of template functions. A theme that leaves one out breaks features that have nothing to do with the theme, usually without an error message.

Source: Code Reference: wp_head(), Code Reference: body_class()

body_class() gained wp-singular on singular views and wp-theme-{template} (plus wp-child-theme-{stylesheet}) in 6.8. Both functions accept extra classes, as in post_class( 'book' ) below, and have filters of the same name.

When a template file starts, the work of finding posts is already done. WP::main() parsed the URL into query variables and ran the main query, a WP_Query object stored in the global $wp_query, and the template loader then included the theme file. The Loop is the code that walks through the posts of that query:

Source: Theme Handbook: The Loop

index.php serves the blog index, pages (the theme has no page.php) and search results. get_post_type() picks content-page.php for a page; that file does not exist, so get_template_part() falls back to content.php. Templates use PHP’s alternative syntax (if … endif), see Control Structures.

The two functions do more than their names suggest. have_posts() and the_post() are wrappers around the same methods of $wp_query:

Template tags such as the_title() read the current post from these globals, which is why they take no post ID inside the Loop and why they print the wrong post when the globals are left pointing elsewhere (see Secondary loops).

Source: Code Reference: WP_Query, Code Reference: loop_no_results

Template tags are the functions templates call to print data about the current post, the site or the request. Most come in two forms: the_*() echoes the value, already filtered for display, and get_the_*() returns it. Use the get_ form when the value is processed or placed somewhere that needs its own escaping (an attribute, a JSON blob).

Source: Theme Handbook: Template Tags, Code Reference: the_title_attribute()

Most post tags also accept a post ID or object (get_the_title( 42 )), so code outside the Loop needs no globals.

Conditional tags answer questions about the current request (is_single(), is_archive(), is_search()) or the current post (has_post_thumbnail(), in_the_loop()). The request tags read the main query, so they only work once it has run: called earlier (for example in a plugin’s main file, before $wp_query exists) they return false and log "Conditional query tags do not work before the query is run". The wp action, template_redirect and the templates themselves are safe places.

The script below parses each path as a front-end request, in the same way index.php does, and prints the request tags that are true. It runs with wp eval-file against the test site of Rendering the theme, where Settings > Reading shows a static page ("Home") on the front page and the posts on "News".

Source: Theme Handbook: Conditional Tags

The output shows the distinctions that cause most template bugs:

Source: Code Reference: is_home(), Code Reference: is_front_page()

Other common ones are is_paged(), is_user_logged_in(), comments_open(), has_term() and in_the_loop(). Conditional tags select what to show; current_user_can() decides what a user may do.

A secondary loop lists posts other than those of the main query: related books, the latest news in a sidebar, a featured section. It creates its own WP_Query and calls the object’s methods, never the bare have_posts() and the_post(), which belong to the main query:

single.php above runs its secondary loop after the main Loop and takes the book’s ID from get_queried_object_id(), which reads the main query and is not affected by the globals. The script below shows what happens when a secondary loop runs inside the main one, before and after the reset:

Source: Code Reference: wp_reset_postdata()

Between the secondary loop and the reset, get_the_title() returns the last related book. The & in the title is the the_title filter at work: titles come back ready for HTML.

A secondary query should always set posts_per_page (the default is the Settings > Reading value, and -1 fetches everything), and 'no_found_rows' => true when it is not paginated, which skips the SQL_CALC_FOUND_ROWS count. 'ignore_sticky_posts' => true keeps sticky blog posts from being prepended to the list.

Source: Code Reference: WP_Query

get_posts() returns an array (with suppress_filters, ignore_sticky_posts and no_found_rows on by default); looping over it with template tags needs setup_postdata() per item and wp_reset_postdata() afterwards, while tags given a post argument (get_the_title( $book )) need neither. See WP_Query and the Database API.

A template is where data turns into HTML, so it is where it gets escaped. The rule in the WordPress coding standards is escape late: at the moment of output, with the function that matches the context, even for data that was sanitized when it was saved.

Source: Common APIs Handbook: Escaping Data

In the 7.1.3 source, the_permalink() applies esc_url() and bloginfo() applies esc_html (through the bloginfo filter), so both are safe as used above. the_title() is filtered but not escaped: titles may carry markup that wp_kses allowed for users without unfiltered_html, which is fine as text and wrong in an attribute. the_content() and the_excerpt() print HTML on purpose, since the content was filtered when it was saved. Post meta, options, request values and remote API data are never escaped by WordPress, hence esc_html( $lumen_isbn ).

Two template-specific traps remain. First, never pass request data to get_template_part() or locate_template(): the name becomes part of a file path. Since 7.1.2 locate_template() refuses candidates containing .. that resolve outside the theme and theme-compat folders (verified: locate_template( '../../../wp-config.php' ) returns an empty string and get_template_part() returns false), but an allow-list of names is still the correct design. Second, translated strings are data too: esc_html__() and esc_html_e() escape the translation, which a translator controls.

Source: WordPress 7.1.3: wp-includes/template.php

Escaping is checked automatically by the WordPress.Security.EscapeOutput sniff of the WordPress Coding Standards for PHP_CodeSniffer, which flags every unescaped echo; see Security for Developers.

The test site is the Compose stack of Template Hierarchy (MariaDB 11.8, the wordpress:7.1.3-php8.4-apache image answering as lumenpress.test, and a wordpress:cli-2.12.0-php8.4 container), with lumen-catalog and lumen-classic mounted read-only and the two scripts of this page mounted at /scripts. Inside the Compose network the site URL is http://lumenpress.test. The seed script installs WordPress, creates the canonical users, a static front page, a post and four books, and sets two posts per page so the pagination is visible:

Source: WP-CLI Commands: wp post create

Every file passed php -l under PHP 7.4 and 8.4; then one request of each kind was sent from the WP-CLI container:

Source: WP-CLI Commands: wp eval-file

Every path returned 200 except /no-such-page/ (404), and wp-content/debug.log stayed empty: no notice or deprecation from the theme. The body of the single book page (whitespace trimmed):

The <head> held the <title>The Glass Orchard – Lumen Press</title> printed by title-tag, the lumen-classic-style-css link and the canonical URL, all from wp_head(); the footer ended with the speculative loading rules and the emoji loader from wp_footer(). The /books/ archive printed two books and a <nav class="navigation pagination" aria-label="Posts pagination"> with links to page 2 and the custom "Older books" label. The front page printed the site name as an <h1>, a search for a missing word printed content-none.php with the core search form, and docker compose down -v removed the site.

The All-in-One For Dummies and Ultimate WordPress Handbook books do not cover template files or The Loop.

Security notes: templates run with the full privileges of WordPress, so the attack surface of a classic theme is its output. Escape every value at output, keep request data out of get_template_part() names and include paths, and keep secondary queries bounded with posts_per_page. The theme file editor should be disabled with DISALLOW_FILE_EDIT, as described in Security Hardening.