Tech Chorus

What is include_path?

To include a file in your PHP script you use the include statement. Hard coding the complete file system path in all your include statements is unmaintainable. You cannot expect your application to be installed in the exact same location everywhere. Including the files from a relative path is so much more easier.

Let us write few simple scripts for demonstration purpose.

Create the file mymainfile.php and paste the below code in it.

Create the file subfile.php in the same directory as mymainfile.php and paste the below code in it.

Run the script mymainfile.php. The output looks like:

This is the main file
This is the sub-file

So far, everything is all right.

We all know that every web application requires reusable code for better maintenance. The reusable code may contain functions and classes. When the library of reusable code grows in size, you start grouping these classes and functions in several files. The functions related to input filtering might be placed in input_filter.php. The functions and classes related to database might be placed in database.php. So on and so forth. To better organize the files you decide to put all your reusable files in the directory 'library'.

Your directory structure may look like:

mymainfile.php
library/database.php
library/input_filter.php

As the application grows, you add more files into your library. Let us modify our mainfile.php to use some database related functions. We include the file database.php which is inside the library directory.

The script above works as intended only if the directory library is in the same directory as mymaifile.php. What if we want to include database.php in a script other than mymainfile.php? We use the relative path.

Let us write another script. Create the directory my/subdirectory and create the file anotherscript.php inside my/subdirectory. The directory structure looks like below

mymainfile.php
my/subdirectory/anotherscript.php
library/database.php
library/input_filter.php

The above script works only if your invoke it from my/subdirectory.

Notice '../../' in the include statement. It indicates the relative path of the library/database.php. Writing relative paths like this in every file quickly becomes a mess to manage.

Enter include_path

include_path instructs PHP where to look for files while including. You can set the include_path in your php.ini file. You can also set the include_path in your PHP script using the function set_include_path().

Let us modify our anotherscript.php to demonstrate set_include_path().

In our script we have instructed PHP to look for files in the directory '../../library' while including. Thus we specify only the file name without any path in the next statements. Create the file input_filter.php in library directory if you haven't already.

Once you set the include path you don't have to specify the path to the file while including. This makes it easier to maintain the application. You can easily move around your scripts from one directory to another. As long as the correct include_path is set you don't have to fiddle with the include statements.

To set two directories as the include_path you pass the two paths separated by path separator. The path separator on Unix and Unix like operating systems is colon(:). On Windows it is semicolon(;). To circumvent this platform specific problem PHP offers the constant PATH_SEPARATOR.

This is how you set multiple directories in your include_path.

You can use the function set_include_path() as many times as you want in your scripts. One gotcha worth mentioning is set_include_path() overwrites previously set include_path. To work around this problem you use the function get_include_path();

get_include_path() returns the currently set include_path.

The output of the above script looks like:

.:/usr/share/pear:/usr/share/php

Example to set a new path retaining the previosuly set include_path.

Always use get_include_path() while setting the include_path.

While setting the include_path avoid using '../../' in the beginning of the path string. For example if you are setting the path like below code:

The PHP constant __FILE__ contains the complete path to the current script.

Disclaimer: We used the relative path in our example above only to demonstrate the usage of function set_include_path().

You can also set include_path in your php.ini. Use this feature if multiple applications on your server share the same libraries. For instance, you could put PEAR in /usr/lib/php/PEAR and add that directory to your include_path. Once you add it to your include_path PEAR will be globally accessible to all your PHP applications.

An example configuration in php.ini is

We have now learned how to use include_path. In the next article I will write about autoload.

PHP Manual reference:
http://php.net/include/
http://php.net/manual/en/ini.core.php#ini.include-path
http://php.net/set_include_path
http://php.net/manual/en/function.get-include-path.php
http://php.net/manual/en/function.dirname.php
http://php.net/manual/en/function.realpath.php