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:
- WordPress has a prewritten function that does what you want, like
register_post_type()
. - 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.
- 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:
- Setting the query criteria of
WP_Query
objects - Defining the properties of custom taxonomies in calls to
register_taxonomy()
- Setting custom post type properties in calls to
register_post_type()
- 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!
[…] WordPress Coding Patterns: Setting Function Options with $args […]
Love it, simple and useful explanation.
Great job Fred!
Thanks so much!
YES!!!
I have been calling this the
$args
pattern for years, and have been planning to blog about it as long. Really glad to see someone else finally put it into a post.