How To Add A Custom PHP Page To WordPress Using A Plugin

Most guides on how to add a custom PHP page in WordPress will explain how to do it using a template in a theme, but this is a restrictive method of adding a custom PHP page to WordPress. It’s actually quite easy, perhaps slightly inefficient, to dynamically create a custom template for a WordPress theme. If you add a custom PHP page to wordpress using a plugin you only need to write the code once and it works for every theme.

The main goal here is to create a PHP page where you can generate any content you like. For this I wanted to pull data from a database outside of WordPress and I didn’t want to create a theme template for dozens of themes. By adding it in the plugin level you can create the page once and call the theme to render the content. There are some rules that you need to follow in order to do this and there may be some further tweaks that need to be made to cover all kinds of themes. I have tested this and it works with all of the themes that I have tested. Some of the steps here might seem unneeded, but I had to add them in order to make the code work with all themes that i tested with.

The first thing you need to do is have a plugin to use. Create a file in this plugin called test.php. The page does not need to be a part of the plugin at all, it just needs to be in the plugin directory so you can easily move it around to other WordPress installs. By default your theme will have a default query. Some themes will just pull a random post and others will generate a post feed. There is no way to prevent this, so instead we need to override the global variables to change it. This is the part that’s a little inefficient, but as you probably know, breaking the WordPress loop isn’t something you want to dig into.

The code below will call the blog header. This will start the loop and leave you with some global variables that contain data that your theme will then display. You need to override this data with your own custom data. This sort of acts like data injection. If anything this is like a custom hook. Once you get the global variables needed, you can do whatever you like with them.

require_once('../../../wp-blog-header.php');

global $post, $posts, $found_posts, $post_count, $wp_query;

If we override all of the relevant data within these variables we can let our theme do all the hard work of rendering the content correctly. This allows us to produce content that matches the look and feel of our website without having to write css for each theme we want to support. To see what is inside each variable you can use a var_dump();

The first thing and most obvious is to override the $post variable. Put whatever you want inside these variables. Hard code them, pull them from an API or get the data from a different DB. Doesnt matter where it comes from, so long as it overrides the existing data.

$post->ID = 99999999999;
$post->post_content = "TEST PAGE content";
$post->post_title = "Page Title";
$post->post_name = "test";
$post->comment_status = "closed";
$post->ping_status = "closed";
$post->post_type = "page";

We have now overridden the global $post variable with our own custom content. This is normally enough for most themes. The theme will display this post and you wont need to do any additional work. Unfortunately the default method of displaying a post, which a lot of themes use, will first print this post and then also display a bunch of other recent posts.

Some themes will use the $wp_query objects via the have_posts() and get_post() methods. This will get the content for $post from $wp_query. We are going to have to override this variable if we want to stop the list of posts from displaying. The following code will override any arrays and variables that contain multiple objects.

$posts = array($post);
$wp_query->posts = $posts;
$wp_query->post_count = 1;
$wp_query->found_posts = 1;
$wp_query->max_num_pages = 1;
$wp_query->post = $post;
$wp_query->is_404 = 0;
$wp_query->is_singular = 1;
$wp_query->page_id = 1;

This should be everything that you need to make themes display the posts correctly. If you find there are themes that need extra work please post in the comments and i will update the post.

The final thing to do, now that we have armed all of the global variables, is to call the default page.php to display our content. We want this to be dynamic so we will get the current theme directory from WordPress. All themes will contain a page.php, so we can be confident that this will work for us.

include get_template_directory()."/page.php";

All of the code above will allow you to add a custom php page to WordPress using a plugin that is completely dynamic. You will not have to modify a theme at all, this code will handle everything through the plugin. Please post any issues or suggestions below so I can make this post as efficient as possible.