Path
in package
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.
Tags
Table of Contents
- CLEANUP_SIZE = 1000
- The buffer size after the cleanup operation.
- CLEANUP_THRESHOLD = 1250
- The number of buffer entries that triggers a cleanup operation.
- $buffer : array<string|int, mixed>
- Buffers input/output of {@link canonicalize()}.
- $bufferSize : int
- The size of the buffer.
- canonicalize() : string
- Canonicalizes the given path.
- changeExtension() : string
- Changes the extension of a path string.
- getDirectory() : string
- Returns the directory part of the path.
- getExtension() : string
- Returns the extension from a file path.
- getFilename() : string
- Returns the file name from a file path.
- getFilenameWithoutExtension() : string
- Returns the file name without the extension from a file path.
- getHomeDirectory() : string
- Returns canonical path of the user's home directory.
- getLongestCommonBasePath() : string|null
- Returns the longest common base path of a set of paths.
- getRoot() : string
- Returns the root directory of a path.
- hasExtension() : bool
- Returns whether the path has an extension.
- isAbsolute() : bool
- Returns whether a path is absolute.
- isBasePath() : bool
- Returns whether a path is a base path of another path.
- isLocal() : bool
- Returns whether the given path is on the local filesystem.
- isRelative() : bool
- Returns whether a path is relative.
- join() : string
- Joins two or more path strings.
- makeAbsolute() : string
- Turns a relative path into an absolute path.
- makeRelative() : string
- Turns a path into a relative path.
- normalize() : string
- Normalizes the given path.
- __construct() : mixed
- split() : array<string|int, string>
- Splits a part into its root directory and the remainder.
- toLower() : string
- Converts string to lower-case (multi-byte safe if mbstring is installed).
Constants
CLEANUP_SIZE
The buffer size after the cleanup operation.
public
mixed
CLEANUP_SIZE
= 1000
CLEANUP_THRESHOLD
The number of buffer entries that triggers a cleanup operation.
public
mixed
CLEANUP_THRESHOLD
= 1250
Properties
$buffer
Buffers input/output of {@link canonicalize()}.
private
static array<string|int, mixed>
$buffer
= array()
$bufferSize
The size of the buffer.
private
static int
$bufferSize
= 0
Methods
canonicalize()
Canonicalizes the given path.
public
static canonicalize(string $path) : string
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 : string
-
A path string.
Tags
Return values
string —The canonical path.
changeExtension()
Changes the extension of a path string.
public
static changeExtension(string $path, string $extension) : string
Parameters
- $path : string
-
The path string with filename.ext to change.
- $extension : string
-
New extension (with or without leading dot).
Tags
Return values
string —The path string with new file extension.
getDirectory()
Returns the directory part of the path.
public
static getDirectory(string $path) : string
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 : string
-
A path string.
Tags
Return values
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.
getExtension()
Returns the extension from a file path.
public
static getExtension(string $path[, bool $forceLowerCase = false ]) : string
Parameters
- $path : string
-
The path string.
- $forceLowerCase : bool = false
-
Forces the extension to be lower-case (requires mbstring extension for correct multi-byte character handling in extension).
Tags
Return values
string —The extension of the file path (without leading dot).
getFilename()
Returns the file name from a file path.
public
static getFilename(string $path) : string
Parameters
- $path : string
-
The path string.
Tags
Return values
string —The file name.
getFilenameWithoutExtension()
Returns the file name without the extension from a file path.
public
static getFilenameWithoutExtension(string $path[, string|null $extension = null ]) : string
Parameters
- $path : string
-
The path string.
- $extension : string|null = null
-
If specified, only that extension is cut off (may contain leading dot).
Tags
Return values
string —The file name without extension.
getHomeDirectory()
Returns canonical path of the user's home directory.
public
static getHomeDirectory() : string
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.
Tags
Return values
string —The canonical home directory
getLongestCommonBasePath()
Returns the longest common base path of a set of paths.
public
static getLongestCommonBasePath(array<string|int, mixed> $paths) : string|null
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 : array<string|int, mixed>
-
A list of paths.
Tags
Return values
string|null —The longest common base path in canonical form or
null if the paths are on different Windows
partitions.
getRoot()
Returns the root directory of a path.
public
static getRoot(string $path) : string
The result is a canonical path.
Parameters
- $path : string
-
A path string.
Tags
Return values
string —The canonical root directory. Returns an empty string if the given path is relative or empty.
hasExtension()
Returns whether the path has an extension.
public
static hasExtension(string $path[, string|array<string|int, mixed>|null $extensions = null ][, bool $ignoreCase = false ]) : bool
Parameters
- $path : string
-
The path string.
- $extensions : string|array<string|int, mixed>|null = null
-
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 : bool = false
-
Whether to ignore case-sensitivity (requires mbstring extension for correct multi-byte character handling in the extension).
Tags
Return values
bool —Returns true if the path has an (or the specified)
extension and false otherwise.
isAbsolute()
Returns whether a path is absolute.
public
static isAbsolute(string $path) : bool
Parameters
- $path : string
-
A path string.
Tags
Return values
bool —Returns true if the path is absolute, false if it is relative or empty.
isBasePath()
Returns whether a path is a base path of another path.
public
static isBasePath(string $basePath, string $ofPath) : bool
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 : string
-
The base path to test.
- $ofPath : string
-
The other path.
Tags
Return values
bool —Whether the base path is a base path of the other path.
isLocal()
Returns whether the given path is on the local filesystem.
public
static isLocal(string $path) : bool
Parameters
- $path : string
-
A path string.
Tags
Return values
bool —Returns true if the path is local, false for a URL.
isRelative()
Returns whether a path is relative.
public
static isRelative(string $path) : bool
Parameters
- $path : string
-
A path string.
Tags
Return values
bool —Returns true if the path is relative or empty, false if it is absolute.
join()
Joins two or more path strings.
public
static join(array<string|int, string>|string $paths) : string
The result is a canonical path.
Parameters
- $paths : array<string|int, string>|string
-
Path parts as parameters or array.
Tags
Return values
string —The joint path.
makeAbsolute()
Turns a relative path into an absolute path.
public
static makeAbsolute(string $path, string $basePath) : string
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 : string
-
A path to make absolute.
- $basePath : string
-
An absolute base path.
Tags
Return values
string —An absolute path in canonical form.
makeRelative()
Turns a path into a relative path.
public
static makeRelative(string $path, string $basePath) : string
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 : string
-
A path to make relative.
- $basePath : string
-
A base path.
Tags
Return values
string —A relative path in canonical form.
normalize()
Normalizes the given path.
public
static normalize(string $path) : string
During normalization, all slashes are replaced by forward slashes ("/"). Contrary to , 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 : string
-
A path string.
Tags
Return values
string —The normalized path.
__construct()
private
__construct() : mixed
Return values
mixed —split()
Splits a part into its root directory and the remainder.
private
static split(string $path) : array<string|int, string>
If the path has no root directory, an empty root directory will be returned.
If the root directory is a Windows style partition, the resulting root will always contain a trailing slash.
list ($root, $path) = Path::split("C:/webmozart") // => array("C:/", "webmozart")
list ($root, $path) = Path::split("C:") // => array("C:/", "")
Parameters
- $path : string
-
The canonical path to split.
Return values
array<string|int, string> —An array with the root directory and the remaining relative path.
toLower()
Converts string to lower-case (multi-byte safe if mbstring is installed).
private
static toLower(string $str) : string
Parameters
- $str : string
-
The string
Return values
string —Lower case string