├── LICENSE.md
├── README.md
├── composer.json
├── phpstan.neon
└── src
    ├── Internal
        ├── CacheReader.php
        ├── ConfigReader.php
        └── ReaderInterface.php
    ├── Locator.php
    └── Resolver
        ├── LinuxPathResolver.php
        ├── MacOSPathResolver.php
        ├── PathResolver.php
        ├── PathResolverInterface.php
        ├── UnixAwareResolver.php
        └── WindowsPathResolver.php


/LICENSE.md:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright © Kirill Nesmeyanov
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Bin Locator
 2 | 
 3 | <p align="center">
 4 |     <a href="https://packagist.org/packages/ffi/location"><img src="https://poser.pugx.org/ffi/location/require/php?style=for-the-badge" alt="PHP 8.1+"></a>
 5 |     <a href="https://packagist.org/packages/ffi/location"><img src="https://poser.pugx.org/ffi/location/version?style=for-the-badge" alt="Latest Stable Version"></a>
 6 |     <a href="https://packagist.org/packages/ffi/location"><img src="https://poser.pugx.org/ffi/location/v/unstable?style=for-the-badge" alt="Latest Unstable Version"></a>
 7 |     <a href="https://packagist.org/packages/ffi/location"><img src="https://poser.pugx.org/ffi/location/downloads?style=for-the-badge" alt="Total Downloads"></a>
 8 |     <a href="https://raw.githubusercontent.com/php-ffi/location/master/LICENSE.md"><img src="https://poser.pugx.org/ffi/location/license?style=for-the-badge" alt="License MIT"></a>
 9 | </p>
10 | <p align="center">
11 |     <a href="https://github.com/php-ffi/location/actions"><img src="https://github.com/php-ffi/location/workflows/build/badge.svg"></a>
12 | </p>
13 | 
14 | Library for searching binary files in the operating system.
15 | 
16 | ## Requirements
17 | 
18 | - PHP >= 7.4
19 | 
20 | ## Installation
21 | 
22 | Library is available as composer repository and can be installed using the 
23 | following command in a root of your project.
24 | 
25 | ```sh
26 | $ composer require ffi/location
27 | ```
28 | 
29 | ## Usage
30 | 
31 | ### Existence Check
32 | 
33 | Checking the library for existence.
34 | 
35 | ```php
36 | use FFI\Location\Locator;
37 | 
38 | $exists = Locator::exists('libGL.so');
39 | // Expected true in the case that the binary exists and false otherwise
40 | ```
41 | 
42 | ### Binary Pathname
43 | 
44 | Getting the full path to the library.
45 | 
46 | ```php
47 | use FFI\Location\Locator;
48 | 
49 | $pathname = Locator::pathname('libGL.so');
50 | // Expected "/usr/lib/x86_64-linux-gnu/libGL.so.1.7.0" or null
51 | // in the case that the library cannot be found
52 | ```
53 | 
54 | ### Binary Resolving
55 | 
56 | Checking multiple names to find the most suitable library.
57 | 
58 | ```php
59 | use FFI\Location\Locator;
60 | 
61 | $pathname = Locator::resolve('example.so', 'test.so', 'libvulkan.so');
62 | // Expected "/usr/lib/x86_64-linux-gnu/libvulkan.so.1.2.131" or null
63 | // in the case that the library cannot be found
64 | ```
65 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "ffi/location",
 3 |     "type": "library",
 4 |     "description": "PHP library for determining the physical location of binaries",
 5 |     "license": "MIT",
 6 |     "keywords": ["ffi", "bin", "location", "utility"],
 7 |     "support": {
 8 |         "source": "https://github.com/php-ffi/location",
 9 |         "issues": "https://github.com/php-ffi/location/issues",
10 |         "docs": "https://github.com/php-ffi/location/blob/master/README.md"
11 |     },
12 |     "authors": [
13 |         {
14 |             "name": "Nesmeyanov Kirill",
15 |             "email": "nesk@xakep.ru",
16 |             "homepage": "https://nesk.me",
17 |             "role": "maintainer"
18 |         }
19 |     ],
20 |     "require": {
21 |         "php": "^7.4|^8.0"
22 |     },
23 |     "autoload": {
24 |         "psr-4": {
25 |             "FFI\\Location\\": "src"
26 |         }
27 |     },
28 |     "require-dev": {
29 |         "phpunit/phpunit": "^9.5",
30 |         "friendsofphp/php-cs-fixer": "^3.53",
31 |         "phpstan/phpstan": "^2.0",
32 |         "phpstan/phpstan-deprecation-rules": "^2.0",
33 |         "phpstan/phpstan-strict-rules": "^2.0"
34 |     },
35 |     "autoload-dev": {
36 |         "psr-4": {
37 |             "FFI\\Location\\Tests\\": "tests"
38 |         }
39 |     },
40 |     "config": {
41 |         "optimize-autoloader": true,
42 |         "preferred-install": {
43 |             "*": "dist"
44 |         },
45 |         "sort-packages": true
46 |     },
47 |     "scripts": {
48 |         "test": ["@test:unit"],
49 |         "test:unit": "phpunit --testdox --testsuite=unit",
50 |         "linter": "@linter:check",
51 |         "linter:check": "phpstan analyse --configuration phpstan.neon",
52 |         "linter:baseline": "@linter:check -- --generate-baseline",
53 |         "phpcs": "@phpcs:check",
54 |         "phpcs:check": "@phpcs:fix --dry-run",
55 |         "phpcs:fix": "php-cs-fixer fix --config=.php-cs-fixer.php --allow-risky=yes --verbose --diff"
56 |     },
57 |     "extra": {
58 |         "branch-alias": {
59 |             "dev-main": "1.0.x-dev",
60 |             "dev-master": "1.0.x-dev"
61 |         }
62 |     },
63 |     "minimum-stability": "dev",
64 |     "prefer-stable": true
65 | }
66 | 


--------------------------------------------------------------------------------
/phpstan.neon:
--------------------------------------------------------------------------------
 1 | includes:
 2 |   - phar://phpstan.phar/conf/bleedingEdge.neon
 3 |   - vendor/phpstan/phpstan-deprecation-rules/rules.neon
 4 |   - vendor/phpstan/phpstan-strict-rules/rules.neon
 5 | parameters:
 6 |   level: max
 7 |   phpVersion:
 8 |     min: 70400
 9 |     max: 80400
10 |   parallel:
11 |     jobSize: 20
12 |     maximumNumberOfProcesses: 4
13 |     minimumNumberOfJobsPerProcess: 2
14 |   paths:
15 |     - src
16 |   tmpDir: vendor/.cache.phpstan
17 |   rememberPossiblyImpureFunctionValues: false
18 |   checkTooWideReturnTypesInProtectedAndPublicMethods: true
19 |   checkImplicitMixed: true
20 |   checkBenevolentUnionTypes: true
21 |   reportPossiblyNonexistentGeneralArrayOffset: true
22 |   reportPossiblyNonexistentConstantArrayOffset: true
23 |   reportAlwaysTrueInLastCondition: true
24 |   reportAnyTypeWideningInVarTag: true
25 |   checkMissingOverrideMethodAttribute: false
26 |   inferPrivatePropertyTypeFromConstructor: true
27 |   tipsOfTheDay: false
28 |   checkMissingCallableSignature: true
29 | 


--------------------------------------------------------------------------------
/src/Internal/CacheReader.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace FFI\Location\Internal;
 6 | 
 7 | /**
 8 |  * @internal cacheReader is an internal library class, please do not use it in your code
 9 |  * @psalm-internal FFI\Location
10 |  */
11 | final class CacheReader implements ReaderInterface
12 | {
13 |     /**
14 |      * @var string
15 |      */
16 |     private const EXEC_CMD = 'strings -n5 %s';
17 | 
18 |     /**
19 |      * @var array<string>
20 |      */
21 |     private array $paths = [];
22 | 
23 |     private string $pathname;
24 | 
25 |     public function __construct(string $pathname)
26 |     {
27 |         $this->pathname = $pathname;
28 |     }
29 | 
30 |     private function exec(): string
31 |     {
32 |         if (!\is_file($this->pathname)) {
33 |             return '';
34 |         }
35 | 
36 |         if (!\function_exists('\\shell_exec')) {
37 |             return '';
38 |         }
39 | 
40 |         /** @psalm-suppress ForbiddenCode */
41 |         $output = @\shell_exec(\sprintf(self::EXEC_CMD, \escapeshellarg($this->pathname)));
42 | 
43 |         if (!\is_string($output)) {
44 |             return '';
45 |         }
46 | 
47 |         return $output;
48 |     }
49 | 
50 |     /**
51 |      * @return array<string>
52 |      */
53 |     private function collect(): array
54 |     {
55 |         $paths = [];
56 | 
57 |         foreach (\explode("\n", $this->exec()) as $library) {
58 |             $directory = \dirname($library);
59 |             $isDirectory = $directory !== '.' && $directory !== '';
60 | 
61 |             if ($isDirectory && !\in_array($directory, $paths, true)) {
62 |                 $paths[] = $directory;
63 |             }
64 |         }
65 | 
66 |         return $paths;
67 |     }
68 | 
69 |     public function getIterator(): \Traversable
70 |     {
71 |         if (!\is_file($this->pathname)) {
72 |             return new \EmptyIterator();
73 |         }
74 | 
75 |         if ($this->paths === []) {
76 |             $this->paths = $this->collect();
77 |         }
78 | 
79 |         return new \ArrayIterator($this->paths);
80 |     }
81 | }
82 | 


--------------------------------------------------------------------------------
/src/Internal/ConfigReader.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace FFI\Location\Internal;
 6 | 
 7 | /**
 8 |  * @internal configReader is an internal library class, please do not use it in your code
 9 |  * @psalm-internal FFI\Location
10 |  */
11 | final class ConfigReader implements ReaderInterface
12 | {
13 |     private string $pathname;
14 | 
15 |     public function __construct(string $pathname)
16 |     {
17 |         $this->pathname = $pathname;
18 |     }
19 | 
20 |     public function getIterator(): \Traversable
21 |     {
22 |         return $this->read($this->pathname);
23 |     }
24 | 
25 |     /**
26 |      * @return \Traversable<array-key, string>
27 |      */
28 |     private function read(string $pathname): \Traversable
29 |     {
30 |         if (!\is_file($pathname) || !\is_readable($pathname)) {
31 |             return;
32 |         }
33 | 
34 |         $fp = @\fopen($pathname, 'rb');
35 | 
36 |         if ($fp === false) {
37 |             return;
38 |         }
39 | 
40 |         while (!\feof($fp)) {
41 |             $line = (string) \fgets($fp);
42 | 
43 |             switch (true) {
44 |                 case \str_starts_with($line, 'include'):
45 |                     $references = \glob(\trim((string) \substr($line, 8)));
46 | 
47 |                     if (\is_iterable($references)) {
48 |                         foreach ($references as $config) {
49 |                             yield from $this->read($config);
50 |                         }
51 |                     }
52 |                     break;
53 | 
54 |                 case \str_starts_with($line, '/'):
55 |                     yield \trim($line);
56 |                     break;
57 |             }
58 |         }
59 | 
60 |         \fclose($fp);
61 |     }
62 | }
63 | 


--------------------------------------------------------------------------------
/src/Internal/ReaderInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace FFI\Location\Internal;
 6 | 
 7 | /**
 8 |  * @internal readerInterface is an internal library interface, please do not use it in your code
 9 |  * @psalm-internal FFI\Location\Internal
10 |  *
11 |  * @template-extends \IteratorAggregate<array-key, string>
12 |  */
13 | interface ReaderInterface extends \IteratorAggregate {}
14 | 


--------------------------------------------------------------------------------
/src/Locator.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace FFI\Location;
 6 | 
 7 | use FFI\Location\Resolver\LinuxPathResolver;
 8 | use FFI\Location\Resolver\MacOSPathResolver;
 9 | use FFI\Location\Resolver\PathResolverInterface;
10 | use FFI\Location\Resolver\WindowsPathResolver;
11 | 
12 | final class Locator
13 | {
14 |     private static ?PathResolverInterface $resolver = null;
15 | 
16 |     private static function resolver(): PathResolverInterface
17 |     {
18 |         if (self::$resolver === null) {
19 |             switch (\PHP_OS_FAMILY) {
20 |                 case 'Windows':
21 |                     return self::$resolver = new WindowsPathResolver();
22 | 
23 |                 case 'Darwin':
24 |                     return self::$resolver = new MacOSPathResolver();
25 | 
26 |                 default:
27 |                     return self::$resolver = new LinuxPathResolver();
28 |             }
29 |         }
30 | 
31 |         return self::$resolver;
32 |     }
33 | 
34 |     public static function exists(string $name): bool
35 |     {
36 |         return self::pathname($name) !== null;
37 |     }
38 | 
39 |     /**
40 |      * @return non-empty-string|null
41 |      */
42 |     public static function pathname(string $name): ?string
43 |     {
44 |         if ($name === '') {
45 |             return null;
46 |         }
47 | 
48 |         if (\is_file($name)) {
49 |             /**
50 |              * Allow non-strict short ternary operator
51 |              *
52 |              * @var non-empty-string
53 |              *
54 |              * @phpstan-ignore ternary.shortNotAllowed
55 |              */
56 |             return \realpath($name) ?: $name;
57 |         }
58 | 
59 |         $resolver = self::resolver();
60 | 
61 |         return $resolver->resolve($name);
62 |     }
63 | 
64 |     /**
65 |      * @return non-empty-string|null
66 |      */
67 |     public static function resolve(string ...$libraries): ?string
68 |     {
69 |         foreach ($libraries as $library) {
70 |             $pathname = self::pathname($library);
71 | 
72 |             if ($pathname !== null) {
73 |                 return $pathname;
74 |             }
75 |         }
76 | 
77 |         return null;
78 |     }
79 | }
80 | 


--------------------------------------------------------------------------------
/src/Resolver/LinuxPathResolver.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace FFI\Location\Resolver;
 6 | 
 7 | /**
 8 |  * @internal this is an internal library class, please do not use it in your code
 9 |  * @psalm-internal FFI\Location
10 |  */
11 | final class LinuxPathResolver extends UnixAwareResolver
12 | {
13 |     protected function getLibDirectories(): iterable
14 |     {
15 |         // Allow non-strict short ternary operator
16 |         // @phpstan-ignore ternary.shortNotAllowed
17 |         yield \getcwd() ?: '.';
18 |         yield from $this->getEnvDirectories('LD_LIBRARY_PATH');
19 |         yield from $this->getLinkerDirectories();
20 |     }
21 | }
22 | 


--------------------------------------------------------------------------------
/src/Resolver/MacOSPathResolver.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace FFI\Location\Resolver;
 6 | 
 7 | /**
 8 |  * @internal this is an internal library class, please do not use it in your code
 9 |  * @psalm-internal FFI\Location
10 |  */
11 | final class MacOSPathResolver extends UnixAwareResolver
12 | {
13 |     protected function getLibDirectories(): iterable
14 |     {
15 |         // Allow non-strict short ternary operator
16 |         // @phpstan-ignore ternary.shortNotAllowed
17 |         yield \getcwd() ?: '.';
18 |         yield from $this->getEnvDirectories('DYLD_LIBRARY_PATH');
19 |         yield from $this->getEnvDirectories('DYLD_FALLBACK_LIBRARY_PATH');
20 |         yield from $this->getLinkerDirectories();
21 |     }
22 | }
23 | 


--------------------------------------------------------------------------------
/src/Resolver/PathResolver.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace FFI\Location\Resolver;
 6 | 
 7 | /**
 8 |  * @internal this is an internal library class, please do not use it in your code
 9 |  * @psalm-internal FFI\Location
10 |  */
11 | abstract class PathResolver implements PathResolverInterface
12 | {
13 |     /**
14 |      * @var array<non-empty-string, non-empty-string|null>
15 |      */
16 |     private array $paths = [];
17 | 
18 |     /**
19 |      * @return iterable<array-key, string>
20 |      */
21 |     abstract protected function getLibDirectories(): iterable;
22 | 
23 |     public function resolve(string $name): ?string
24 |     {
25 |         if (!isset($this->paths[$name])) {
26 |             foreach ($this->getLibDirectories() as $directory) {
27 |                 $pathname = $directory . '/' . $name;
28 | 
29 |                 if (\is_file($pathname)) {
30 |                     // Allow non-strict short ternary operator
31 |                     // @phpstan-ignore ternary.shortNotAllowed
32 |                     return $this->paths[$name] = \realpath($pathname) ?: $pathname;
33 |                 }
34 |             }
35 | 
36 |             return $this->paths[$name] = null;
37 |         }
38 | 
39 |         return $this->paths[$name];
40 |     }
41 | 
42 |     /**
43 |      * @param non-empty-string $env
44 |      * @param non-empty-string $delimiter
45 |      *
46 |      * @return iterable<array-key, non-empty-string>
47 |      */
48 |     protected function getEnvDirectories(string $env, string $delimiter = ':'): iterable
49 |     {
50 |         $value = $this->fetchEnvVariable($env);
51 | 
52 |         if ($value === null || $value === '') {
53 |             return [];
54 |         }
55 | 
56 |         foreach (\explode($delimiter, $value) as $path) {
57 |             $trimmed = \trim($path);
58 | 
59 |             if ($trimmed !== '') {
60 |                 yield $trimmed;
61 |             }
62 |         }
63 |     }
64 | 
65 |     /**
66 |      * @param non-empty-string $variable
67 |      */
68 |     private function fetchEnvVariable(string $variable): ?string
69 |     {
70 |         $value = $_ENV[$variable] ?? null;
71 | 
72 |         if (\is_string($value)) {
73 |             return $value;
74 |         }
75 | 
76 |         $value = $_SERVER[$variable] ?? null;
77 | 
78 |         if (\is_string($value)) {
79 |             return $value;
80 |         }
81 | 
82 |         $value = \getenv($variable);
83 | 
84 |         if (\is_string($value)) {
85 |             return $value;
86 |         }
87 | 
88 |         return null;
89 |     }
90 | }
91 | 


--------------------------------------------------------------------------------
/src/Resolver/PathResolverInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace FFI\Location\Resolver;
 6 | 
 7 | /**
 8 |  * @internal this is an internal library interface, please do not use it in your code
 9 |  * @psalm-internal FFI\Location
10 |  */
11 | interface PathResolverInterface
12 | {
13 |     /**
14 |      * @param non-empty-string $name
15 |      *
16 |      * @return non-empty-string|null
17 |      */
18 |     public function resolve(string $name): ?string;
19 | }
20 | 


--------------------------------------------------------------------------------
/src/Resolver/UnixAwareResolver.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace FFI\Location\Resolver;
 6 | 
 7 | use FFI\Location\Internal\CacheReader;
 8 | use FFI\Location\Internal\ConfigReader;
 9 | use FFI\Location\Internal\ReaderInterface;
10 | 
11 | /**
12 |  * @internal this is an internal library class, please do not use it in your code
13 |  * @psalm-internal FFI\Location
14 |  */
15 | abstract class UnixAwareResolver extends PathResolver
16 | {
17 |     /**
18 |      * Memoized linker directories.
19 |      *
20 |      * @var array<array-key, string>
21 |      */
22 |     private array $linkerDirectories = [];
23 | 
24 |     /**
25 |      * @return iterable<array-key, string>
26 |      */
27 |     protected function getLinkerDirectories(): iterable
28 |     {
29 |         if ($this->linkerDirectories === []) {
30 |             $reader = $this->getReader();
31 | 
32 |             if ($reader === null) {
33 |                 return [];
34 |             }
35 | 
36 |             foreach ($reader as $directory) {
37 |                 $this->linkerDirectories[] = $directory;
38 |             }
39 |         }
40 | 
41 |         yield from $this->linkerDirectories;
42 |     }
43 | 
44 |     private function getReader(): ?ReaderInterface
45 |     {
46 |         if (\is_file('/etc/ld.so.conf')) {
47 |             return new ConfigReader('/etc/ld.so.conf');
48 |         }
49 | 
50 |         if (\is_file('/etc/ld.so.cache')) {
51 |             return new CacheReader('/etc/ld.so.cache');
52 |         }
53 | 
54 |         return null;
55 |     }
56 | }
57 | 


--------------------------------------------------------------------------------
/src/Resolver/WindowsPathResolver.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace FFI\Location\Resolver;
 6 | 
 7 | /**
 8 |  * @internal this is an internal library class, please do not use it in your code
 9 |  * @psalm-internal FFI\Location
10 |  */
11 | final class WindowsPathResolver extends PathResolver
12 | {
13 |     protected function getLibDirectories(): iterable
14 |     {
15 |         // Allow non-strict short ternary operator
16 |         // @phpstan-ignore ternary.shortNotAllowed
17 |         yield \getcwd() ?: '.';
18 |         yield from $this->getEnvDirectories('PATH', ';');
19 |     }
20 | }
21 | 


--------------------------------------------------------------------------------