Overview

Namespaces

  • Webmozart
    • PathUtil

Classes

  • Path
  • Overview
  • Namespace
  • Class

Class Path

Contains utility methods for handling path strings.

The methods in this class are able to deal with both UNIX and Windows paths with both forward and backward slashes. All methods return normalized parts containing only forward slashes and no excess "." and ".." segments.

Final
Namespace: Webmozart\PathUtil
Author: Bernhard Schussek bschussek@gmail.com
Author: Thomas Schulz mail@king2500.net
Since: 1.0
Located at Path.php
Methods summary
public static string
# canonicalize( string $path )

Canonicalizes the given path.

Canonicalizes the given path.

During normalization, all slashes are replaced by forward slashes ("/"). Furthermore, all "." and ".." segments are removed as far as possible. ".." segments at the beginning of relative paths are not removed.

echo Path::canonicalize("\webmozart\puli\..\css\style.css");
// => /webmozart/css/style.css

echo Path::canonicalize("../css/./style.css");
// => ../css/style.css

This method is able to deal with both UNIX and Windows paths.

Parameters

$path
A path string.

Returns

string
The canonical path.

Since

1.0 Added method.
2.0 Method now fails if $path is not a string.
2.1 Added support for ~.
public static string
# normalize( string $path )

Normalizes the given path.

Normalizes the given path.

During normalization, all slashes are replaced by forward slashes ("/"). Contrary to Webmozart\PathUtil\Path::canonicalize(), this method does not remove invalid or dot path segments. Consequently, it is much more efficient and should be used whenever the given path is known to be a valid, absolute system path.

This method is able to deal with both UNIX and Windows paths.

Parameters

$path
A path string.

Returns

string
The normalized path.

Since

2.2 Added method.
public static string
# getDirectory( string $path )

Returns the directory part of the path.

Returns the directory part of the path.

This method is similar to PHP's dirname(), but handles various cases where dirname() returns a weird result: - dirname() does not accept backslashes on UNIX - dirname("C:/webmozart") returns "C:", not "C:/" - dirname("C:/") returns ".", not "C:/" - dirname("C:") returns ".", not "C:/" - dirname("webmozart") returns ".", not "" - dirname() does not canonicalize the result

This method fixes these shortcomings and behaves like dirname() otherwise.

The result is a canonical path.

Parameters

$path
A path string.

Returns

string

The canonical directory part. Returns the root directory if the root directory is passed. Returns an empty string if a relative path is passed that contains no slashes. Returns an empty string if an empty string is passed.

Since

1.0 Added method.
2.0 Method now fails if $path is not a string.
public static string
# getHomeDirectory( )

Returns canonical path of the user's home directory.

Returns canonical path of the user's home directory.

Supported operating systems: - UNIX - Windows8 and upper

If your operation system or environment isn't supported, an exception is thrown.

The result is a canonical path.

Returns

string
The canonical home directory

Throws

RuntimeException
If your operation system or environment isn't supported

Since

2.1 Added method.
public static string
# getRoot( string $path )

Returns the root directory of a path.

Returns the root directory of a path.

The result is a canonical path.

Parameters

$path
A path string.

Returns

string

The canonical root directory. Returns an empty string if the given path is relative or empty.

Since

1.0 Added method.
2.0 Method now fails if $path is not a string.
public static string
# getFilename( string $path )

Returns the file name from a file path.

Returns the file name from a file path.

Parameters

$path
The path string.

Returns

string
The file name.

Since

1.1 Added method.
2.0 Method now fails if $path is not a string.
public static string
# getFilenameWithoutExtension( string $path, string|null $extension = null )

Returns the file name without the extension from a file path.

Returns the file name without the extension from a file path.

Parameters

$path
The path string.
$extension

If specified, only that extension is cut off (may contain leading dot).

Returns

string
The file name without extension.

Since

1.1 Added method.
2.0 Method now fails if $path or $extension have invalid types.
public static string
# getExtension( string $path, boolean $forceLowerCase = false )

Returns the extension from a file path.

Returns the extension from a file path.

Parameters

$path
The path string.
$forceLowerCase

Forces the extension to be lower-case (requires mbstring extension for correct multi-byte character handling in extension).

Returns

string
The extension of the file path (without leading dot).

Since

1.1 Added method.
2.0 Method now fails if $path is not a string.
public static boolean
# hasExtension( string $path, string|array|null $extensions = null, boolean $ignoreCase = false )

Returns whether the path has an extension.

Returns whether the path has an extension.

Parameters

$path
The path string.
$extensions

If null or not provided, checks if an extension exists, otherwise checks for the specified extension or array of extensions (with or without leading dot).

$ignoreCase

Whether to ignore case-sensitivity (requires mbstring extension for correct multi-byte character handling in the extension).

Returns

boolean

Returns true if the path has an (or the specified) extension and false otherwise.

Since

1.1 Added method.
2.0 Method now fails if $path or $extensions have invalid types.
public static string
# changeExtension( string $path, string $extension )

Changes the extension of a path string.

Changes the extension of a path string.

Parameters

$path
The path string with filename.ext to change.
$extension
New extension (with or without leading dot).

Returns

string
The path string with new file extension.

Since

1.1 Added method.
2.0 Method now fails if $path or $extension is not a string.
public static boolean
# isAbsolute( string $path )

Returns whether a path is absolute.

Returns whether a path is absolute.

Parameters

$path
A path string.

Returns

boolean

Returns true if the path is absolute, false if it is relative or empty.

Since

1.0 Added method.
2.0 Method now fails if $path is not a string.
public static boolean
# isRelative( string $path )

Returns whether a path is relative.

Returns whether a path is relative.

Parameters

$path
A path string.

Returns

boolean

Returns true if the path is relative or empty, false if it is absolute.

Since

1.0 Added method.
2.0 Method now fails if $path is not a string.
public static string
# makeAbsolute( string $path, string $basePath )

Turns a relative path into an absolute path.

Turns a relative path into an absolute path.

Usually, the relative path is appended to the given base path. Dot segments ("." and "..") are removed/collapsed and all slashes turned into forward slashes.

echo Path::makeAbsolute("../style.css", "/webmozart/puli/css");
// => /webmozart/puli/style.css

If an absolute path is passed, that path is returned unless its root directory is different than the one of the base path. In that case, an exception is thrown.

Path::makeAbsolute("/style.css", "/webmozart/puli/css");
// => /style.css

Path::makeAbsolute("C:/style.css", "C:/webmozart/puli/css");
// => C:/style.css

Path::makeAbsolute("C:/style.css", "/webmozart/puli/css");
// InvalidArgumentException

If the base path is not an absolute path, an exception is thrown.

The result is a canonical path.

Parameters

$path
A path to make absolute.
$basePath
An absolute base path.

Returns

string
An absolute path in canonical form.

Throws

InvalidArgumentException

If the base path is not absolute or if the given path is an absolute path with a different root than the base path.

Since

1.0 Added method.
2.0 Method now fails if $path or $basePath is not a string.

2.2.2 Method does not fail anymore of $path and $basePath are absolute, but on different partitions.
public static string
# makeRelative( string $path, string $basePath )

Turns a path into a relative path.

Turns a path into a relative path.

The relative path is created relative to the given base path:

echo Path::makeRelative("/webmozart/style.css", "/webmozart/puli");
// => ../style.css

If a relative path is passed and the base path is absolute, the relative path is returned unchanged:

Path::makeRelative("style.css", "/webmozart/puli/css");
// => style.css

If both paths are relative, the relative path is created with the assumption that both paths are relative to the same directory:

Path::makeRelative("style.css", "webmozart/puli/css");
// => ../../../style.css

If both paths are absolute, their root directory must be the same, otherwise an exception is thrown:

Path::makeRelative("C:/webmozart/style.css", "/webmozart/puli");
// InvalidArgumentException

If the passed path is absolute, but the base path is not, an exception is thrown as well:

Path::makeRelative("/webmozart/style.css", "webmozart/puli");
// InvalidArgumentException

If the base path is not an absolute path, an exception is thrown.

The result is a canonical path.

Parameters

$path
A path to make relative.
$basePath
A base path.

Returns

string
A relative path in canonical form.

Throws

InvalidArgumentException

If the base path is not absolute or if the given path has a different root than the base path.

Since

1.0 Added method.
2.0 Method now fails if $path or $basePath is not a string.
public static boolean
# isLocal( string $path )

Returns whether the given path is on the local filesystem.

Returns whether the given path is on the local filesystem.

Parameters

$path
A path string.

Returns

boolean
Returns true if the path is local, false for a URL.

Since

1.0 Added method.
2.0 Method now fails if $path is not a string.
public static string|null
# getLongestCommonBasePath( array $paths )

Returns the longest common base path of a set of paths.

Returns the longest common base path of a set of paths.

Dot segments ("." and "..") are removed/collapsed and all slashes turned into forward slashes.

$basePath = Path::getLongestCommonBasePath(array( '/webmozart/css/style.css', '/webmozart/css/..'
));
// => /webmozart

The root is returned if no common base path can be found:

$basePath = Path::getLongestCommonBasePath(array( '/webmozart/css/style.css', '/puli/css/..'
));
// => /

If the paths are located on different Windows partitions, null is returned.

$basePath = Path::getLongestCommonBasePath(array( 'C:/webmozart/css/style.css', 'D:/webmozart/css/..'
));
// => null

Parameters

$paths
A list of paths.

Returns

string|null

The longest common base path in canonical form or null if the paths are on different Windows partitions.

Since

1.0 Added method.
2.0 Method now fails if $paths are not strings.
public static string
# join( string[]|string $paths )

Joins two or more path strings.

Joins two or more path strings.

The result is a canonical path.

Parameters

$paths
Path parts as parameters or array.

Returns

string
The joint path.

Since

2.0 Added method.
public static boolean
# isBasePath( string $basePath, string $ofPath )

Returns whether a path is a base path of another path.

Returns whether a path is a base path of another path.

Dot segments ("." and "..") are removed/collapsed and all slashes turned into forward slashes.

Path::isBasePath('/webmozart', '/webmozart/css');
// => true

Path::isBasePath('/webmozart', '/webmozart');
// => true

Path::isBasePath('/webmozart', '/webmozart/..');
// => false

Path::isBasePath('/webmozart', '/puli');
// => false

Parameters

$basePath
The base path to test.
$ofPath
The other path.

Returns

boolean
Whether the base path is a base path of the other path.

Since

1.0 Added method.
2.0 Method now fails if $basePath or $ofPath is not a string.
Constants summary
integer CLEANUP_THRESHOLD

The number of buffer entries that triggers a cleanup operation.

The number of buffer entries that triggers a cleanup operation.
# 1250
integer CLEANUP_SIZE

The buffer size after the cleanup operation.

The buffer size after the cleanup operation.
# 1000
Webmozart Path Utility API API documentation generated by ApiGen