Short (trivial) programs like counting to 10 can be done all in one file. But in real-life applications, keeping everything in one file quickly becomes an organizational nightmare.

Most real programs are divided into parts and stored across multiple files, each file containing a part of the whole that makes it possible to focus on one thing at a time and to organize into directories so you can find the thing you’re looking for.

That being the case, we need a way of passing program flow from one file to the next. In PHP we use include (and include_once) and require (and require_once) to accomplish this.

Both include and require direct the PHP processor to pull the contents of an indicated file into memory and continue processing at the top of that file. After reaching the end of what’s there, or when the processor gets to a return statement at any point along the way, processing passes back to the file it was working on before.

include makes the request for the new file optional. If the processor can’t find or read the file, you’ll get a notice, and things move on without it. It’s commonly used when we want to pull in an HTML template, where if the template is missing, that part of the webpage would be missing, but the rest of the output would still be ok.

require makes the request for the new file mandatory. If the processor can’t find or read it, you get a “fatal error” and everything stops. Use this for when you want to call a file where you’ve stored a function or other code that the program needs, and without it, there’s just no sense continuing until you can get the file back.

Each of these has a twin, include_once and require_once. They do exactly the same thing, but they first check to see of the file you’ve asked for has already been included or required, and if so, they skip doing the same file a second time.

So, you might want to have the program include that template HTML exactly one time, and prevent it from displaying any time again after the first time. Or, if you define a function in another file and then require it, you want to make sure you don’t require it again down the line, or you’d end up trying to define the same function twice (which would cause another fatal error), you’d require_once to prevent an accidental reloading.

Assignment

So here’s an easy exercise just to get a feel for how it this kind of thing works.

Create a new file, call it callthreebee.php. Cut all the echo lines out of the bottom of threebee.php, and paste them into the new callthreebee.php file. (Remember to start the new file with <?php!)

Now, in the new file, add a line above the echo lines:

include 'threebee.php';

At the end of the new file, after the echo lines, add a new one:

echo "I made it to the end of the program!";

If you run http://callthreebee.php in your browser, you should get the same result as previously when the function and the calls to the function were in the same file, now with the added report that the program made it to the end.

Now change the include line to require 'threebee.php'; and you should still get the same result.

Now experiment with misspelling the name of the included file:

include 'threbe.php`;

You will probably get a notice or warning of some kind, and then, you'll get a fatal error, "Call to undefined function." Why? Because the you tried to call the threebee() function, which it needed from a file it couldn't find.

Now change the misspelled line to require. You should get a different fatal error, "Failed to find file" or "File does not exist".

In either case, you get a fatal error, but the use of require gives you a more useful error – you know things broke down because a specific file is missing rather than a function is undefined  (which in a large program can save you lots of time trying to track down a missing function from who-knows-where).

Let’s play with the _once versions:

Change the line back to spell the filename correctly and then copy that line again, so you have:

require 'threebee.php';
require 'threebee.php';

Run callthreebee.php and you should see a fatal error, “function already defined” (or something like that).

Change to require_once 'threebee.php'; and the error should be resolved.

The same should happen with includeing twice, but not not include_onceing twice.

To see the difference for include, cut the pair of include lines out of the callthreebee file and past them into the bottom of the threebee file after the function (where the echo lines were originally), changing the requested filename to ‘callthreebee.php’ on each line:

<?php
function threebee() {
	// ...
}

include 'callthreebee.php';
include 'callthreebee.php';
threebee.php
<?php
echo callthreebee('123);
// ...
echo "I made it to the end!";
callthreebee.php

Now run from the threebee.php file. You should see that the output from the echos is doubled, because it was included twice. If you change to include_once, the duplicate should disappear.