ama-team / pathetic
A small library that helps in dealing with paths
Requires
- php: >= 5.4
Requires (Dev)
- allure-framework/allure-codeception: ^1.2
- codeception/codeception: ^2.3
- satooshi/php-coveralls: ^1.0
- symfony/console: <= 3.2.8
This package is not auto-updated.
Last update: 2024-11-20 02:59:16 UTC
README
Pathetic is a simple PHP library consisting just of couple of classes. It is aimed to help with platform-independent path work, so you can run the same code, fnmatch checks and comparisons regardless of specific machine your project is running on.
And yes, it is influenced by java.nio.Path
.
Installation
composer require ama-team/pathetic
Usage
You start with classic string and Path::parse
method:
use AmaTeam\Pathetic\Path; $path = Path::parse('beverages/soda'); $path = Path::parse('file://beverages/soda'); $path = Path::parse('c:\\beverages\\soda', Path::PLATFORM_WINDOWS); $path = Path::parse('c:/beverages/soda', Path::PLATFORM_WINDOWS); $path = Path::parse('custom-scheme://c:/beverages/soda', Path::PLATFORM_WINDOWS);
Second argument should be used only when you operate with paths for specific platform - by default, it is calculated automatically.
After you've obtained path instance, you can simply convert it to string to get consistent-delimiter representation:
$path = Path::parse('file://beverages\\soda'); echo (string) $path; // file://beverages/soda
This will save you from awkward moments when you append
directory/file
to windows path and then try to compare it with path
received from OS (which will contain directory\file
instead), also,
it makes it pretty easy to use fnmatch
glob patterns
platform-independently.
If you ever to need platform-consistent representation, you may use
toPlatformString()
method:
echo $path->toPlatformString(); // file://beverages\\soda
Except for those basic operations, Pathetic allows basic path normalization, path concatenation (resolution), path relativization and path comparison.
$path = Path::parse('/node/directory//./../leaf'); echo (string) $path; # /node/directory//./../leaf echo $path->normalize(); # /node/leaf $path->isAbsolute(); # true $node = Path::parse('/node'); $leaf = Path::parse('leaf'); $other = $node->resolve($leaf); # /node/leaf $path->isChildOf($node); # true $path->isSiblingOf($other); # true $path->equals($other); # true echo (string) $path->getParent(); # /node echo (string) $node->relativize($path); # leaf foreach ($path->iterator() as $entry) { echo (string) $entry; # / # /node # /node/leaf }
At last, there are some helper methods you may want to use:
$path = Path::parse('file://c:/node/directory', Path::PLATFORM_WINDOWS); $path = $path->withoutScheme()->withRoot('d:'); echo $path->getRoot(); # d: echo $path->getScheme(); # null echo $path->getSeparator(); # \ - because of windows platform
Major notes
All path operations are non-destructive, and all path instances are
immutable - whenever #normalize()
, #relativize()
or #withRoot()
are called, new object is created instead of modifying old one.
There is edge case with current directory - while one may expect
that normalized relative path of current directory will render down
to dot ('.'
), this won't happen - it will be rendered to empty string
(''
). However, while you don't call for normalization, your path will
stay as-is.
Windows has two types of absolute paths - with and without drive
letter, (\Users
and C:\Users
, for example). Both types are
treated as absolute by Pathetic - it's up to end user to determine if
he or she has to specify drive letter to not to inherit it from current
working directory. This is, of course, a drawback, but unless that
absolute path is inherited from user input - which should be
intentional thing - that shouldn't happen.