Including files in a PHP environment can be tricky for new developers.  There are no less than four ways to include a file: include, include_once, require, and require_once.  Moreso, there’s very subtle differences in the reasons behind using each one.  Throw in WordPress (which has its own specific flavor of include tag – get_template_part) and it can be downright confusing.  Using the wrong one, especially in plugin development, can mean the difference between a working plugin and a fatal error.

Let’s break down the various tags and shed some light on their usage.

PHP ‘include’ and ‘include_once’

The include tags are fairly straightforward.  From the PHP Manual:

<?php include(); ?> - The include statement includes and evaluates the specified file.

Simple enough. If you need to call in an external file, using include will bring all of the code into the script you’re running, at the exact spot you’ve placed the tag.  This also means that the file gets access to all of the functions and variables you’ve previously written.  It serves the same function as taking the file, copying its contents, and placing it in the same spot as the tag.

Include_once is very similar, but with one very important difference:

<?php include_once(); ?> - The include_once statement includes and evaluates the specified file during the execution of the script. This is a behavior similar to the include statement, with the only difference being that if the code from a file has already been included, it will not be included again. As the name suggests, it will be included just once.

Include_once is useful when you worry about variable reassignment or “double-calling” existing functions.  Use it, and worry not about duplicate scripts being called.

PHP ‘require’ and ‘require_once’

The require tags are actually very similar as well.  The key difference lies in the effect of calling a file that’s missing.  From the manual:

<?php require(); ?> - require is identical to include except upon failure it will also produce a fatal E_COMPILE_ERROR level error. In other words, it will halt the script whereasinclude only emits a warning (E_WARNING) which allows the script to continue.

<?php require_once(); ?> - The require_once statement is identical to require except PHP will check if the file has already been included, and if so, not include (require) it again.

It’s amazing how easy it is to break these commands down, and yet how subtle the differences are.  If you require a file, and that file doesn’t exist, it’ll throw an error message and will halt the script where it stands.  Include, on the other hand, will simply throw a warning message, allowing the script to continue running.

PHP ‘get_template_part’

This is WordPress’ built in command to include files that are located in the theme’s directory.  But it goes beyond that.  Let’s look at a sample tag:

<?php get_template_part( 'loop', 'single' ); ?>

This is a fairly standard usage.  Get_template_part works well with WordPress because it’s a degrading include – it looks for the more specific template first, before (upon failure to locate) moving to a more general template.

In this case, it would look for the files in this order:

• wp-content/themes/childtheme/loop-single.php

• wp-content/themes/parenttheme/loop-single.php

• wp-content/themes/childtheme/loop.php

• wp-content/themes/parenttheme/loop.php

It starts with the file in a child theme folder, then in the parent theme, and finally checking for a more generic template (child theme first).

So, what gets used when?

Here’s a few very simple rules of thumb.  Obviously, you will want to check your own needs before making a final decision, but this is more of a catch-all, quick thinking way to remember what to do.

• The larger your site, the more likely you’d rather use require_once than include_once.  Smaller scripts can get away with include_once; the more moving parts there are, the more likely you want exact control of which files get called and where.
• Any time a file you need is in your WordPress theme folder, use get_template_part. Period.
• Variables, unless they are global, are un-accessible in templates called with get_template_part. If you need to access a variable, make it a global variable.
• When using require and include, never use absolute links.  The second you deploy your site, things will start to go haywire.  Instead, use relative links.

If you want my honest opinion (and this is strictly that – an opinion) unless you’re doing some outside-of-WordPress stuff that needs to be brought in, most files that need to be brought in through WordPress should be done with get_template_part.  If it’s outside of WordPress (calls to external databases or content), then you can use include_once or require_once.

Any best practices I missed? Feel free to share them below!

Thanks to Ben Woodard for the inspiration for today’s post!

Photo by CalEvans