Question

I’m looking for a way to disable PHP’s use of include_path in a project.

Background

Perhaps you’re surprised: Why would I want to prevent the use of such a useful feature?

Unfortunately, while I’d consider the answer simple, it’s not simple to accurately describe:

In brief, include_path is (obviously) package-/library-blind.

More specifically, it’s possible to put two different versions of a library into two folders, both of which are in include_path, and ending up with executed code that is a mixture of both. Consider the following setting:

include_path=/some/server/path/lib:
    /var/www/apache/htdocs/yourApplication/library

Now imagine the canonical location for a library you want to use is in /some/server/path/lib and your build process places it there, but a developer is trying to patch a part of it and erroneously syncing the library to /var/www/apache/htdocs/yourApplication/library. Now imagine this happens:

/some/server/path/lib/moduleYouWant
    '--> A.php (old version)
/var/www/apache/htdocs/yourApplication/
    '--> SomeFile.php (uses B.php from module; previously used A.php)
/var/www/apache/htdocs/yourApplication/library/moduleYouWant
    '--> A.php (new version)
    '--> B.php (new file; uses A.php from module)

Suddenly, your application will mysteriously use or autoload (if your autoloader puts include_path to use, which most framework-supplied autoloaders do, as far as I’m aware) only half of the changes you made – the new B.php but the old A.php.

You may, of course, object to the setup I’ve described on grounds that it should never happen for other reasons. That’s fair. I’m likely to agree, even. The above scenario is a backwards-incompatible change, for example, and that’s not very nice.

Nonetheless, so far I’ve seen it happen twice in the wild (in a sufficiently complex project, with chroots muddying the water) and it’s eaten up countless confused debugging hours… and I don’t want to have that issue again. Not in this sort of constellation – or any other.

I don’t want PHP magically trying to find my files. I want PHP to demand I be specific about which files to load.

Why I don’t need include_path

With __DIR__ (or dirname(__FILE__) in older PHP versions), semantically ‘relative’ paths are easy to construct. And if I need live- and test-server distinctions, constants defining absolute locations are my friend.

So… I want non-absolute paths supplied to include() (and related functions) to fail.

This stackoverflow question from 2011 tells me that I can’t blank include_path. Is there perhaps some other way I can disable the feature? My Googlefu is weak, but nonetheless I have a creeping suspicion the answer is ‘no (unless you patch PHP itself)’.

If someone knows of a way I can put a stop to this other than by code convention agreement (or the related “please don’t use include() but this custom function I wrote“), I’d love to know. 🙂

Answer 1

You indicate that the root of the problem is that you have developers writing bad relative includes where they should use be using absolute includes or autoloading.

The solution to this is not technical but cultural. You can enforce correct behavior by adding a pre-commit-hook to your versioning-system that tries to detect erroneous includes (either relative includes, or just all includes) and block the commit.