nubs / which
A library for locating commands in a PATH.
Installs: 6 854
Dependents: 4
Suggesters: 1
Security: 0
Stars: 5
Watchers: 2
Forks: 1
Open Issues: 0
Requires
- php: ~5.4 || ~7.0
Requires (Dev)
- brianium/habitat: ~1.0
- phpunit/phpunit: ~4.0
- satooshi/php-coveralls: ~0.6.1
- squizlabs/php_codesniffer: ~2.3
Suggests
- brianium/habitat: For better access to environment variables (e.g., for mocking).
This package is auto-updated.
Last update: 2024-10-12 21:36:36 UTC
README
A PHP library for locating commands in a PATH.
Requirements
This library requires PHP 5.6, or newer.
Installation
This package uses composer so you can just add
nubs/which
as a dependency to your composer.json
file or execute the
following command:
composer require nubs/which
Example
Here is a quick example to demonstrate how this library is generally meant to be used:
$locatorFactory = new \Nubs\Which\LocatorFactory\PlatformLocatorFactory(); $locator = $locatorFactory->create(); echo $locator->locate('php'); // /usr/bin/php
Usage
Constructing a Locator
There are several ways to create a locator. The preferred way is to use the
brianium/habitat constructor. Habitat
makes accessing the environment variables easy, even in cases where the $_ENV
superglobal isn't populated. You can use it like this:
$habitat = new \Habitat\Habitat(); $environment = $habitat->getEnvironment(); $locatorFactory = new \Nubs\Which\LocatorFactory\PlatformLocatorFactory(); $locator = $locatorFactory->create($environment);
Habitat environment is not necessary. Without passing an environment, PHP's
built-in getenv
will be used:
$locatorFactory = new \Nubs\Which\LocatorFactory\PlatformLocatorFactory(); $locator = $locatorFactory->create();
There are also two platform-specific factories in case you don't want to rely
on the platform detection in the PlatformLocatorFactory
. If you are on a
POSIXy system (e.g., Linux, OSX, BSD), you can use the PosixLocatorFactory
and if you are on a Windows system you can use the WindowsLocatorFactory
.
$locatorFactory = new \Nubs\Which\LocatorFactory\PosixLocatorFactory(); $locator = $locatorFactory->create(); // or $locatorFactory = new \Nubs\Which\LocatorFactory\WindowsLocatorFactory(); $locator = $locatorFactory->create();
Finally, if you want full control over the paths that are searched, you can use specify exactly which paths to use:
$paths = ['/opt/special/bin', '/usr/local/bin', '/usr/bin', '/bin']; $pathBuilder = new \Nubs\Which\PathBuilder\PosixPathBuilder($paths); $locator = new \Nubs\Which\Locator($pathBuilder); // or $paths = ['C:\\Windows\\System32', 'C:\\Windows']; $pathExtensions = ['.exe', '.com']; $pathBuilder = new \Nubs\Which\PathBuilder\WindowsPathBuilder( $paths, $pathExtensions ); $locator = new \Nubs\Which\Locator($pathBuilder);
Locating commands
The locator can find commands based off of its configured paths and will return
null
if the command could not be found:
$locatorFactory = new \Nubs\Which\LocatorFactory\PlatformLocatorFactory(); $locator = $locatorFactory->create(); echo $locator->locate('php'); // /usr/bin/php var_dump($locator->locate('asdf')); // NULL
It can also be given an absolute or a relative path, in which case the configured paths are ignored and pathing is done based off the current directory:
$locatorFactory = new \Nubs\Which\LocatorFactory\PlatformLocatorFactory(); $locator = $locatorFactory->create(); echo $locator->locate('/opt/php/bin/php'); // /opt/php/bin/php chdir('/opt/php'); echo $locator->locate('bin/php'); // /opt/php/bin/php
Finally, an additional locateAll
method is included. If a command exists at
multiple places on the PATH
, this will return all of them. It operates
under all the rules as the standard locate
method.
$locatorFactory = new \Nubs\Which\LocatorFactory\PlatformLocatorFactory(); $locator = $locatorFactory->create(); var_dump($locator->locateAll('php')); // array(2) { // [0] => // string(12) "/usr/bin/php" // [1] => // string(16) "/opt/php/bin/php" // } var_dump($locator->locate('asdf')); // array(0) { // } var_dump($locator->locateAll('/opt/php/bin/php')); // array(1) { // [0] => // string(16) "/opt/php/bin/php" // } chdir('/opt/php'); var_dump($locator->locateAll('bin/php')); // array(1) { // [0] => // string(16) "/opt/php/bin/php" // }
CLI Interface
There is also a CLI interface for both POSIX systems and Windows that imitates
the standard which command. It is available as
nubs/which-cli
.
Why?
I created which in order to fill a hole I came across: Detecting whether a user has a certain command installed. Primarily this was for sensible, a library that picks the user's preferred editor/browser/pager and falls back to a sensible default if no preference is specified. which provides the ability for sensible to decide whether the different command choices exist. Read more about it on my blog.
Similar Projects
I am also aware of a node.js library with a similar role: node-which.
License
which is licensed under the MIT license. See LICENSE for the full license text.