eloquent/pathogen API
Interface

Eloquent\Pathogen\PathInterface

interface PathInterface

The interface implemented by all Pathogen paths.

Methods

array<integer,string> atoms()

Get the atoms of this path.
string atomAt(integer $index)

Get a single path atom by index.
mixed atomAtDefault(integer $index, mixed $default = null)

Get a single path atom by index, falling back to a default if the index is undefined.
array<integer,string> sliceAtoms(integer $index, integer|null $length = null)

Get a subset of the atoms of this path.
boolean hasAtoms()

Determine if this path has any atoms.
boolean hasTrailingSeparator()

Determine if this path has a trailing separator.
string string()

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

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

Get this path's name.
array<integer,string> nameAtoms()

Get this path's name atoms.
string nameAtomAt(integer $index)

Get a single path name atom by index.
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.
array<integer,string> sliceNameAtoms(integer $index, integer|null $length = null)

Get a subset of this path's name atoms.
string nameWithoutExtension()

Get this path's name, excluding the last extension.
string namePrefix()

Get this path's name, excluding all extensions.
string|null nameSuffix()

Get all of this path's extensions.
string|null extension()

Get this path's last extension.
boolean hasExtension()

Determine if this path has any extensions.
boolean contains(string $needle, boolean|null $caseSensitive = null)

Determine if this path contains a substring.
boolean startsWith(string $needle, boolean|null $caseSensitive = null)

Determine if this path starts with a substring.
boolean endsWith(string $needle, boolean|null $caseSensitive = null)

Determine if this path ends with a substring.
boolean matches(string $pattern, boolean|null $caseSensitive = null, integer|null $flags = null)

Determine if this path matches a wildcard pattern.
boolean matchesRegex(string $pattern, array $matches = null, integer|null $flags = null, integer|null $offset = null)

Determine if this path matches a regular expression.
boolean nameContains(string $needle, boolean|null $caseSensitive = null)

Determine if this path's name contains a substring.
boolean nameStartsWith(string $needle, boolean|null $caseSensitive = null)

Determine if this path's name starts with a substring.
boolean nameMatches(string $pattern, boolean|null $caseSensitive = null, integer|null $flags = null)

Determine if this path's name matches a wildcard pattern.
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.
PathInterface parent(integer|null $numLevels = null)

Get the parent of this path a specified number of levels up.
PathInterface stripTrailingSlash()

Strips the trailing slash from this path.
PathInterface stripExtension()

Strips the last extension from this path.
PathInterface stripNameSuffix()

Strips all extensions from this path.
PathInterface joinAtoms($atom)

Joins one or more atoms to this path.
PathInterface joinAtomSequence(mixed<string> $atoms)

Joins a sequence of atoms to this path.
PathInterface join(RelativePathInterface $path)

Joins the supplied path to this path.
PathInterface joinTrailingSlash()

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

Joins one or more extensions to this path.
PathInterface joinExtensionSequence(mixed<string> $extensions)

Joins a sequence of extensions to this path.
PathInterface suffixName(string $suffix)

Suffixes this path's name with a supplied string.
PathInterface prefixName(string $prefix)

Prefixes this path's name with a supplied string.
PathInterface replace(integer $index, mixed<string> $replacement, integer|null $length = null)

Replace a section of this path with the supplied atom sequence.
PathInterface replaceName(string $name)

Replace this path's name.
PathInterface replaceNameWithoutExtension(string $nameWithoutExtension)

Replace this path's name, but keep the last extension.
PathInterface replaceNamePrefix(string $namePrefix)

Replace this path's name, but keep any extensions.
PathInterface replaceNameSuffix(string|null $nameSuffix)

Replace all of this path's extensions.
PathInterface replaceExtension(string|null $extension)

Replace this path's last extension.
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.
AbsolutePathInterface toAbsolute()

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

Get a relative version of this path.
PathInterface normalize()

Normalize this path to its most canonical form.

Details

at line 26
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.

at line 36
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.

at line 47
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.

at line 57
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.

at line 64
public boolean hasAtoms()

Determine if this path has any atoms.

Return Value

boolean True if this path has at least one atom.

at line 71
public boolean hasTrailingSeparator()

Determine if this path has a trailing separator.

Return Value

boolean True if this path has a trailing separator.

at line 78
public string string()

Generate a string representation of this path.

Return Value

string A string representation of this path.

at line 85
public string __toString()

Generate a string representation of this path.

Return Value

string A string representation of this path.

at line 92
public string name()

Get this path's name.

Return Value

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

at line 101
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.

at line 111
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.

at line 122
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.

at line 132
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.

at line 139
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.

at line 146
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.

at line 153
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.

at line 160
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.

at line 167
public boolean hasExtension()

Determine if this path has any extensions.

Return Value

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

at line 177
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.

at line 187
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.

at line 197
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.

at line 208
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.

at line 220
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.

at line 235
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.

at line 245
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.

at line 256
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.

at line 268
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.

at line 282
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.

at line 289
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.

at line 296
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.

at line 303
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.

at line 314
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.

at line 324
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.

at line 333
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 340
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.

at line 351
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.

at line 361
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.

at line 371
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.

at line 381
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.

at line 392
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.

at line 401
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.

at line 410
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.

at line 419
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.

at line 428
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.

at line 437
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.

at line 449
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.

at line 460
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 471
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 478
public PathInterface normalize()

Normalize this path to its most canonical form.

Return Value

PathInterface The normalized path.