PHP 101: Includes

One of the the most common uses of PHP is what’s called an include. Take a look at this page. It has a header, a footer and a sidebar that appear on every other page on the blog. It would be silly to reproduce those items manually on every page. Instead what you want to do is put the chunks of HTML code for those elements in their own documents and issue a PHP include command so they’re pulled into all the other documents.

If you use includes if you need to make changes to a repeated portion of the site you just make the change in one place (the include document) and it will be changed everywhere.

The most basic PHP include statement looks something like this…

<?php include ("navbar.php"); ?>

The problem with writing it so simply is that writing it that way will look for navbar.php in the same directory as the page you’re serving, which usually isn’t the case. You could use ../navbar.php, ../../navbar.php, etc. – but that gets really messy after a while.

The clean and simple approach is to use the Apache environment variable DOCUMENT_ROOT. That would change the include statement to look something like this:

<?php include ($_SERVER['DOCUMENT_ROOT']."/includes/navbar.php"); ?>

I’ve done a couple things in the statement above…

First, I used DOCUMENT_ROOT which specifies the absolute path on the server to the root directory of your website – for this purpose it’s a very handy variable!

Next, I said that navbar.php was in a directory called “includes”. Doing something like this is generally a very good idea. It organizes all of your include documents in one place and makes things very neat and orderly…

Notice that string values can be concatenated into a larger string value using a period. So there’s a period between DOCUMENT_ROOT and the rest of the path to navbar.php. This is common PHP syntax and something you’ll be using a lot.

One thing that should be mentioned is that include documents are not like the documents you might use with an iFrame – they are not complete HTML documents (with <html>, <head>, <body>, etc.). They are just snippets of HTML code. So don’t put anything in the include document you don’t want to show up in the parent document at the spot where you call the PHP include.

One handy modification to the include code shown above is to change the ‘include’ command to ‘include_once’. That would make it look like this…

<?php include_once ($_SERVER['DOCUMENT_ROOT']."/includes/banner-ads.php"); ?>

As you might expect, include_once will ensure that the include is only done one time on the page. This could be useful if you wanted to put a banner ad after only the first blog post. Or if you were worried about circular references in your include documents. Or perhaps you had something that inserted promotions for different types of visitors and it was possible a visitor fell into two categories. Using include_once would make sure that s/he doesn’t see the same promotion twice on the same page.

That’s pretty much it for includes. Though there is one other thing which may be of interest… PHP variables that you set in the parent document can be used when processing the include document. They can be specified anywhere on the parent page, for simplicity here’s an example where they’re declared in the same PHP code as the include…

$visitorType = "client";
include ($_SERVER['DOCUMENT_ROOT']."/includes/navbar.php");

With that code you could have code in navbar.php that shows certain nav bar elements only if the PHP variable $visitorType is equal to “client”.

Includes are incredibly powerful and every professionally-built website over 3 or 4 pages uses them… And as you can see above – they’re easy to use.