Managing a variety of content types within a WordPress website is a routine task developers come across. Each content type – whether it be a post, attachment, page, or even a custom post type – has its moment of prominence on–and off-stage as dictated by user interactions. Then comes in the ‘is_singular’ function that truly shines as our behind-the-scenes maestro conducting this interactive symphony.
Hold on to the thought of running a news website, with varied content types including articles, videos, podcasts, and photo galleries. At any moment, you’ll need to sift through this content to present the most relevant piece to the readers. That’s where our ‘is_singular’ function works quietly but efficiently, checking whether the request is for a single, unique piece of content, and enabling you to serve your audience precisely what they’re looking for. Understanding it better will truly empower the way you manage diverse content in WordPress.
Syntax
| is_singular( $post_types = '' ) |
Parameters
$post_types(optional): A string or an array of post types to check against. Defaults to an empty string.
Return Value
trueif the query is for an existing single post or any of the given post types.falseif the query is not for a single post or any of the given post types.
How it Works
| <?php | |
| /** | |
| * Determines whether the query is for an existing single post of any post type | |
| * (post, attachment, page, custom post types). | |
| * | |
| * If the $post_types parameter is specified, this function will additionally | |
| * check if the query is for one of the Posts Types specified. | |
| * | |
| * For more information on this and similar theme functions, check out | |
| * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ | |
| * Conditional Tags} article in the Theme Developer Handbook. | |
| * | |
| * @since 1.5.0 | |
| * | |
| * @see is_page() | |
| * @see is_single() | |
| * @global WP_Query $wp_query WordPress Query object. | |
| * | |
| * @param string|string[] $post_types Optional. Post type or array of post types | |
| * to check against. Default empty. | |
| * @return bool Whether the query is for an existing single post | |
| * or any of the given post types. | |
| */ | |
| function is_singular( $post_types = '' ) { | |
| global $wp_query; | |
| if ( ! isset( $wp_query ) ) { | |
| _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' ); | |
| return false; | |
| } | |
| return $wp_query->is_singular( $post_types ); | |
| } |
The is_singular() function is used to determine whether the current WordPress query is for an existing single post of any post type (such as posts, attachments, pages, or custom post types).
Additionally, it can also check if the query is for one of the specified post types by passing them as arguments in the $post_types parameter.
To use this function, you need access to the global $wp_query object, which is automatically available in WordPress.
Before checking whether the query is for a single post, this function first checks if the $wp_query object has been set. If it hasn’t been set yet, it means that the conditional query tags do not work before the query itself is executed. In such cases, this function will return false and notify about this issue using _doing_it_wrong().
If everything works fine and is_singular() is called after the query has been run, it simply forwards to another method: $wp_query->is_singular(). This method checks if either no post type was specified (which means it should return true for any single entity) or if the queried object matches one of the specified post types in $post_types.
Overall, is_singular() provides a handy way to determine whether a certain query matches a singular entity like a single blog post or page based on their specific conditions and requirements.
Usage
The is_singular() function is used to determine whether the current query is for an existing single post of any post type (post, attachment, page, custom post types).
Inside a Plugin
Suppose you are developing a plugin that adds custom functionality related to single posts. You want to check if the current query is for a single post of the “book” post type before executing your plugin’s code.
| <?php | |
| // Add your plugin's functionality only if the query is for a single book post | |
| function my_plugin_function() | |
| { | |
| if (is_singular('book')) | |
| { | |
| // Your plugin code here | |
| } | |
| } | |
| add_action('wp', 'my_plugin_function'); |
In this example:
- You define your plugin’s functionality inside the
my_plugin_function()function. - The
is_singular( 'book' )condition checks if the current query is for a single post of the “book” post type. - If the condition evaluates to
true, your plugin code will be executed.
By using the is_singular() function within your plugin, you can ensure that your code runs only on single posts of the specified post type.
Inside a Theme
Suppose you are developing a custom theme and want to display additional information on single blog posts and pages. You can use the is_singular() function to conditionally render this information only on single posts or pages.
| <?php | |
| // Display additional information on single blog posts and pages | |
| function my_theme_additional_info() | |
| { | |
| if (is_singular(array( | |
| 'post', | |
| 'page' | |
| ))) | |
| { | |
| // Render additional information here | |
| } | |
| } | |
| add_action('template_redirect', 'my_theme_additional_info'); |
In this example:
- The
my_theme_additional_info()function contains the code to display additional information. - The
is_singular( array( 'post', 'page' ) )condition checks if the current query is for a single post of the “post” or “page” post types. - If the condition evaluates to
true, the additional information will be rendered on the single blog posts and pages.
By using the is_singular() function within your theme, you can customize the display of content based on whether the current query is for a single post or page.
