Several rows of overlapping blue theater seats
Part of the PHP Basics Reading List

In most websites you have areas of content that are the same from one page to the next. These sections might include:

The appearance of this content is commanded byCSS, which allows us to maintain rules for the consistent presentation of content across a site. However, the content itself is also often exactly the same: for example, you may always have the same code immediately after the opening body tag on every page:

<h1>Hannibal’s Bait &amp; Tackle Shop</h1>
<h3>Duluth, North Dakota</h3>

To make this content the same between all pages, most so-called web developers copy and paste the same code from one HTML page to the next. The approach works well so long as the content never changes. But if the site in our example decided to offer boat rental, and changed their business name to “Hannibal’s Bait, Boat & Tackle Store”, we would have a massive amount of editing to do site-wide. We can avoid this problem entirely – and speed up web development by 10 - 50% – by using PHP includes from the very beginning.

(It is possible to “shim” PHP includes into an already extant site, but doing so usually takes considerably more work: like most things, PHP includes are a technique that deliver their greatest value if you use them right the first time, when you are initially creating a site.)

Every server-side scripting language features some form of includes: you will also hear them referred to as server-side includes or SSI’s. In PHP, the process of using them goes something like this:

  1. Make sure that the page you want to use the include on has a .php extension. (Note that if a server is confronted with an index.html and index.php page in the same location, it will preferentially choose the first. Be very careful when substituting PHP pages for HTML ones.)
  2. Usually your content already exists on the page. Cut (CTRL-X) this content, taking note of its location in the code.
  3. Make a new HTML page.
  4. Remove all code from the new page. An include takes everything from the include file and puts it into place on the main PHP page: we only want our snippet of code to be placed.
  5. Paste (CTRL-V) the code you copied from the previous page.
  6. Save the HTML page with the snippet of code, with a filename that follows naming conventions: for example, header.html It is typical (but not required) to save the page in an includes sub-folder inside an assets folder.
  7. Return to the original PHP page. In the exact location where the HTML code was removed, write the following (assuming that the assets folder is directly beside the PHP page): 
    <?php include('assets/includes/header.html'); ?>
  8. Make sure that both the PHP page and the include file, along with any directories, are correctly uploaded to the server, and test them in the browser.
  9. Make another PHP page that uses the same code to include the same file.
  10. Note that a similar function to include exists in PHP, in the form of require. Both include and require work exactly the same way, with two exceptions:
    1. The functions differ the way in which they handle failure. If include fails to find the file, the rest of the script proceeds as normal, and a printed warning is added to the page location where the include was written. The rest of the page will appear normal.

      On the other hand, if require fails to find the file it is directed to, it causes a fatal error. All execution of the page stops, and the result is likely to be a fatal error message on an otherwise blank page.

    2. include may be used as the action of a condition (i.e. inside an if statement.) However a file called by require will always appear on the page, even if it is placed inside a condition in which an argument is not met.

    For these reasons, I usually stick to include to do a server-side include on a PHP page.

    Taking things too far

    It is common for overly-ambitious coders to see the potential of include and go somewhat overboard, with the equivalent of the statement “Wow! All my pages down to the opening <body> tag are the same code, so I’ll just make all of that code one giant include!” In doing so, they are forgetting that the <title> should be different on every page, and includes, as we have used them here, don’t differentiate between pages they are used on. There are ways around this, but for now, think of consistent content in the body alone as being suitable for includes.

    Alternatives to includes

    Many dynamic scripting languages feature their own alternatives to include, as do other server-side solutions and programs. , for example, uses what it refers to as “templates” to achieve the same ends. The problem with proprietary solutions is that you must use continue to use DreamWeaver (as an example) to edit template files from that point forward. And, in my experience, when proprietary solutions go bad, they go really bad. There can be compelling reasons to use a proprietary solution, but the fact that you can use a (or anything else) to change PHP remains a strong argument in its favour.

    Long term, PHP includes are likely to replaced by HTML5 import and template, but support for those modules has only just started, as of this writing, and it will be many years before they can be relied upon.

    Photograph by Andrey Salinsky, used under a Creative Commons Attribution-NonCommercial-NoDerivs 2.0 Generic license

    Enjoy this piece? I invite you to follow me at twitter.com/dudleystorey to learn more.