Include and require – part I (how to include a file)
Up until this point, we’ve only looked at scripts that are contained entirely in a single file. But in PHP you actually have the ability to split your work up into lots of different files. And in fact, this can be a very handy thing to do, as it can allow you to more effectively organize related portions of your code, and also help to prevent a file from becoming too long to understand.
PHP actually supports two different ways of including external files in your script. There is the include statement, and the require statement. There’s an important distinction between these two statements. If you try to include a file with the include statement, and the file doesn’t exist, the script continues executing anyway. On the other hand, if you try to include that same file using the require statement, your script will trigger a fatal error. This can be a handy thing to do when you know that without that file, your script is going to fail anyway, but the require statement’s error is generally going to be a little more obvious and easier to debug than the result you get when it fails at some later point while using include.
Here’s how the statements look:
include(‘includeMe.php’);
require(‘requireMe.php’);
What these statements will do is cause the contents of the specified files to be inserted into your script at the point where the include or require statements are run. Technically, both ‘include’ and ‘require’ are not functions, but actual language constructs, which is why my editor is coloring them blue. Most language constructs have some quirk about them that make it obvious they aren’t actually functions. Include and require are no different. In their case, they’re like echo statements (echo being another language construct), in that they do not need parenthesis around their arguments:
{modify code to demonstrate}
See? The editor isn’t reporting an error.
In this case, you’ll notice my statements are ambiguous about where the files to import are actually located. I’m using what’s called a relative path. But relative to what? Well, that’s not clear from this context. But obviously my script was written with the assumption that the place PHP looks for these files, called the include path, contains the directory where these files ought to exist.
An include path is a string, and it works like the Windows or Unix environmental variable “PATH”. If you’re not familiar with it, it’s basically one string with either colons separating each directory path if you’re in a Unix environment, or semi-colons separating each if you’re in Windows. And when you use a relative path name, it just searches for the file in each of the include path’s directories, one at a time, until it finds a match, and then it imports that file. If it exists in two locations, only the one that gets checked first will be imported. If I want the second one, I have to use the full path to the file, starting with the root directory.
So now let’s look at the include path on my own PHP install. I’m on a Mac, so its going to use the Unix-style path separator: the colon.
echo get_include_path();
The get_include_path function, since I haven’t modified the path anywhere in my script, is going to get the value set in my php.ini file. We look more at the php.ini settings file in a later chapter. For now, here’s the output from this script:
{show output}
And that tells me which directories I can include from without first altering my include path. Notice the period at the start. This was just the default setting when I installed my XAMPP server. What that does is tell PHP to always check the directory of the file currently being executed first, before looking in other directories. So, if ‘includeMe.php’ and ‘requireMe.php’ exist in the same directory as the script that imports them, I don’t need to make any change to my path in order to import them this way.
Now, suppose we want to get a file that isn’t in this path. Well, if we know the full path to the file, we can either modify the include path if we’re going to be getting several files, or we can use the file’s absolute path if we just need to include from that directory one time.
When you use an absolute path – that is, a path that begins with the root directory, be that a drive letter in Windows or a forward slash in Unix, PHP doesn’t look at the include path setting at all. And because it doesn’t, there is a slight performance benefit from including your files this way. But it’s often the case that we’re not sure of a file’s absolute path ahead of time, or we want the freedom to deploy our code on numerous sites, in which case we can be sure that the absolute paths to our files are going to change. So, a better way to handle this situation is typically to modify the include path once and then use relative paths everywhere else. PHP lets us do that with the set_include_path function.
Since it’s a pretty common task, I’ll show you how to add the current script’s directory to the include path the right way:
set_include_path(get_include_path() . PATH_SEPARATOR . __DIR__);
In this case, I’m not overwriting the existing path, I’m just adding to it. And by the way, the __DIR__ magic constant has only been available since PHP 5.3. On older systems, you would use:
set_include_path(get_include_path() . PATH_SEPARATOR . dirname(__FILE__));
The constant ‘PATH_SEPARATOR’ is one of the ones defined for us by PHP, and we can always count on it being the correct value – whether a semi-colon in Windows or a colon in Unix – no matter what system we’re using.
Before I move on though, one last thing I want to point out. Suppose that includeMe.php and requireMe.php really do exist in the same directory as the file that imports them. If that’s the case, then this:
include(‘./includeMe.php’);
require(‘./requireMe.php’);
is considered an absolute path, and so it’s going to be a little bit faster than using the include path, even if it also begins with a period.
That’s all for this video on the include path. In the next video, we’re going to look at what happens when you actually start including files.
February 13 2010 11:59 pm | Basics and PHP Programming Basics and PHP tutorial scripts