Using PHP Includes | Sams Teach Yourself Web Publishing with HTML and CSS in One Hour a Day (5th Edition)

In the previous lesson, you learned how to use server-side includes, which enable you to easily include snippets of web pages within other web pages. PHP and all other serverside scripting languages provide the same functionality, generally with the added benefit of giving you a lot more control over how includes are applied. With PHP, files are included using built-in functions. You can conditionally include files, specify which file to include dynamically, or even nest include function calls within included pages. Here's a simple example of an include call:

include("header.php");

On encountering that function call, PHP will try to read in and process a file named header.php in the same directory as the current page. If it can't find this file, it will try to find the file in each of the directories in its include path as well. The include path is a list of directories (generally specified by the server administrator) where PHP searches for files to include, and it's generally set for the entire server in a configuration file.

Four include-related functions are built into PHP: require, require_once, include, and include_once. All these functions include an external file in the page being processed. The difference between "include" and "require" is how PHP reacts when the file being included isn't available. If include or include_once is used, the PHP page prints a warning and continues on. If require or require_once is used, an unavailable include file is treated as a fatal error and page processing stops.

If you use require_once or include_once to include a file that was already included on the page, the function call will be ignored. If you use require or include, the file will be included no matter what.

PHP includes are like HTML links in that you can use relative or absolute paths in your includes. The difference is that absolute PHP paths start at the root of file system rather than the web server's document root. So if you wanted to include a file using an absolute path on a computer running Windows, you'd write the include like this:

require_once('c:\stuff\myfile.php');

That's almost never a good idea. You should always use relative paths where possible. In other words, if the included file is in the directory above the one where the including file is located, you should use a path like this:

require_once("../myinclude.php");

If the file being included is not stored with your other web documents, you should try to have that directory added to your server's include path rather than using absolute paths to access it.

Caution

Never pass data entered by a user to any include function; it's a big security risk. For example, this would be inappropriate:

require_once($_POST['file_to_include');

Choosing Which Include Function to Use

Given these four very similar functions, how do you choose which makes the most sense to use? The most important factor in making that decision is the content of the file to be included. Generally there are two types of include filessnippets of markup that will be presented on your page, and PHP code libraries that provide code you are using on multiple pages throughout a site.

If the file you are including is a library, you just about always want to use require_once. If you're using code from the library on a page, chances are the page will not work if the library file is not available, meaning that you should use require rather than include. If the file contains library code, you're not going to want to include it more than once. Let's look at an example. You've written a library called temperature_converter.php. The contents of the file are shown here:

<?php function celsiusToFahrenheit($temp = 0) {     return round(($temp * 9/5) + 32); } ?>

This file contains one function, celsiusToFahrenheit(), which converts a Celsius temperature to Fahrenheit and then rounds the result so that the function returns an integer. Now let's look at a page that includes this file:

<?php require_once("temperature_converter.php"); ?> <html>   <head>     <title>Current Temperature</title>   </head>   <body>   <p>Current temperature in Fahrenheit: <?= celsiusToFahrenheit(55) ?></p>   </body> </html>

As you can see, in this case the page won't have any meaning if the function in the library page is not available, so using require makes sense. On this page, it wouldn't matter whether I used require or require_once because there are no other includes.

Let's say that the page included another file, one that prints the current temperatures around the world. If that page also had a require() call for temperature_converter.php, the same code would be included twice. An error would cause the page to fail, because each function name can only be declared once. Using require_once ensures that your library code is available and that it is not accidentally included in your page multiple times.

On the other hand, if you're including content that will be displayed within your page, then include or require make more sense. You don't have to worry about conflicts, and if you're including something to be displayed on the page, chances are you want it to appear, even if you've already included the same thing.