What does is_page_template() compare against?

Looking through the WordPress documentation, it says that is_page_template() compares against a “template name”, if one is provided.

I have a template stored in page-homepage.php called Homepage:

/*
 * Template Name: Homepage
 * Description: The template for displaying the homepage
 */

And I have some code I wish to run in my functions.php when I’m using that template:

if (is_page_template('Homepage')) { 
   ...

But it isn’t being triggered when I’m on a page which uses that template.

When I look at the code that WordPress executes for is_page_template(), it looks like it actually checks for the document name, not the template name…?

function is_page_template( $template = '' ) {

    $page_template = get_page_template_slug( get_queried_object_id() );

    if ( $template == $page_template )
        return true;

In my instance it seems that $page_template is page-homepage.php — not the template name, like the documentation suggests…?

Am I doing something wrong?

Answers:

Thank you for visiting the Q&A section on Magenaut. Please note that all the answers may not help you solve the issue immediately. So please treat them as advisements. If you found the post helpful (or not), leave a comment & I’ll get back to you as soon as possible.

Method 1

Your condition should be written like this:

if (is_page_template('path/file.php')) { 
    // Do stuff
}

I believe the confusion is a result of two things:

1. The docs refer to “name” ambiguously. Specifying “file name” would make the documentation much more clear.
2. The code behind is_page_template() shows the get_page_template_slug() function at its core. This function actually returns a file name, not the template slug. https://codex.wordpress.org/Function_Reference/get_page_template_slug

When specifying an argument for the is_page_template() function (as in the example above), the file path is relative to the theme root.

This function will not work inside the loop.

EDIT: an important issue to note here as well. The is_page_template() function will return empty/false if the page is using the default template from the hierarchy. If a custom template is not assigned, you must use another method, such as basename(get_page_template()). See Jacob’s answer here for more details: https://wordpress.stackexchange.com/a/328427/45202

Method 2

I think the best thing to say is, it checks on the FILE name and in your case it would be page-homepage.php. so:

if (is_page_template('page-homepage.php')) { 
  ...

Other things to think of is if the template file is actually stored within another folder inside the theme. read more

One more thing, the Template Name: Homepage is genrally whats used to identify the template when creating a page or post.

All methods was sourced from stackoverflow.com or stackexchange.com, is licensed under cc by-sa 2.5, cc by-sa 3.0 and cc by-sa 4.0