Including other scripts
As a PHP script grows in size and complexity, it's better to split it into several files, so that the code is more manageable. This is possible thanks to the require and include PHP statements.
Include
Say we have a simple script C:\mywebstuff\htdocs\php-tutorial\includeme.php with the following content:
<p>Include me!</p>
Then we have another script C:\mywebstuff\htdocs\php-tutorial\main.php with the following content:
<p>This is the main file</p> <?php include 'includeme.php'; ?>
In this example main.php includes includeme.php. The result of loading http://localhost/php-tutorial/main.php in the browser will be:
This is the main file
Include me!
Or if you view the source of the page, it will be:
<p>This is the main file</p> <p>Include me!</p>
So the browser doesn't know (or care) how many files were used to produce the page, it only sees the final HTML output.
In the example above includeme.php didn't contain any PHP code, but it might as well do, like:
<p>Include me!</p>
<p>Today is <?php echo date('Y-m-d'); ?></p>
Any PHP code in the included file will be processed as usual, so the result will be:
This is the main file
Include me!
Today is 2007-09-08
Include once
You can modify the example above and include the file multiple times, like this:
<p>This is the main file</p> <?php include 'includeme.php'; include 'includeme.php'; include 'includeme.php'; ?>
The result will be:
This is the main file
Include me!
Today is 2007-09-08
Include me!
Today is 2007-09-08
Include me!
Today is 2007-09-08
The content is repeated as many times as the file is included. Most of the times, this is probably not what you need. If you want to make sure a file is included only once, you can use the include_once statement, like this:
<p>This is the main file</p> <?php include_once 'includeme.php'; include_once 'includeme.php'; include_once 'includeme.php'; ?>
The result will be the same as if we used include only once.
include vs include_once
You might think why would I need to use include_once several times with the same file, instead of just using include one time only. Yes, it doesn't make much sense. But as a web application grows in size and complexity, sometimes include_once is an easy way to make sure you don't include the same file by mistake or by a longer include chain (files including other files including other files...).
As you can probably guess include_once is a bit slower than include, because PHP has to lookup its internal table of already included files to make sure the file is not already there. So take-home message is: use include, avoid include_once as much as possible.
Require and require once
What if you try to include a file that doesn't exist? Like this:
<p>This is the main file</p> <?php include 'nothere.php'; ?> <p>The life goes on</p>
This will result in an error (unless of course you have error reporting set to E_NONE), but then the script main.php will continue execution. The result will be:
This is the main file
Warning: include(nothere.php) [function.include]: failed to open stream: No such file or directory in C:\mywebstuff\htdocs\php-tutorial\main.php on line 3
Warning: include() [function.include]: Failed opening 'nothere.php' for inclusion (include_path='.;\xampplite\php\pear\') in C:\mywebstuff\htdocs\php-tutorial\main.php on line 3
The life goes on
If it is vital for your page to have the included file, you can use require. It's the same as include but the script will stop execution if a required file is not found. In the example above if you substitute include with require, the last line "The life goes on" will not be printed, because the script execution will stop after the unsuccessful require.
There is also require_once which makes sure a file is included only once.
A note on the syntax
There are two ways of using the include family of statements:
// as a PHP construct (statement)
include 'includeme.php';
// as a function
include('includeme.php');
Both are valid and will work, but the first one is preferred because it emphasizes on the fact that include and require are language constructs and not functions. (More on functions - in later articles.) BTW, the same is true for echo 'hi'; and echo('hi');
A convention
I find myself naming files that are meant to be included (as opposed to loaded directly in the browser) like: includeme.inc.php, with an .inc.php extension. Some people prefer only .inc like includeme.inc but in this case you have to make sure all .inc files are either outside the webroot or PHP/Apache configuration treats them as PHP files (or declines to serve them!) if they are requested directly. Otherwise the danger is that if someone can guess the location of an .inc file (or sees it in an error message), he/she can request the include directly and the file will be shown as plain text in the browser, exposing some potentially secret PHP code, like for example database username and password.
As an illustration, my web server is not configured to treat .inc the same as .php so my code could be exposed if I had something like database.inc