PHP - Relative paths and Phar Archives

Working with file paths and Phar archives in PHP can be tricky. The PHP code inside of a Phar file will treat relative paths as being relative to the Phar archive, *not* relative to the current working directory. Here's a short example:

Say you have the following files:

phar/index.php
test.php
my.phar

The index.php file is located inside of the phar directory. It is the bootstrap file for the phar archive:

function does_it_exist($file){
  return file_exists($file) ? "true" : "false";
}

The bootstrap file is executed when the phar file is included from a PHP script. Our bootstrap file will simply cause the function "does_it_exist" to be declared.

The file my.phar is the packaged phar archive (see the phar-util project for an excellent phar-building tool). It contains the index.php file at its root.

Let's try running different code inside of test.php and see what the results are for each run:

//Run 1:
require_once 'phar/index.php';  //PHP file
$file = __DIR__ . "/index.php"; //absolute path
echo does_it_exist($file);      //prints "false"

//Run 2:
require_once 'phar/index.php';  //PHP file
$file = "index.php";            //relative path
echo does_it_exist($file);      //prints "false"

//Run 3:
require_once 'my.phar';         //phar file
$file = __DIR__ . "/index.php"; //absolute path
echo does_it_exist($file);      //prints "false"

//Run 4:
require_once 'my.phar';         //phar file
$file = "index.php";            //relative path
echo does_it_exist($file);      //prints "true"

Look at Run 4. This code includes the phar file and passes the function a relative path. Relative to the current working directory, index.php does not exist. But relative to the contents of the phar archive, it does exist, which is why it prints "true"!

Any file paths that you manipulate inside of a phar archive must be absolute. If they are relative, the phar will treat the path as being relative to the phar archive, not relative to the current working directory, which may not be what you intended!

PHP PEAR libraries and Eclipse

If you develop PHP applications using Eclipse, here is a tip that may come in handy.  PDT, the Eclipse plugin for PHP development, will, among other things, display the documentation for any method, function, or field that you hover your mouse over.  And you can jump to the definition of that method, function, or field by control-clicking on it.

But if your application uses libraries installed with PEAR, then this extra functionality will not work for those libraries.  However, this can be fixed by providing Eclipse with the locations of these libraries.

Note: Click on the screenshots below to see a larger image.

1. Right click on your PHP project and select "Properties".

2. Select "PHP Include Path" from the left-hand menu.  Click the "Libraries" tab, then click "Add Library...".

3. Select "User Library" and click "Next".

4. Click "Configure...".  Another new dialog will appear.

5. You want to add a new library, so click "New..." and type in a name for the library.  I'm going to add PHPUnit.

6. Select the newly added Library and click "Add External folder...".  This is where we point to the file system location of the library.

7. Select the path to the library.  In Windows, PEAR installs its libraries inside the "PEAR" folder under the PHP installation directory.  On Mac OSX, its location is "/usr/local/PEAR".  On Ubuntu, it should be at "/usr/share/php/PEAR".  If you can't figure out where your PEAR directory is, you can find it in the "include_path" setting in your php.ini file (when PEAR is installed, it automatically modifies the PHP include path to include itself).  Click "OK".

8. Click "OK", then click "Finish"!

In my next post, I'll explain how to run PHPUnit unit tests from Eclipse without needing any plugins!

Do you have any tips for developing in PHP on Eclipse?  Let me know in the comments section!