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
require_once) to accomplish this.
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,
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.
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
Now, in the new file, add a line above the
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:
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
Change the line back to spell the filename correctly and then copy that line again, so you have:
require 'threebee.php'; require 'threebee.php';
callthreebee.php and you should see a fatal error, “function already defined” (or something like that).
require_once 'threebee.php'; and the error should be resolved.
The same should happen with
includeing twice, but not not
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:
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.