jstewmc / path
A class for handling paths in PHP
Requires (Dev)
- phpunit/phpunit: 4.2.*
This package is auto-updated.
Last update: 2024-10-29 04:30:58 UTC
README
A class for dealing with string paths in PHP.
A path is a route through a hierarchy, for example, a folder in a file system or a category in a department tree.
$path = new Path('foo/bar/baz'); $path->getSegment('first'); // returns 'foo' $path->getSegment(1); // returns 'bar' $path-appendSegment('qux'); // path becomes 'foo/bar/baz/qux' $path->prependSegment('quux'); // path becomes 'quux/foo/bar/baz/qux' echo $path; // prints 'quux/foo/bar/baz/qux'
Feel free to check out the API documentation, report an issue, contribute, or ask a question.
Segments
A path is composed of segments. Each segment represents a step in the path. For example, the path foo/bar/baz
has three segments: foo
, bar
, and baz
.
Segments are indexed starting with 0. So, in the path foo/bar/baz
, the index of foo
is 0. The index of bar
is 1, and the index of baz
is 2.
Most methods that use a segment's index as an argument will accept an offset. An offset can be positive (that many places from the beginning of the path) or negative (that many places from the end of the path). For example, an offset of 1
is the second segment in the path, and an offset of -1
is the last segment in the path. In addition, most methods accept the special strings first
and last
.
You can append, prepend, insert, set, and unset a path's segments:
$path = new Path(); $path->appendSegment('foo'); // path becomes "foo" $path->prependSegment('bar'); // path becomes "bar/foo" $path->insertSegment(1, 'baz'); // path becomes "bar/baz/foo" $path->setSegment(-1, 'qux'); // path becomes "bar/baz/qux" $path->unsetSegment('last'); // path becomes "bar/baz" echo $path; // prints "bar/baz"
The example above uses separate method calls. However, you can chain most of the methods:
$path = new Path(); $path->appendSegment('foo')->prependSegment('bar')->insertSegment(1, 'baz'); echo $path; // prints "bar/baz/foo"
Whenever a Path is used as a string, it will, no surprise, return the path as a string:
$path = new Path('foo/bar/baz'); (string) $path; // returns "foo/bar/baz" echo $path; // returns "foo/bar/baz" $path .''; // returns "foo/bar/baz"
You can get, find, and verify a segment by it's value or offset:
$path = new Path('foo/bar/baz'); // get the index of the 'foo' segment $path->getIndex('foo'); // returns 0 $path->getIndex('qux'); // returns false ('qux' does not exist) // get the value of the 0-th (aka, 'first') segment $path->getSegment(0); // returns 'foo' $path->getSegment('first'); // returns 'foo' $path->getSegment(999); // throws OutOfBoundsException // does the path have a segment at the 1-st index? $path->hasIndex(1); // returns true $path->hasIndex(999); // returns false // does the path have the given segments (at any index)? $path->hasSegment('bar'); // returns true $path->hassegment('qux'); // returns false // does the path have the given segments (at the given indices)? $path->hasSegment('foo', 0); // returns true $path->hasSegment('foo', 'first'); // returns true $path->hasSegment('foo', 1); // returns false ('foo' is 0-th) $path->hasSegment('qux', 'last'); // returns false ('qux' does not exist)
Path
You can also slice and reverse a path.
You can slice and reverse the current path:
$path = new Path('foo/bar/baz'); $path->slice(1); echo $path; // prints "bar/baz" $path->reverse(); echo $path; // prints "baz/bar"
Or, you can slice and reverse a clone:
$a = new Path('foo/bar/baz'); $b = $a->getSlice(1); echo $a; // prints 'foo/bar/baz' echo $b; // prints 'bar/baz' $c = $a->getReverse(); echo $a; // prints 'foo/bar/baz' echo $c; // prints 'baz/bar/foo'
Tests
Tests cover more than 90% of the code. I'm not exactly sure what's missing, because I'm pretty sure I wrote tests for everything. If you see something missing, let me know.
Contributing
Feel free to contribute your own improvements:
- Fork
- Clone
- PHPUnit
- Branch
- PHPUnit
- Code
- PHPUnit
- Commit
- Push
- Pull request
- Relax and eat a Paleo muffin
See CONTRIBUTING.md for details.
Author
Jack Clayton - clayjs0@gmail.com.
License
Url is released under the MIT License. See the LICENSE file for details.
History
You can view the (short) history of the Url project in the CHANGELOG.md file.