When it comes to PHP, a lot of developers love the language, a lot of the developers hate the language, and a lot of developers generally just use it to get their work done.<\/p>\n
For what it\u2019s worth, I\u2019m of the latter camp. I think PHP is fine. Like anything, it\u2019s not without it\u2019s problems, but I enjoy working with it well enough and see it as a way to get work done versus some pie-in-the-sky language for some time of utopia of development.<\/p>\n
The thing is, one of the things that developer\u2019s love about PHP \u2013 its features and flexibilities \u2013 are the very things that often trip us up. The list is long, but in the WordPress world, one of the most common points of confusion is the proper way to include external files.<\/p>\n
PHP offers four(!) ways to do this and WordPress even offers its own variation thereof.<\/p>\n
In this article, we\u2019ll survey the four ways that PHP offers to include files, guidelines for when to use each, and we\u2019ll review WordPress\u2019 features for including files.<\/p>\n
Generally speaking, including files with PHP refers to the action of including another script into the context of the script on which you\u2019re currently working.<\/p>\n
You can think of this as importing a file such that when the file is returned from the server, the scripts are combined together in the order that they are included, and then interpreted as a single file.<\/p>\n
First, we\u2019ll look at the ways to include files in PHP and the implications of each. At the end of the article, we\u2019ll review when we should be doing this.<\/p>\n
include()<\/code><\/h3>\nAccording to the PHP manual:<\/p>\n
include() will include and evaluate the specified file. If the file isn\u2019t found, a PHP warning will be thrown.<\/p><\/blockquote>\n
Simply put, this means that PHP will look to the file that you\u2019re attempting to include. If it\u2019s found, then it will be added to your script in the exact place that you\u2019ve declared it.<\/p>\n
This is important to understand. For example, let\u2019s say you\u2019re writing a set of functions that depend on a prior set of functions. In that case, you\u2019ll need to make sure the other file is included first.<\/p>\n
On the other hand, if you\u2019re looking to bring in a set of functions or an external file in the middle of an existing function, then you can include it exactly in the place that you need it.<\/p>\n
Secondly, note that if the file is missing, PHP will throw a warning. Depending on the server configuration, you may see this rendered to the browser or you may see this written to a log file (or both).<\/p>\n
Nonetheless, warnings are just that \u2013 they aren\u2019t considered fatal and typically don\u2019t stop execution, but they are important to note because it generally implies that part of your work is not being properly loaded and\/or interpreted.<\/p>\n
Finally, note that when a file is loaded using include()<\/code> that it will have access to all of the variables previously defined in your existing script.<\/p>\nFor example, say that you\u2019re working on a function and halfway through the function, you\u2019re going to include a separate file. That separate file will have access to the variables defined earlier in the function in which it\u2019s included.<\/p>\n
Although you may view this as convenient, it makes the external script a bit unclear as it doesn\u2019t necessarily show that it\u2019s depending on variables defined externally. This can be confusing especially when working with a team.<\/p>\n
include_once()<\/code><\/h3>\nTaken directly from the PHP manual:<\/p>\n
include_once() will perform the same behavior as include() but won\u2019t include the file again if it\u2019s already been included.<\/p><\/blockquote>\n
Obviously, there\u2019s no need to spend as much time talking about the general points of include_once()<\/code>, but there are some key differentiators between how include_once()<\/code> works and how include()<\/code> works.<\/p>\nFirst, whereas include_once()<\/code> performs largely the same as include()<\/code>, it will\u00a0not<\/em> allow you to include the script again. This means that if somewhere else in your project, an external file has been included, that\u2019s\u00a0the definitive location<\/em> in which that file has been included.<\/p>\nSo what\u2019s the advantage of this? Aside from assuring that there\u2019s only a single place in which a script is included, it also ensures that variables and functions won\u2019t necessarily be redefined. Recall that when using include()<\/code>, scripts have access to functions and variables that are defined above them.<\/p>\nIf you opt to define a new set of variables or functions in a file, include it in another script, and\u00a0not<\/em> use include_once()<\/code>, then you run the risk of re-defining functions and variables potentially causing major problems with the execution of your code.<\/p>\n
\nRequiring Files With PHP<\/h2>\n
Requiring files is similar to including files in that it\u2019s another way that you can include a script into the script that you\u2019re currently writing, but it carries a set of its own implications around errors and security.<\/p>\n
Though you can consider the act of requiring a file in much the same way that you can including a file, it does carry the implication that it\u2019s stronger \u2013 that is, the external file is\u00a0required<\/em> for execution.<\/p>\nAs we\u2019ll see, this is exactly this case.<\/p>\n
require()<\/code><\/h3>\nOnce again, straight from the PHP manual:<\/p>\n
require() performs the same as include() but will throw a PHP fatal error if the file isn\u2019t found.<\/p><\/blockquote>\n
So here\u2019s the thing with require()<\/code>: it will perform the same action as include()<\/code> as far as importing the external script into the context of the one on which you\u2019re working, but if it fails to locate the file, it throws an error and completely halts execution.<\/p>\nThis means that your application stops. With include()<\/code>, you\u2019ll get a warning and it will attempt to keep going.<\/p>\nOn some level, it may seem like requiring files is\u00a0the<\/em> right way to go. After all, why would you want to risk including something just to have a warning with a potential failure in the application.<\/p>\nBut it all comes down to the nature of what you\u2019re working on. Sometimes, simple PHP warnings are okay \u2013 like forgetting to initialize the index of an array \u2013 other times, you need an error.<\/p>\n
There aren\u2019t hard and fast rules for when to use this versus includes, but think critically about the nature of what you\u2019re doing and the implications that it carries if it were to fail.<\/p>\n
require_once()<\/h3>\n
Lastly, from the PHP manual:<\/p>\n
require_once() performs the same as require() but will not include the file a second time if it\u2019s already included.<\/p><\/blockquote>\n
This is possibly the easiest to understand since we\u2019ve covered the last three functions in relative detail. Simply put, require_once()<\/code> performs the exact same functions as require, though it will not attempt to include a file again if it\u2019s already loaded in your script.<\/p>\n
\nRules of Thumb<\/h2>\n
In addition to critically thinking through which function is best for the nature of your project, here are two additional rules of thumb to consider when working with include()<\/code> and require()<\/code>:<\/p>\n\nrequire_once()<\/code> is better for larger sites as it does some additional work at the lower level that impacts security and performance<\/li>\ninclude_once()<\/code> is faster and is generally deemed acceptable for smaller sites<\/li>\n<\/ul>\nEasy enough, but what about WordPress helper functions?<\/p>\n
\nIncluding Files With WordPress<\/h2>\n
With all of that said, there\u00a0are<\/em> better ways than using include()<\/code> and require()<\/code> to include templates in your WordPress projects.<\/p>\nSay, for example, that you have several loop files \u2013 one for a post format:<\/p>\n
\n- loop-standard.php<\/li>\n
- loop-image.php<\/li>\n
- loop-quote.php<\/li>\n<\/ul>\n
And you need to include them in single.php<\/strong> whenever you\u2019re working on a theme\u2019s single post page.<\/p>\nAt one point in time, it was acceptable to do something like this:<\/p>\n
include_once( 'loop-standard.php' );<\/pre>\nBut that\u2019s no longer the best practice.<\/p>\n
get_template_part()<\/code><\/h3>\nWordPress now offers a function, get_template_part()<\/code>, that is part of the native API and is used specifically for reusing sections \u2013 or templates \u2013 of code (except for the header, footer, and sidebar) through your theme.<\/p>\nThe function accepts two arguments:<\/p>\n
\n- The first argument is the slug for the template. In the example above, that would be \u2018
loop<\/code>\u2018.<\/li>\n- The second argument is the name of the template. In the example above, that would be \u2018
standard<\/code>\u2018, \u2018quote<\/code>\u2018, or \u2018image<\/code>\u2018.<\/li>\n<\/ul>\nIn sticking with our example above, let\u2019s say that we\u2019re in The Loop<\/a> and we want to include the quote post format template. In that case, we\u2019d do the following:<\/p>\nif( 'quote' == get_post_format() ) {\r\n\r\n\tget_template_part( 'loop', 'quote' );\r\n\r\n}<\/pre>\nOr, assuming that you\u2019ve named your templates to match the post format types, you can do something even cleaner:<\/p>\n
get_template_part( 'loop', get_post_format() );<\/pre>\nClean, right?<\/p>\n
You can actually take this a step farther. Let\u2019s say you\u2019ve abstracted your pagination code out into its own template file called pagination.php<\/strong>. Using get_template_part()<\/code>, you can include this across your entire site in, say, footer.php<\/strong> or in index.php<\/strong>, single.php<\/strong>, archives.php<\/strong>, etc. simply by adding:<\/p>\nget_template_part( 'pagination ');<\/pre>\nMuch easier, isn\u2019t it?<\/p>\n
\nWhen Should I Use What?<\/h2>\n
So after all of this, we still have yet to actually discuss the guidelines of when to use what. By no means am I an authority on this, but here are the rules of thumb that I follow:<\/p>\n
\n- In theme development, I always use
get_template_part()<\/code>.<\/li>\n- In plugin development, I almost always use
include_once()<\/code> and I generally use it once in a function. You can see this in my boilerplates<\/a>.<\/li>\n- If the plugin I\u2019m writing is going to be used on a very large site, then I use
require_once()<\/code>.<\/li>\n<\/ol>\nThat\u2019s all!<\/p>\n
\nFurther Reading<\/h2>\n
For more detailed explanations of what was covered in this article, be sure to read the manual pages for each of the functions:<\/p>\n
\ninclude()<\/code><\/a><\/li>\ninclude_once()<\/code><\/a><\/li>\nrequire()<\/code><\/a><\/li>\nrequire_once()<\/code><\/a><\/li>\nget_template_part()<\/code><\/a><\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"When it comes to PHP, a lot of developers love the language, a lot of the developers hate the language, and a lot of developers generally just use it to get their work done. For what it\u2019s worth, I\u2019m of the latter camp. I think PHP is fine. Like anything, it\u2019s not without it\u2019s problems, […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_bbp_topic_count":0,"_bbp_reply_count":0,"_bbp_total_topic_count":0,"_bbp_total_reply_count":0,"_bbp_voice_count":0,"_bbp_anonymous_reply_count":0,"_bbp_topic_count_hidden":0,"_bbp_reply_count_hidden":0,"_bbp_forum_subforum_count":0},"categories":[7,4],"tags":[],"_links":{"self":[{"href":"https:\/\/a1webdesignteam.com\/blog\/wp-json\/wp\/v2\/posts\/412"}],"collection":[{"href":"https:\/\/a1webdesignteam.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/a1webdesignteam.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/a1webdesignteam.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/a1webdesignteam.com\/blog\/wp-json\/wp\/v2\/comments?post=412"}],"version-history":[{"count":0,"href":"https:\/\/a1webdesignteam.com\/blog\/wp-json\/wp\/v2\/posts\/412\/revisions"}],"wp:attachment":[{"href":"https:\/\/a1webdesignteam.com\/blog\/wp-json\/wp\/v2\/media?parent=412"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/a1webdesignteam.com\/blog\/wp-json\/wp\/v2\/categories?post=412"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/a1webdesignteam.com\/blog\/wp-json\/wp\/v2\/tags?post=412"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}