Site Structure: Where to Locate Includes?

NYPHP - PHundamentals

Code which is going to be reused in different scripts is typically put into libraries of files which are then included into scripts as needed; they are therefore called "include files." This practice eases maintenance and can help to provide a logical organization to a website. Sometimes, however, these include files contain sensitive data like database connection information, so it is important to store this information as securely as possible. Where then should these libraries of include files be located? Best practice in answer to this question is determined by whether you control the server.

Scenario 1
When you control the server

Files in the document root, typically something like /var/www/html/ on a Linux box, are accessible to the public. When you control the server, you should place libraries of include files elsewhere on the server, above the document root, and then make sure that they are accessible to scripts in the document root while keeping them inaccessible to the public. You should thus place them in the default php directory, which might be something like /usr/lib/php, or in the default php includes directory, which might be something like /usr/lib/php/includes, or in a location of your choosing outside the document root directory, such as /var/www/includes or /var/includes.

You should make sure that the path to your include files is in your php.ini (unless you are using one of the default locations). Do this by adding your path to the value of include_path in the Paths and Directories section of php.ini.

Scenario 2
When you do not control the server

This scenario assumes that you are working on a shared host and thus have limited or no control over the server’s configuration.

Scenario 2A
You have access to directories just above the document root directory.

In this case you can proceed as above, placing the libraries above the document root, in a location of your choice, such as /var/www/includes. You will then need to specify the relative path to the file when you include it.

Scenario 2B
You do not have access to those directories above document root.

Your only recourse in this case is to place the libraries in a subdirectory of document root, like /var/www/html/includes. Again, you will need to specify the relative path to the file when you include it.

How should include files be named?

Although some prefer to give include files a .php extension, in order to force them to run on the server rather than being displayed, this is not a good idea: there is potential danger in having isolated files executing out of the context of the programs for which they were designed; and this extension fails to logically distinguish the include files with their library code from scripts containing executable code.

Best practice is to give include files an .inc extension. When your include files are in a subdirectory of document root, where they are normally exposed to browsers, you should use an .htaccess file to tell Apache not to display or serve them. Do this by creating an .htaccess file in your document root directory which contains the following four lines:

<Files *.inc>
  order allow,deny
  deny from all
</Files>

As a last resort, if your hosting company does not allow you to create .htaccess, you can give your include files a .php extension. You should, however, be sensitive to the potential danger of having these isolated files execute out of context.

Contributors to this note include the following:
Jon Baer
Daniel Cain
Dan Convissor
Russ Demarest
Adam Fields
Max Goldberg
Jim Hendricks
Seth Hersh
Daniel Krook
Brian Pang
David Sexton
Chris Shiflett
David Sklar
Chris Snyder
Hans Zaunere
the PHundamentals team: Jeff Siegel and Mike Southwell