eloquent/pathogen API
Class

Eloquent\Pathogen\AbsolutePath

class AbsolutePath extends AbstractPath implements AbsolutePathInterface

Represents an absolute path.

Constants

ATOM_SEPARATOR

The character used to separate path atoms.
EXTENSION_SEPARATOR

The character used to separate path name atoms.
PARENT_ATOM

The atom used to represent 'parent'.
SELF_ATOM

The atom used to represent 'self'.

Methods

__construct(mixed<string> $atoms, boolean|null $hasTrailingSeparator = null)

Construct a new path instance.

 from AbstractPath
array<integer,string> atoms()

Get the atoms of this path.

 from AbstractPath
string atomAt(integer $index)

Get a single path atom by index.

 from AbstractPath
mixed atomAtDefault(integer $index, mixed $default = null)

Get a single path atom by index, falling back to a default if the index is undefined.

 from AbstractPath
array<integer,string> sliceAtoms(integer $index, integer|null $length = null)

Get a subset of the atoms of this path.

 from AbstractPath
boolean hasAtoms()

Determine if this path has any atoms.

 from AbstractPath
boolean hasTrailingSeparator()

Determine if this path has a trailing separator.

 from AbstractPath
string string()

Generate a string representation of this path.
string __toString()

Generate a string representation of this path.

 from AbstractPath
string name()

Get this path's name.

 from AbstractPath
array<integer,string> nameAtoms()

Get this path's name atoms.

 from AbstractPath
string nameAtomAt(integer $index)

Get a single path name atom by index.

 from AbstractPath
mixed nameAtomAtDefault(integer $index, mixed $default = null)

Get a single path name atom by index, falling back to a default if the index is undefined.

 from AbstractPath
array<integer,string> sliceNameAtoms(integer $index, integer|null $length = null)

Get a subset of this path's name atoms.

 from AbstractPath
string nameWithoutExtension()

Get this path's name, excluding the last extension.

 from AbstractPath
string namePrefix()

Get this path's name, excluding all extensions.

 from AbstractPath
string|null nameSuffix()

Get all of this path's extensions.

 from AbstractPath
string|null extension()

Get this path's last extension.

 from AbstractPath
boolean hasExtension()

Determine if this path has any extensions.

 from AbstractPath
boolean contains(string $needle, boolean|null $caseSensitive = null)

Determine if this path contains a substring.

 from AbstractPath
boolean startsWith(string $needle, boolean|null $caseSensitive = null)

Determine if this path starts with a substring.

 from AbstractPath
boolean endsWith(string $needle, boolean|null $caseSensitive = null)

Determine if this path ends with a substring.

 from AbstractPath
boolean matches(string $pattern, boolean|null $caseSensitive = null, integer|null $flags = null)

Determine if this path matches a wildcard pattern.

 from AbstractPath
boolean matchesRegex(string $pattern, array $matches = null, integer|null $flags = null, integer|null $offset = null)

Determine if this path matches a regular expression.

 from AbstractPath
boolean nameContains(string $needle, boolean|null $caseSensitive = null)

Determine if this path's name contains a substring.

 from AbstractPath
boolean nameStartsWith(string $needle, boolean|null $caseSensitive = null)

Determine if this path's name starts with a substring.

 from AbstractPath
boolean nameMatches(string $pattern, boolean|null $caseSensitive = null, integer|null $flags = null)

Determine if this path's name matches a wildcard pattern.

 from AbstractPath
boolean nameMatchesRegex(string $pattern, array $matches = null, integer|null $flags = null, integer|null $offset = null)

Determine if this path's name matches a regular expression.

 from AbstractPath
PathInterface parent(integer|null $numLevels = null)

Get the parent of this path a specified number of levels up.

 from AbstractPath
PathInterface stripTrailingSlash()

Strips the trailing slash from this path.

 from AbstractPath
PathInterface stripExtension()

Strips the last extension from this path.

 from AbstractPath
PathInterface stripNameSuffix()

Strips all extensions from this path.

 from AbstractPath
PathInterface joinAtoms($atom)

Joins one or more atoms to this path.

 from AbstractPath
PathInterface joinAtomSequence(mixed<string> $atoms)

Joins a sequence of atoms to this path.

 from AbstractPath
PathInterface join(RelativePathInterface $path)

Joins the supplied path to this path.

 from AbstractPath
PathInterface joinTrailingSlash()

Adds a trailing slash to this path.
PathInterface joinExtensions($extension)

Joins one or more extensions to this path.

 from AbstractPath
PathInterface joinExtensionSequence(mixed<string> $extensions)

Joins a sequence of extensions to this path.

 from AbstractPath
PathInterface suffixName(string $suffix)

Suffixes this path's name with a supplied string.

 from AbstractPath
PathInterface prefixName(string $prefix)

Prefixes this path's name with a supplied string.

 from AbstractPath
PathInterface replace(integer $index, mixed<string> $replacement, integer|null $length = null)

Replace a section of this path with the supplied atom sequence.

 from AbstractPath
PathInterface replaceName(string $name)

Replace this path's name.

 from AbstractPath
PathInterface replaceNameWithoutExtension(string $nameWithoutExtension)

Replace this path's name, but keep the last extension.

 from AbstractPath
PathInterface replaceNamePrefix(string $namePrefix)

Replace this path's name, but keep any extensions.

 from AbstractPath
PathInterface replaceNameSuffix(string|null $nameSuffix)

Replace all of this path's extensions.

 from AbstractPath
PathInterface replaceExtension(string|null $extension)

Replace this path's last extension.

 from AbstractPath
PathInterface replaceNameAtoms(integer $index, mixed<string> $replacement, integer|null $length = null)

Replace a section of this path's name with the supplied name atom sequence.

 from AbstractPath
PathInterface normalize()

Normalize this path to its most canonical form.

 from AbstractPath
static AbsolutePathInterface fromString(string $path)

Creates a new absolute path from its string representation.
static AbsolutePathInterface fromAtoms(mixed<string> $atoms, boolean|null $hasTrailingSeparator = null)

Creates a new absolute path from a set of path atoms.
AbsolutePathInterface toAbsolute()

Get an absolute version of this path.
RelativePathInterface toRelative()

Get a relative version of this path.
boolean isRoot()

Determine whether this path is the root path.
boolean isParentOf(AbsolutePathInterface $path)

Determine if this path is the direct parent of the supplied path.
boolean isAncestorOf(AbsolutePathInterface $path)

Determine if this path is an ancestor of the supplied path.
RelativePathInterface relativeTo(AbsolutePathInterface $path)

Determine the shortest path from the supplied path to this path.
AbsolutePathInterface resolve(PathInterface $path)

Resolve the supplied path against this path.

Details

in AbstractPath at line 47
public __construct(mixed<string> $atoms, boolean|null $hasTrailingSeparator = null)

Construct a new path instance.

Parameters

mixed<string> $atoms The path atoms.
boolean|null $hasTrailingSeparator True if this path has a trailing separator.

Exceptions

InvalidPathAtomExceptionInterface If any of the supplied path atoms are invalid.

in AbstractPath at line 66
public array<integer,string> atoms()

Get the atoms of this path.

For example, the path '/foo/bar' has the atoms 'foo' and 'bar'.

Return Value

array<integer,string> The atoms of this path as an array of strings.

in AbstractPath at line 79
public string atomAt(integer $index)

Get a single path atom by index.

Parameters

integer $index The index to search for.

Return Value

string The path atom.

Exceptions

UndefinedAtomException If the index does not exist in this path's atoms.

in AbstractPath at line 98
public mixed atomAtDefault(integer $index, mixed $default = null)

Get a single path atom by index, falling back to a default if the index is undefined.

Parameters

integer $index The index to search for.
mixed $default The default value to return if no atom is defined for the supplied index.

Return Value

mixed The path atom, or $default if no atom is defined for the supplied index.

in AbstractPath at line 120
public array<integer,string> sliceAtoms(integer $index, integer|null $length = null)

Get a subset of the atoms of this path.

Parameters

integer $index The index of the first atom.
integer|null $length The maximum number of atoms.

Return Value

array<integer,string> An array of strings representing the subset of path atoms.

in AbstractPath at line 135
public boolean hasAtoms()

Determine if this path has any atoms.

Return Value

boolean True if this path has at least one atom.

in AbstractPath at line 145
public boolean hasTrailingSeparator()

Determine if this path has a trailing separator.

Return Value

boolean True if this path has a trailing separator.

at line 63
public string string()

Generate a string representation of this path.

Return Value

string A string representation of this path.

in AbstractPath at line 167
public string __toString()

Generate a string representation of this path.

Return Value

string A string representation of this path.

in AbstractPath at line 177
public string name()

Get this path's name.

Return Value

string The last path atom if one exists, otherwise an empty string.

in AbstractPath at line 196
public array<integer,string> nameAtoms()

Get this path's name atoms.

For example, the path name 'foo.bar' has the atoms 'foo' and 'bar'.

Return Value

array<integer,string> The atoms of this path's name as an array of strings.

in AbstractPath at line 209
public string nameAtomAt(integer $index)

Get a single path name atom by index.

Parameters

integer $index The index to search for.

Return Value

string The path name atom.

Exceptions

UndefinedAtomException If the index does not exist in this path's name atoms.

in AbstractPath at line 228
public mixed nameAtomAtDefault(integer $index, mixed $default = null)

Get a single path name atom by index, falling back to a default if the index is undefined.

Parameters

integer $index The index to search for.
mixed $default The default value to return if no atom is defined for the supplied index.

Return Value

mixed The path name atom, or $default if no atom is defined for the supplied index.

in AbstractPath at line 250
public array<integer,string> sliceNameAtoms(integer $index, integer|null $length = null)

Get a subset of this path's name atoms.

Parameters

integer $index The index of the first atom.
integer|null $length The maximum number of atoms.

Return Value

array<integer,string> An array of strings representing the subset of path name atoms.

in AbstractPath at line 265
public string nameWithoutExtension()

Get this path's name, excluding the last extension.

Return Value

string The last atom of this path, excluding the last extension. If this path has no atoms, an empty string is returned.

in AbstractPath at line 282
public string namePrefix()

Get this path's name, excluding all extensions.

Return Value

string The last atom of this path, excluding any extensions. If this path has no atoms, an empty string is returned.

in AbstractPath at line 294
public string|null nameSuffix()

Get all of this path's extensions.

Return Value

string|null The extensions of this path's last atom. If the last atom has no extensions, or this path has no atoms, this method will return null.

in AbstractPath at line 311
public string|null extension()

Get this path's last extension.

Return Value

string|null The last extension of this path's last atom. If the last atom has no extensions, or this path has no atoms, this method will return null.

in AbstractPath at line 328
public boolean hasExtension()

Determine if this path has any extensions.

Return Value

boolean True if this path's last atom has any extensions.

in AbstractPath at line 341
public boolean contains(string $needle, boolean|null $caseSensitive = null)

Determine if this path contains a substring.

Parameters

string $needle The substring to search for.
boolean|null $caseSensitive True if case sensitive.

Return Value

boolean True if this path contains the substring.

in AbstractPath at line 365
public boolean startsWith(string $needle, boolean|null $caseSensitive = null)

Determine if this path starts with a substring.

Parameters

string $needle The substring to search for.
boolean|null $caseSensitive True if case sensitive.

Return Value

boolean True if this path starts with the substring.

in AbstractPath at line 389
public boolean endsWith(string $needle, boolean|null $caseSensitive = null)

Determine if this path ends with a substring.

Parameters

string $needle The substring to search for.
boolean|null $caseSensitive True if case sensitive.

Return Value

boolean True if this path ends with the substring.

in AbstractPath at line 416
public boolean matches(string $pattern, boolean|null $caseSensitive = null, integer|null $flags = null)

Determine if this path matches a wildcard pattern.

Parameters

string $pattern The pattern to check against.
boolean|null $caseSensitive True if case sensitive.
integer|null $flags Additional flags.

Return Value

boolean True if this path matches the pattern.

in AbstractPath at line 441
public boolean matchesRegex(string $pattern, array $matches = null, integer|null $flags = null, integer|null $offset = null)

Determine if this path matches a regular expression.

Parameters

string $pattern The pattern to check against.
array $matches Populated with the pattern matches.
integer|null $flags Additional flags.
integer|null $offset Start searching from this byte offset.

Return Value

boolean True if this path matches the pattern.

in AbstractPath at line 471
public boolean nameContains(string $needle, boolean|null $caseSensitive = null)

Determine if this path's name contains a substring.

Parameters

string $needle The substring to search for.
boolean|null $caseSensitive True if case sensitive.

Return Value

boolean True if this path's name contains the substring.

in AbstractPath at line 495
public boolean nameStartsWith(string $needle, boolean|null $caseSensitive = null)

Determine if this path's name starts with a substring.

Parameters

string $needle The substring to search for.
boolean|null $caseSensitive True if case sensitive.

Return Value

boolean True if this path's name starts with the substring.

in AbstractPath at line 520
public boolean nameMatches(string $pattern, boolean|null $caseSensitive = null, integer|null $flags = null)

Determine if this path's name matches a wildcard pattern.

Parameters

string $pattern The pattern to check against.
boolean|null $caseSensitive True if case sensitive.
integer|null $flags Additional flags.

Return Value

boolean True if this path's name matches the pattern.

in AbstractPath at line 545
public boolean nameMatchesRegex(string $pattern, array $matches = null, integer|null $flags = null, integer|null $offset = null)

Determine if this path's name matches a regular expression.

Parameters

string $pattern The pattern to check against.
array $matches Populated with the pattern matches.
integer|null $flags Additional flags.
integer|null $offset Start searching from this byte offset.

Return Value

boolean True if this path's name matches the pattern.

in AbstractPath at line 574
public PathInterface parent(integer|null $numLevels = null)

Get the parent of this path a specified number of levels up.

Parameters

integer|null $numLevels The number of levels up. Defaults to 1.

Return Value

PathInterface The parent of this path $numLevels up.

in AbstractPath at line 595
public PathInterface stripTrailingSlash()

Strips the trailing slash from this path.

Return Value

PathInterface A new path instance with the trailing slash removed from this path. If this path has no trailing slash, the path is returned unmodified.

in AbstractPath at line 613
public PathInterface stripExtension()

Strips the last extension from this path.

Return Value

PathInterface A new path instance with the last extension removed from this path. If this path has no extensions, the path is returned unmodified.

in AbstractPath at line 623
public PathInterface stripNameSuffix()

Strips all extensions from this path.

Return Value

PathInterface A new path instance with all extensions removed from this path. If this path has no extensions, the path is returned unmodified.

in AbstractPath at line 637
public PathInterface joinAtoms($atom)

Joins one or more atoms to this path.

Parameters

$atom

Return Value

PathInterface A new path with the supplied atom(s) suffixed to this path.

Exceptions

InvalidPathAtomExceptionInterface If any joined atoms are invalid.

in AbstractPath at line 650
public PathInterface joinAtomSequence(mixed<string> $atoms)

Joins a sequence of atoms to this path.

Parameters

mixed<string> $atoms The path atoms to append.

Return Value

PathInterface A new path with the supplied sequence of atoms suffixed to this path.

Exceptions

InvalidPathAtomExceptionInterface If any joined atoms are invalid.

in AbstractPath at line 670
public PathInterface join(RelativePathInterface $path)

Joins the supplied path to this path.

Parameters

RelativePathInterface $path The path whose atoms should be joined to this path.

Return Value

PathInterface A new path with the supplied path suffixed to this path.

at line 73
public PathInterface joinTrailingSlash()

Adds a trailing slash to this path.

Return Value

PathInterface A new path instance with a trailing slash suffixed to this path.

in AbstractPath at line 702
public PathInterface joinExtensions($extension)

Joins one or more extensions to this path.

Parameters

$extension

Return Value

PathInterface A new path instance with the supplied extensions suffixed to this path.

Exceptions

InvalidPathAtomExceptionInterface If the suffixed extensions cause the atom to be invalid.

in AbstractPath at line 715
public PathInterface joinExtensionSequence(mixed<string> $extensions)

Joins a sequence of extensions to this path.

Parameters

mixed<string> $extensions The extensions to append.

Return Value

PathInterface A new path instance with the supplied extensions suffixed to this path.

Exceptions

InvalidPathAtomExceptionInterface If the suffixed extensions cause the atom to be invalid.

in AbstractPath at line 742
public PathInterface suffixName(string $suffix)

Suffixes this path's name with a supplied string.

Parameters

string $suffix The string to suffix to the path name.

Return Value

PathInterface A new path instance with the supplied string suffixed to the last path atom.

Exceptions

InvalidPathAtomExceptionInterface If the suffix causes the atom to be invalid.

in AbstractPath at line 760
public PathInterface prefixName(string $prefix)

Prefixes this path's name with a supplied string.

Parameters

string $prefix The string to prefix to the path name.

Return Value

PathInterface A new path instance with the supplied string prefixed to the last path atom.

Exceptions

InvalidPathAtomExceptionInterface If the prefix causes the atom to be invalid.

in AbstractPath at line 779
public PathInterface replace(integer $index, mixed<string> $replacement, integer|null $length = null)

Replace a section of this path with the supplied atom sequence.

Parameters

integer $index The start index of the replacement.
mixed<string> $replacement The replacement atom sequence.
integer|null $length The number of atoms to replace. If $length is null, the entire remainder of the path will be replaced.

Return Value

PathInterface A new path instance that has a portion of this path's atoms replaced with a different sequence of atoms.

in AbstractPath at line 806
public PathInterface replaceName(string $name)

Replace this path's name.

Parameters

string $name The new path name.

Return Value

PathInterface A new path instance with the supplied name replacing the existing one.

in AbstractPath at line 835
public PathInterface replaceNameWithoutExtension(string $nameWithoutExtension)

Replace this path's name, but keep the last extension.

Parameters

string $nameWithoutExtension The replacement string.

Return Value

PathInterface A new path instance with the supplied name replacing the portion of the existing name preceding the last extension.

in AbstractPath at line 854
public PathInterface replaceNamePrefix(string $namePrefix)

Replace this path's name, but keep any extensions.

Parameters

string $namePrefix The replacement string.

Return Value

PathInterface A new path instance with the supplied name prefix replacing the existing one.

in AbstractPath at line 866
public PathInterface replaceNameSuffix(string|null $nameSuffix)

Replace all of this path's extensions.

Parameters

string|null $nameSuffix The replacement string, or null to remove all extensions.

Return Value

PathInterface A new path instance with the supplied name suffix replacing the existing one.

in AbstractPath at line 898
public PathInterface replaceExtension(string|null $extension)

Replace this path's last extension.

Parameters

string|null $extension The replacement string, or null to remove the last extension.

Return Value

PathInterface A new path instance with the supplied extension replacing the existing one.

in AbstractPath at line 938
public PathInterface replaceNameAtoms(integer $index, mixed<string> $replacement, integer|null $length = null)

Replace a section of this path's name with the supplied name atom sequence.

Parameters

integer $index The start index of the replacement.
mixed<string> $replacement The replacement name atom sequence.
integer|null $length The number of atoms to replace. If $length is null, the entire remainder of the path name will be replaced.

Return Value

PathInterface A new path instance that has a portion of this name's atoms replaced with a different sequence of atoms.

in AbstractPath at line 959
public PathInterface normalize()

Normalize this path to its most canonical form.

Return Value

PathInterface The normalized path.

at line 27
static public AbsolutePathInterface fromString(string $path)

Creates a new absolute path from its string representation.

Parameters

string $path The string representation of the absolute path.

Return Value

AbsolutePathInterface The newly created absolute path.

Exceptions

NonAbsolutePathException If the supplied string represents a non-absolute path.

at line 47
static public AbsolutePathInterface fromAtoms(mixed<string> $atoms, boolean|null $hasTrailingSeparator = null)

Creates a new absolute path from a set of path atoms.

Parameters

mixed<string> $atoms The path atoms.
boolean|null $hasTrailingSeparator True if the path has a trailing separator.

Return Value

AbsolutePathInterface The newly created absolute path.

Exceptions

InvalidPathAtomExceptionInterface If any of the supplied atoms are invalid.
InvalidPathStateException If the supplied arguments would produce an invalid path.

at line 91
public AbsolutePathInterface toAbsolute()

Get an absolute version of this path.

If this path is relative, a new absolute path with equivalent atoms will be returned. Otherwise, this path will be retured unaltered.

Return Value

AbsolutePathInterface An absolute version of this path.

Exceptions

InvalidPathStateException If absolute conversion is not possible for this path.

at line 105
public RelativePathInterface toRelative()

Get a relative version of this path.

If this path is absolute, a new relative path with equivalent atoms will be returned. Otherwise, this path will be retured unaltered.

Return Value

RelativePathInterface A relative version of this path.

Exceptions

EmptyPathException If this path has no atoms.

at line 123
public boolean isRoot()

Determine whether this path is the root path.

The root path is an absolute path with no atoms.

Return Value

boolean True if this path is the root path.

at line 135
public boolean isParentOf(AbsolutePathInterface $path)

Determine if this path is the direct parent of the supplied path.

Parameters

AbsolutePathInterface $path The child path.

Return Value

boolean True if this path is the direct parent of the supplied path.

at line 149
public boolean isAncestorOf(AbsolutePathInterface $path)

Determine if this path is an ancestor of the supplied path.

Parameters

AbsolutePathInterface $path The child path.

Return Value

boolean True if this path is an ancestor of the supplied path.

at line 170
public RelativePathInterface relativeTo(AbsolutePathInterface $path)

Determine the shortest path from the supplied path to this path.

For example, given path A equal to '/foo/bar', and path B equal to '/foo/baz', A relative to B would be '../bar'.

Parameters

AbsolutePathInterface $path The path that the generated path will be relative to.

Return Value

RelativePathInterface A relative path from the supplied path to this path.

at line 207
public AbsolutePathInterface resolve(PathInterface $path)

Resolve the supplied path against this path.

Parameters

PathInterface $path The path to resolve.

Return Value

AbsolutePathInterface The resolved path.