As I was looking on http://php.net/manual/en/function.file-get-contents.php for the file_get_contents function, I noticed that it takes an optional second parameter named $use_include_path but I cannot understand what is the use and how changes the file_get_contents behavior.
Can you provide me an example in order to understand it better?
include_path in PHP is similar to PATH env variable in the OS: it defines a set of directories where to look for an included/read file.
By default, it is .:/usr/share/php which means current directory . and /usr/share/php. The semicolon : serves as a separator in UNIX-like environments. The separator for your environment is specified in a PATH_SEPARATOR constant.
So, by calling file_get_contents with a relative path and the second parameter as true, PHP would look from the current directory first and then, when specified file is not found, from /usr/share/php.
You can set any set of paths to the include_path by calling set_include_path function. It is good to retain former include_path so you won't break things for your setup:
set_include_path(get_include_path() . PATH_SEPARATOR . '/<your custompath>');
For example, I have file /tmp/code.txt and I need to get contents of this file, I can write something like:
var_dump(file_get_contents('code.txt'));
but it will fall with error (No such file or directory), hence I have to profile full path to file, but in case I don't want to do it, I can write something like:
set_include_path(get_include_path() . PATH_SEPARATOR . '/tmp/');
var_dump(file_get_contents('code.txt', FILE_USE_INCLUDE_PATH));
and it will work!
It is very useful in case you have library or sub-project or you mount your sub-project into another project or you have SDK or something else...
and you can have set_include_path in your bootstrap script for your module/library/whatever but in your code, you have only clear usage of particular files without full path, only relative...