How can one use variables in a template or template part without polluting the global scope?

Question

I'm a developer who is relatively new to developing in PHP for WordPress, and I am working on a WordPress site that has a considerable amount of custom code in the site's theme. I have been enjoying using the WordPress Coding Standards tool, since it often makes me aware of PHP's gotchas and footguns.

One of the coding standards that seems to come up a lot is related to variable naming, which typically validate against three criteria:

1. Use $snake_case
2. Don't override WordPress global variables like $post and $id.
3. Prefix all global variables with $theme_name_ to have the effect of namespacing these variables to avoid conflicts with globals from WP or other packages.

In other languages I am more experienced with like JavaScript, I tend to code in a functional style, and avoid polluting global scope by using IIFEs.

What I've seen so far with template files and template parts in WordPress themes seems to suggest it is impossible not to pollute global scope, so I'm very curious to know if I'm unaware of a better practice, or otherwise missing something.

For example, again comparing with JavaScript, if I wanted to write a template file, I could do something like this:

export function template_html (args) {
  const title = args['title'];
  const subtitle = args['subtitle'];
  return `
<h1>${title}</h1>
<h2>${subtitle}</h2>
<p>Hello world</p>
`;
}

Whereas in WordPress, I have something like the following:

<?php
/**
 * This is a template file
 *
 * @package my-theme
 */

$my_theme_title = $args['title'];
$my_theme_subtitle = $args['subtitle'];
?>

<h1><?php echo esc_html( $my_theme_title ); ?></h1>
<h2><?php echo esc_html( $my_theme_subtitle ); ?></h2>
<p>Hello world</p>

Is this really as good as it gets? I am still learning PHP require semantics and it seems worrying that if you can't avoid populating the global variable scope, even if the tooling helps you avoid clobbering WP variables, you have no guarantees that you haven't reused your own namespaced global variable names across multiple files and could end up with initial values that you don't expect since they were populated in a different file, earlier in the require chain.

Answer 1

I feel there is a bit of confusion — let me try and clarify some key concepts.

A WordPress installation can potentially run huge amounts of 3rd party code. Code you can't control. That leads to a high chance of naming collisions. That's why WordPress coding standards suggest to "namespace" functions and variables declared in the global scope. If you're defining a variable inside your functions or templates (so, not in the global scope), there is no need to "namespace" it.

Regarding templates in particular, you probably already know that you can pass data to templates you load through get_template_part() and the likes.

Data passed this way is in no way global: it's only accessible to the template you're passing it to. From the link I shared above:

In the above example, the additional data passed to get_template_part() through the $args variable can be accessed within the foo.php template through the locally scoped $args variable.

In other words, you don't need to namespace your variables in your templates. This is perfectly fine:

<?php
/**
 * This is a template file
 *
 * @package my-theme
 */
?>

<h1><?php echo esc_html( $args['title'] ); ?></h1>
<h2><?php echo esc_html( $args['subtitle'] ); ?></h2>
<p>Hello world</p>