Repository files navigation

PathJoin is PHP library for normalizing and joining file system paths. Thepurpose of this library is to make easier to work with file system pathsirregardless of the platform and the system directory separator.

The purpose of file path normalization is to provide a single consistent filepath representation. In other words, the normalization in this library willresolve. and.. directory references and also condense multiple directoryseparators into one. This makes it much easier to avoid common problems whencomparing paths against each other.

While PHP provides a built in functionrealpath(), it is not usable in everycase since it works by using the file system. This library simply combines andnormalizes the paths using string handling. There is no requirement for thefiles or directories to be readable or even exist.

The API documentation is available at:http://kit.riimu.net/api/pathjoin/

• The minimum supported PHP version is 5.6

The easiest way to install this library is to use Composer to handle yourdependencies. In order to install this library via Composer, simply followthese two steps:

1. Acquire thecomposer.phar by running the ComposerCommand-line installationin your project root.

2. Once you have run the installation script, you should have thecomposer.pharfile in you project root and you can run the following command:

   php composer.phar require "riimu/kit-pathjoin:^1.2"

After installing this library via Composer, you can load the library byincluding thevendor/autoload.php file that was generated by Composer duringthe installation.

If you are already familiar with how to use Composer, you may alternatively addthe library as a dependency by adding the followingcomposer.json file to yourproject and running thecomposer install command:

{"require": {"riimu/kit-pathjoin":"^1.2"    }}

If you do not wish to use Composer to load the library, you may also downloadthe library manually by downloading thelatest releaseand extracting thesrc folder to your project. You may then include theprovidedsrc/autoload.php file to load the library classes.

This library provides two convenient methods,Path::normalize() andPath::join(). Both of these methods work in a very similar fashion. The maindifference is that while thejoin() method can accept multiple paths to join,thenormalize() will only accept a single path. Both of the methods willreturn a normalized path as the result.

The following example will contain numerous different use cases of the library:

<?phprequire'vendor/autoload.php';useRiimu\Kit\PathJoin\Path;// Both of the following will output 'foo/bar' on Unix and 'foo\bar' on Windowsecho Path::normalize('foo/bar') .PHP_EOL;echo Path::join('foo','bar') .PHP_EOL;// The join method accepts multiple arguments or a single arrayecho Path::join('foo','bar','baz') .PHP_EOL;// outputs 'foo/bar/baz'echo Path::join(['foo','bar','baz']) .PHP_EOL;// outputs 'foo/bar/baz'// The '.' and '..' directory references will be resolved in the pathsecho Path::normalize('foo/./bar/../baz') .PHP_EOL;// outputs 'foo/baz'echo Path::join(['foo/./','bar','../baz']) .PHP_EOL;// outputs 'foo/baz'// Only the first path can denote an absolute path in the join methodecho Path::join('/foo','/bar/baz') .PHP_EOL;// outputs '/foo/bar/baz'echo Path::join('foo','/bar') .PHP_EOL;// outputs 'foo/bar'echo Path::join('foo','../bar','baz') .PHP_EOL;// outputs 'bar/baz'echo Path::join('','/bar','baz') .PHP_EOL;// outputs 'bar/baz'// Relative paths can start with a '..', but absolute paths cannotecho Path::join('/foo','../../bar','baz') .PHP_EOL;// outputs '/bar/baz'echo Path::join('foo','../../bar','baz') .PHP_EOL;// outputs '../bar/baz'// Empty paths will result in a '.'echo Path::normalize('foo/..') .PHP_EOL;echo Path::join('foo','bar','../..') .PHP_EOL;

ThePath::normalize() also accepts a second parameter$prependDrive thattakes a boolean value and defaults to true. On Windows platforms, the driveletter is important part of the absolute path. Thus, when the parameter is setto true, the method will prepend the drive letter of the current workingdirectory to absolute paths if the absolute path does not provide one itself.

The following example is true for Windows systems, if the working directory islocated on the C: drive:

<?phprequire'vendor/autoload.php';useRiimu\Kit\PathJoin\Path;echo Path::normalize('/foo/bar') .PHP_EOL;// outputs 'C:\foo\Bar'echo Path::normalize('D:/foo/bar') .PHP_EOL;// outputs 'D:\foo\Bar'echo Path::normalize('/foo/bar',false) .PHP_EOL;// outputs '\foo\Bar'

This library is Copyright (c) 2014-2017 Riikka Kalliomäki.

See LICENSE for license and copying information.