Documentation

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
author

Bernhard Schussek bschussek@gmail.com

author

Thomas Schulz mail@king2500.net

author

Théo Fidry theo.fidry@gmail.com

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, string>
Buffers input/output of {@link canonicalize()}.
$bufferSize  : int
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 (without leading dot).
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 in canonical form of a set of paths or `null` if the paths are on different Windows partitions.
getRoot()  : string
Returns the root directory of a path.
hasExtension()  : bool
Returns whether the path has an (or the specified) extension.
isAbsolute()  : bool
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
join()  : string
Joins two or more path strings into a canonical path.
makeAbsolute()  : string
Turns a relative path into an absolute path in canonical form.
makeRelative()  : string
Turns a path into a relative path.
normalize()  : string
Normalizes the given path.
__construct()  : mixed
findCanonicalParts()  : array<string|int, string>
split()  : array{: string, : string}
Splits a canonical path into its root directory and the remainder.
toLower()  : string

Constants

CLEANUP_SIZE

The buffer size after the cleanup operation.

private mixed CLEANUP_SIZE = 1000

CLEANUP_THRESHOLD

The number of buffer entries that triggers a cleanup operation.

private mixed CLEANUP_THRESHOLD = 1250

Properties

$buffer

Buffers input/output of {@link canonicalize()}.

private static array<string, string> $buffer = []

$bufferSize

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("\symfony\puli\..\css\style.css");
// => /symfony/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
Return values
string —

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)

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:/symfony") returns "C:", not "C:/"
  • dirname("C:/") returns ".", not "C:/"
  • dirname("C:") returns ".", not "C:/"
  • dirname("symfony") 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
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 (without leading dot).

public static getExtension(string $path[, bool $forceLowerCase = false ]) : string
Parameters
$path : string
$forceLowerCase : bool = false

forces the extension to be lower-case

Return values
string —

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
$extension : string|null = null

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

Return values
string —

getHomeDirectory()

Returns canonical path of the user's home directory.

public static getHomeDirectory() : string

Supported operating systems:

  • UNIX
  • Windows8 and upper

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

The result is a canonical path.

Tags
throws
RuntimeException

If your operating system or environment isn't supported

Return values
string —

getLongestCommonBasePath()

Returns the longest common base path in canonical form of a set of paths or `null` if the paths are on different Windows partitions.

public static getLongestCommonBasePath(string ...$paths) : string|null

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

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

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

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

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

$basePath = Path::getLongestCommonBasePath(
    'C:/symfony/css/style.css',
    'D:/symfony/css/..'
);
// => null
Parameters
$paths : string
Return values
string|null —

getRoot()

Returns the root directory of a path.

public static getRoot(string $path) : string

The result is a canonical path.

Parameters
$path : string
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 (or the specified) extension.

public static hasExtension(string $path[, string|array<string|int, string>|null $extensions = null ][, bool $ignoreCase = false ]) : bool
Parameters
$path : string

the path string

$extensions : string|array<string|int, string>|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

Return values
bool —

isAbsolute()

public static isAbsolute(string $path) : bool
Parameters
$path : string
Return values
bool —

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('/symfony', '/symfony/css');
// => true

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

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

Path::isBasePath('/symfony', '/puli');
// => false
Parameters
$basePath : string
$ofPath : string
Return values
bool —

isLocal()

Returns whether the given path is on the local filesystem.

public static isLocal(string $path) : bool
Parameters
$path : string
Return values
bool —

isRelative()

public static isRelative(string $path) : bool
Parameters
$path : string
Return values
bool —

join()

Joins two or more path strings into a canonical path.

public static join(string ...$paths) : string
Parameters
$paths : string
Return values
string —

makeAbsolute()

Turns a relative path into an absolute path in canonical form.

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", "/symfony/puli/css");
// => /symfony/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", "/symfony/puli/css");
// => /style.css

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

Path::makeAbsolute("C:/style.css", "/symfony/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
$basePath : string

an absolute base path

Tags
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

Return values
string —

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("/symfony/style.css", "/symfony/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", "/symfony/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", "symfony/puli/css");
// => ../../../style.css

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

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

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

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

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

The result is a canonical path.

Parameters
$path : string
$basePath : string
Tags
throws
InvalidArgumentException

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

Return values
string —

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
Return values
string —

__construct()

private __construct() : mixed
Return values
mixed —

findCanonicalParts()

private static findCanonicalParts(string $root, string $pathWithoutRoot) : array<string|int, string>
Parameters
$root : string
$pathWithoutRoot : string
Return values
array<string|int, string> —

split()

Splits a canonical path into its root directory and the remainder.

private static split(string $path) : array{: string, : 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:/symfony") // => ["C:/", "symfony"]

list ($root, $path) = Path::split("C:") // => ["C:/", ""]

Parameters
$path : string
Return values
array{: string, : string} —

an array with the root directory and the remaining relative path

toLower()

private static toLower(string $string) : string
Parameters
$string : string
Return values
string —

Search results