Including Files

Include statements in PHP are a way to include the contents of one PHP file into another PHP file before the server executes it. This feature can be particularly useful for several reasons:

Code Reusability: If you have some code that needs to be used on multiple pages or in multiple scripts, you can put that code into a single file and then include that file in each of the scripts where it's needed.
Organization: Using include statements helps to organize your code. For example, you might put all of your functions in one file and then include that file wherever the functions are needed. This makes your code cleaner and easier to manage.
Efficiency in Maintenance: If you have a piece of code included in multiple pages (like a navigation menu), and you want to change something in it, you won't have to go and change it on every single page. Just change it in the included file, and the changes will apply across all pages where it's included.

PHP offers four different keywords for loading files, which are include, require, include_once, and require_once. Let's go through each of them.

Include Statement

Let's start with the include keyword. The syntax for the include statement is as follows:

include 'filename.php';

After the include keyword, you must provide a path to a file. The path can be a relative or an absolute path. Optionally, you can surround the string with a pair of parentheses like so:

include('filename.php');

Either syntax is valid.

Using the include statement

Here's an example to illustrate how include statements work. Let's say you have a file named header.php that includes HTML code for the header of your website:

header.php

<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
  </head>
  <body>

And another file named footer.php that includes HTML code for the footer of your website:

footer.php

    <footer>
        <p>Copyright &copy; 2023 My Website</p>
    </footer>
</body>
</html>

Now, on every page of your website, you can include these files. For example, let's say you had a file called index.php. You can include the header.php and footer.php files from within the index.php file like so:

<?php include 'header.php'; ?>
 
<h1>Welcome to my homepage!</h1>
<p>Some text...</p>
 
<?php include 'footer.php'; ?>

As a result, index.php will contain the complete HTML structure with a header and footer. If you need to change the header or footer, you can do so in header.php or footer.php, and the changes will be reflected on all pages that include these files.

You can expect the output of the index.php file to be the following:

<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
  </head>
  <body>
    <h1>Welcome to my homepage!</h1>
    <p>Some text...</p>
    <footer>
      <p>Copyright &copy; 2023 My Website</p>
    </footer>
  </body>
</html>
</html>

Require Statement

The require statement in PHP is very similar to include. It also allows you to include the contents of one PHP file into another PHP file before the server executes it. The syntax for the require statement is as follows:

require 'filename';

Just like with include, you can use an absolute or relative file path in the require statement.

Differences from include statements

The main difference between include and require arises when the file to be included cannot be found or cannot be opened:

Include: If the file cannot be found, include will throw a warning, but the script will continue to execute.
Require: If the file cannot be found, require will throw a fatal error and stop the script from executing further.

This difference makes require useful in cases where the script can't or shouldn't run without the included file. Conversely, include is useful in cases where the script should still run, even if the included file is missing.

Here's an example to illustrate the difference. Let's say we had the following two files:

file1.php

echo 'Hello, ';
include 'file2.php';
echo '!';

file2.php

echo 'World';

If file2.php exists, then running file1.php will output Hello, World!. If file2.php does not exist, then file1.php will still output Hello, , followed by a warning about the missing file2.php.

On the other hand, if you replace include with require in file1.php:

file1.php

echo 'Hello, ';
require 'file2.php';
echo '!';

Now, if file2.php does not exist, running file1.php will output Hello, , followed by a fatal error due to the missing file2.php, and the script will not output anything else after that.

Including files once

PHP offers two additional keywords for including files. They're called include_once and require_once. The include_once and require_once statements function much like their include and require counterparts, but with one key difference: they check if the file has already been included, and if so, they do not include or require it again.

The syntax for these statements is as follows:

include_once 'filename';
require_once 'filename';

Here's why you might want to use include_once or require_once instead of include or require:

Prevent Multiple Declarations: If you have a file that declares variables, functions, or classes, including it multiple times can lead to errors due to multiple declarations of the same element. Using include_once or require_once prevents this problem because it ensures the file is only included once.
Improve Efficiency: If a file has already been included and its contents are not needed again, including it again can be a waste of resources. include_once or require_once can make your script more efficient by avoiding unnecessary inclusions.

Here's an example to illustrate how include_once works. Let's say you had a file called config.php with variables for storing connectivity details to a database:

config.php

$database_host = 'localhost';
$database_user = 'root';
$database_password = 'password';
$database_name = 'my_database';

You can include it within another file that needs those details like so:

index.php

include_once 'config.php';
 
// Some code...
 
include_once 'config.php';  // This will do nothing because config.php was already included.

In this example, config.php is included only once in index.php, even though there are two include_once 'config.php'; statements. This can be helpful, for example, when you're working on a large project, and it's hard to track every place where a file is included.

Similarly, you can use require_once in place of include_once when you want the file to be included exactly once, and you want to produce a fatal error if the file can't be included.

Key takeaways

The include statement copies the content of the specified file into the current file. If the specified file is missing, include will throw a warning, but the script will continue to execute.
The require statement is similar to include, but if the specified file is missing, require will throw a fatal error and stop the script.
The include_once statement is similar to include, but it checks if the file has already been included, and if so, it doesn't include it again.
The require_once statement ensures that the file is included exactly once and will throw a fatal error if the file can't be included.
If your script needs a certain file to execute properly, you should use require or require_once to ensure the script stops executing if the file is missing.
If the file is not essential, or if you want to handle a missing file in a different way, you can use include or include_once.
If the file contains elements like functions, classes, or variables that should only be declared once, you should use include_once or require_once.