TOC

The community is working on translating this tutorial into Kiswahili, but it seems that no one has started the translation process for this article yet. If you can help us, then please click "More info".

Basic PHP:

Including files

One of the most popular features of PHP is the ability to include files. This allows you to separate your code into multiple files, and re-use them in various places. For instance, you can create a file with the functions you use a lot, and then include it when needed, or you can use it to keep your static markup in one place, for easy updating of your site. This may all seem a bit abstract right now, so let's start off with a simple example:

<i>Below this, content will come from another file!</i>
<br /><br /><br />
<?php
$number1 = 20;
include("includedfile.php");
?>
<br /><br /><br />
<i>We're back, after the included file has ended!</i>

Save this into one file, start a new one, save it as includedfile.php in the same directory, and copy/paste this code into it:

<b>This text is included!</b><br />
<?php 
$number2 = 30;
echo "And so is this PHP code - ".$number1." + ".$number2." equals " . ($number1 + $number2) . "!";
?>

If you open up the first file in your browser, you will see that the content of the included file is shown where you have the include statement. As you can see from the example, variables declared in the first file can be used in the included file and the other way around as well. That's because include files in PHP works very simple - PHP simply stuffs the included content into the executed file and interprets it as if it was a part of the file originally.

Different flavors

The include functionality comes in 4 different flavors: include(), include_once(), require() and require_once(). The _once variant makes sure that the file from the parameter is never included more than once, which comes in handy once you start to include several files in various places. The require version should be used when the file you wish to include is critical to the continued execution of your code. If a file can not be found, which can be caused by several things, include() will only issue a warning, while require() will throw a fatal error and the execution will be stopped. As with everything else, all four flavors can come in handy in different situations.

Including files based on the query string

To finish off this chapter, I will show you a real world example of how to use include files for dividing up the markup of your pages into static and dynamic parts. This allows you to have a top and a bottom part, which is static, and then letting only the middle part be dynamic. This can be done in several ways, but this one seems to be very popular. First the example, and then some explanation:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>My website</title>
    <meta name="generator" content="TSW phpCoder 2008" />
</head>
<body>
This part of the website is static. Dynamic content below!
<br /><br /><br />
<?php
if(isset($_GET["show"]))
{
    switch($_GET["show"])
    {
        case "about":
            include("subpage_about.php");
            break;
        case "contact":
            include("subpage_contact.php");
            break;
        default:
            include("subpage_index.php");
            break;                
    }
}
else
    include("subpage_index.php");?>
</body>
</html>

Think of this as your index file of your website. We have some static HTML, which is used no matter what, and then we have this magic switch statement. It includes a subpage based on the show parameter. This means that the page can be called like this:

index.php?show=about

and the file subpage_about.php will be included. If no valid show parameter has been specified, the subpage_index.php file will be included. The subpage files should of course only have the real content of the page, without all the basic HTML like doctype definition, meta tags and so on. This saves you from having all this stuff in all your files, and it allows you to make changes to all your pages by changing one file.

Another way of doing it is by including a top and a bottom file on each page, like this:

<?php
include("top.php");
?>
The actual content of the page goes here!
<?php
include("bottom.php");
?>

How you do it really depends mostly on your personal preferences and the kind of project you're working on, but be sure to realize just how powerful the include file functionality is - it can save you tons of time, and if you're still not sure of it, try reading this chapter again.

This article has been fully translated into the following languages:
Is your preferred language not on the list? Click here to help us translate this article into your language!