WordPress Coding Patterns: Setting Function Options with $args

Today’s topic is a pattern in WordPress programming called $args. It crops up all the time—so often that simply understanding it will make you a significantly more confident WordPress programmer. Let’s take a look!

$args Exists to Define Function Options

A very common pattern in WordPress is as follows:

1. WordPress has a prewritten function that does what you want, like register_post_type().
2. However, WordPress doesn’t know certain details of what you want. For example, does the post type have a special singular name? (If your post type is called “Phenomena,” the answer is yes!) Should posts of this post type show up in searches from your site’s search bar, or not? And so on.
3. So WordPress lets you fill in as many of these options as you want, as function parameters that will be passed to the main function (register_post_type()) itself.

Step three above is where $args comes in—$args is what will set all the custom function parameters that you want to dictate to WordPress.

This precisely why register_post_type() and many functions like it look something like this: register_post_type( $post_type, $args );.

$args is Everywhere!

To give you an idea how common the $args pattern is across WordPress development, here’s a very partial list of uses of it in tutorials we’ve written:

1. Setting the query criteria of WP_Query objects
2. Defining the properties of custom taxonomies in calls to register_taxonomy()
3. Setting custom post type properties in calls to register_post_type()
4. Defining the parameters of wp_remote_get() and other functions from WordPress’s HTTP API

You can get a fuller list by searching WPShout for “$args“—we counted at least a dozen distinct topics. You can also search the WordPress Codex for $args, and be there a while.

$args is an Associative Array

So $args is everywhere—but what is it?

The simplest answer is that it’s an associative array: a simple store of data that lists properties (keys) and the values those properties take (values). To make a pretend $args up on the spot, complete with a pretend WordPress function, here’s how it would look:

// This is $args, the associative array
$args = array(
	'title' => 'Great Big Miami Beach Sandcastle',
	'height_in_meters' => 3,
	'has_turrets' => true,
);

// This is the WordPress function that accepts $args as a parameter
wp_build_sandcastle( 'miami_beach', $args );

See how that works? $args is simply a listing of properties the WordPress function will understand—properties like title and height_in_meters—together with values for those properties, which can be strings like “Great Big Miami Beach Sandcastle,” booleans like true, or any other data type depending on the nature of that specific property.

A listing of these properties, structured as a PHP array, is $args in a nutshell.

You Don’t Have to Call it $args (But You Might As Well)

We call it $args by convention: it’s a good name, and consistent naming makes life easier.

Early on, it feels important to clarify that $args could be named anything, from $arguments to $a to $zzz—or even $boolean, if you’re into writing deliberately confusing variable names.

Why do we call it $args? By convention! $args is about as good a name as you’ll find for a variable that is essentially an array of function arguments—and calling it the same thing as other programmers makes it easier to know at a glance what those programmers are talking about.

This is similar to why so many of us call loop counter variables (in just about any language, from JavaScript to PHP to Java and beyond) by the name i. So don’t get stuck on the name $args—but you might as well keep in unless you’ve got a better one.

$args is Often Optional

Many WordPress function arguments have default values, and so $args itself is often optional.

Most WordPress function arguments have default values—sensible values that the function will use if you don’t specify a value of your own—and so $args itself is often optional.

wp_remote_get() is an example: it has default values for all variables in the way it makes its HTTP requests. As a result, you only need $args if you want to override one or more of those defaults, such as the request’s timeout time in seconds:

$args = array( 'timeout' => 30 );
$response = wp_remote_get( 'https://google.com', $args );

If you’re fine with the default timeout (of 5 seconds), as well as all the other defaults, then you can just leave $args off entirely:

$response = wp_remote_get( 'https://google.com' );

Creating an $args Variable is Good Practice, but Not a Necessity

$args is not a necessary piece of programming. Rather, it’s a convenience for cleaner, easier-to-read code.

Let’s go back to our first wp_remote_get() example. Why didn’t we simply write it as follows?

$response = wp_remote_get( 'http://www.google.com', array( 'timeout' => 30 ) );

The answer is: we could have! There’s nothing special about creating a variable called $args that references an array, and then passing that variable in as a function parameter; you can certainly just write the same array directly into the function call itself.

So why should we ever use $args? For a couple of reasons:

$args Makes for Cleaner Code

Let’s look at two ways of doing the same thing—in this case, registering a taxonomy called “Genre,” with several custom properties, for a custom post type called “book.” Here’s that process without $args:

register_taxonomy( 'genre', 'book', array( 'label' => __( 'Genre' ), 'public' => false, 'rewrite' => false, 'hierarchical' => true, ) );

And here’s the same code with $args:

$args = array(
	'label' => __( 'Genre' ),
	'public' => false,
	'rewrite' => false,
	'hierarchical' => true,
);

register_taxonomy( 'genre', 'book', $args );

Much better, right? It’s not only that the second example has indentation (after all, there’s nothing to stop us from adding indentation inside the call to register_taxonomy() itself): it’s also conceptually cleaner.

The first example says: “Register ‘genre.’ It’s for books. Also, let me also dump a bunch of stuff on you that I want to be true about ‘genre.'”

The second example says: “I’m going to list out a number of properties. Now let’s register ‘genre,’ for books, with the properties I just listed.”

So $args keeps your code looking clean, and it keeps your properties separate from the functions which use those properties. It’s better, easier to read, easier to wrangle-with code than writing arrays directly into your function calls.

$args Lets You Program Your Function Arguments

Still not convinced? Here’s another thing $args lets you do:

$args = array(
	'author_name' => 'fred',
	'post_type' => 'post',
);

if( is_search() ) {
	$args['post_type'] = array( 'post', 'page' );  
}

$query = new WP_Query($args);

The effect of the code above is to write a custom query that returns posts of type post by author fred—unless the current page is the site’s search page, in which case the query returns posts of type post or page by author fred.

You can’t do this if you’re writing arguments straight into your functions, so don’t bother trying. This is again a result of the cleaner code that $args lets you write: you set all your parameters out at the beginning—and if you want you can even do things with them—before you call the function that will use them. Cool, right?

Now You Get $args

Like understanding English words like “and” or “the,” understanding the nature of the $args pattern in WordPress development clarifies a whole lot all at once. I hope today’s article has made this pattern crystal-clear. As always, we’d love to hear your thoughts and questions in the comments below!