PHP Pandas: Includes

← Back to Index

You've been learning PHP for a while now, it's time to talk about your future. You're in a committed relationship with PHP. You have matching his and hers dressing gowns. You might be thinking about marriage already. You're probably going to want to write future applications with PHP, aren't you?

Include

It would be a shame if you had to keep writing the same code over and over again, wouldn't it? I mean, it was fun to write, but it would slowly wear away at you. Let's imagine that you have the following function.

<?php

function welcome($name) {
    return "Welcome, {$name}!";
}

Ah! The old welcome() function. It never gets old! We're gonna need this in a lot of our applications. After all, if we don't welcome our users, they might get angry at us! We can use the include statement to make this code somewhat re-usable.

First let's put the function in it's own file. We'll call it welcome.php. We'll put the same code inside.

<?php

function welcome($name) {
    return "Welcome, {$name}!";
}

Now then, let's create a new file, called program.php. We'll place this file next to the welcome.php file. We want to use the welcome() function within this file, so let's include the welcome.php file. Confused? Let's see the program.php file.

<?php

include 'welcome.php';

echo welcome('Tamas');

We use include() to include the welcome.php file. It's like PHP is copying and pasting the code in welcome.php to where we've put the include statement. We can now use the welcome() function like before.

The include statement is followed by the path to the file that we want to include. This path is relative to the file that you execute with the php command. If our welcome.php file was located in a subfolder, then we could use slashes / like we would in a unix filesystem to denote its location.

<?php

include 'foo/bar/baz/welcome.php';

You can use as many includes as you like! Go ahead and modularise your code into re-usable files. You can also include from your included files. Kind of like that dream movie.

You can use the __DIR__ constant to refer to the directory that the current file is in. This can be useful when include()ing other files!

Require

If you try to include a file that doesn't exist, then PHP will show a warning message, and continue executing. If this is a problem in our applications, we can use the require statement instead of the include to have PHP throw a fatal error when the file cannot be loaded.

The syntax is exactly the same as the include statement. Let's load an imaginary file.

<?php

require 'foo.php';

Let's see what PHP has to say about the imaginary foo.php file, shall we?

Fatal error: require(): Failed opening required 'foo.php'

Great! That's going to put an end to that program. Come back when the file exists, you crazy loon!

Require Once

What would happen if we were to include the welcome.php file twice? You know, the one with the welcome() function inside? Let's find out, shall we?

It's going to look a little like this:

<?php

require 'welcome.php';
require 'welcome.php';

echo welcome('Alastair');

Let's go ahead and execute the code.

Fatal error: Cannot redeclare welcome() (previously declared...

Uh oh! What's going on here? The problem is that you can't define two functions with the same name. They collide, and you get this error. You can't re-declare the welcome() function.

So why do we have two functions anyway? Well we're requiring welcome.php twice. So we're loading the welcome() function twice. How do we get around this problem? What if we forget that we've already required the file, and then require it again much later in the application? This can happen easily if you're using files that include other files that include other files.

Hey, how about that subchapter title? That might help us, right? I mean, it normally does. Take a look at this snippet.

<?php

require_once 'welcome.php';
require_once 'welcome.php';

echo welcome('Alastair');

All we've done here, is replaced the word require with require_once. What's the effect? Well let's execute our program and find out.

Welcome, Alastair!

Hurray! It works. You see, the require_once statement will only include a file once. The second time the statement is executed, the file is ignored, and the welcome() function collision is avoided.

When including PHP code into your application, be sure to consider the effects of including the file twice. Decide whether require or require_once is more appropriate.

Well that's another short chapter read! Don't worry, the next one's going to be a fair bit longer, but extremely exciting!

My books are available online for free to encourage learning. However, if you'd like for me to keep writing, then please consider buying a digital copy over at Leanpub.com.

It's available in PDF, ePub, and Kindle format, and contains a bunch of extras that you won't find on the site. I have a full-time job, and I write my books in my spare time. Please consider buying a copy so that I can continue to write new books from the comfort of my sofa!