Include and require – part II (how to use an included file)
In the previous video we looked at how to specify the location of a file to include both through using an absolute path as well as a path relative to the include path. In this video, we’re going to look more at how and why to include files.
To begin, you might be wondering – what are some situations where you might want to place your data into a separate file? Well, one situation is where you have a configuration file. A config file typically sets up variables that are needed by your script for things like connecting to a database, or connecting to an outside web feed, or setting certain parameters on or off – like whether the site should be in maintenance mode. Depending on how your site is configured, you might even be able to swap out config files and completely change your site from top to bottom. That’s some pretty sweet power when you can do that.
Other possible things to place in external files could be a list of constants you want defined at various points in your script. Since constants all need to be unique, keeping them in one script makes it easier to ensure that you haven’t already named a constant with a certain label. It’s also an easy reference to check when you need to know what constants you’ve already defined.
Pretty much the exact same argument for constants can be made for your custom functions. It can be awfully handy to keep them in their own separate file too.
So, the way this works is as soon as you include a file, any variables set within it become accessible beginning with the line immediately after the include statement. Conversely, any variables already defined by the line of your include statement are available within the file you’re including. In addition, it is entirely acceptable to include a file from within a function, it just won’t have access to variables defined in the global scope. So anyway, here’s a simple example:
{show example scripts}
I’ve written this script to do three simple things. It will define the variable $var1 as ‘hello Mason’. Then it will include the script include.php, and then it will display the value of $var2. Meanwhile over here, my script ‘include.php’ will do just 2 things. It will display the value of $var1, and it will define the variable $var2 as ‘good-bye Mason’.
{show output}
And as you can see we get a quick hello and good-bye message, because $var1 was available in include.php, and $var2 was available in the main script. Now if we flip the main script, and try to access $var2 before we do the include, and then set $var1 after the include:
{show output}
You can see nothing happens, since the variables aren’t yet defined when the scripts try to use them.
Now, the same thing is true of constants. If you try to access them before including the script in which they’re defined, you won’t get their values. What PHP does instead is throw a notice, and depending on your error reporting setting you may or may not know that it threw the notice. And then it just tries to use your constant like a string, as though you had put quotes around its name.
However, this is not the case with functions. When the parser checks over your script, if it sees that your function will definitely be defined, as opposed to defined only if the logic of a particular branch is used, then you can actually call that function higher up in the script than the line where the file that has its definition gets included.
{show example code}
So here the file functions.php gets included further down than my call to doSomething(). But when you look at the output:
{show output}
You see that the function got invoked anyway.
Alright, so last way of using the include statement is with files that don’t contain PHP, or else contain a mix of PHP and other things. When this happens, the contents of your file just get thrown out to the page:
{show example HTML fragment}
{show output}
And you see it showed up. Basically, all an include statement does is add the contents of any file to one long script that the parser generates when it makes its first pass over your code. And then the interpreter actually runs that script. So you don’t need to think about whether you’re adding php or non-php files. They’re all just parts of that one long script. And if there’s no PHP block, the engine just prints them to the page uninterpreted.
An important note about why that last example worked – when you import a file with include or require, PHP does not assume that the included file needs to be interpreted as PHP. If it does, your file needs to include the PHP opening tag. Without it, your file’s contents get output to the page directly with no interpretation.
Another thing to know about include is the fact that PHP supports ‘include_once’ and ‘require_once’. These alternatives can be useful if, for instance, you’re importing a file that defines functions or constants. Including one of these files more than once will trigger a fatal error, since it treats it as though your script is trying to define these multiple times, which isn’t possible in PHP. With include_once and require_once, the PHP engine won’t import the file if it has already been imported previously.
The last thing to know about including and requiring files is that you can use the return statement from within an included file. It works the same as a return statement from within a function. It stops execution of the script, and can optionally return a value. If it does return a value, you can capture that value the same way you would with a regular function. Just assign the value of your include or require statement to a variable in the calling script.
So, let’s look at this in action:
(in calling script)
$returnVal = include ‘./includeMe.php’;
echo $returnVal;
See I’m assigning the return value of this include call to the value $returnVal, and then displaying it.
(in includeMe.php)
<?php
return ‘Hello World!’;
echo ‘Good-bye’;
And in the included script, I’m returning the string ‘Hello World!’ and then displaying ‘Good-bye’.
{show output}
And sure enough, we see ‘Hello World!’ because the calling script was able to use the return value of the included script. But we don’t see the words ‘Good-bye’ because the included script stopped executing after the return statement.
The ability to import files is very useful in PHP, or really any modern programming language. Now that we’ve studied the concept, most of the videos from here on out will involve including or requiring additional files.
February 14 2010 01:22 pm | Basics and PHP Programming Basics and PHP tutorial scripts