README

A service to help easily find plugins for your services, using Composer metadata!

Requirements

• PHP ^8.5

Install

composer require myerscode/package-discovery

Usage

Publishing projects add metadata to their composer.json extra field. A consuming project instantiates a Finder and uses it to discover, inspect, and locate those packages.

Publishing a package

Add an object under your namespace key in the extra field of composer.json:

{
  "name": "myerscode/corgis",
  "extra": {
    "myerscode": {
      "corgis": ["Gerald", "Rupert"],
      "providers": [
        "Myerscode\\Corgis\\CorgiProvider"
      ]
    }
  }
}

Discovering packages

Pass the root path of your project (where vendor/ lives) to Finder, then call discover() with your namespace.

$finder = new Finder(__DIR__);

$packages = $finder->discover('myerscode');

Returns an array keyed by package name:

[
    'myerscode/corgis' => [
        'corgis' => ['Gerald', 'Rupert'],
        'providers' => ['Myerscode\\Corgis\\CorgiProvider'],
    ],
]

You can also discover across multiple namespaces at once by passing an array. Results are merged by package name:

$packages = $finder->discover(['myerscode', 'corgi']);

Avoiding discovery

To exclude a specific package from discovery, add it to the avoid list under your namespace in the consuming project's composer.json:

{
  "name": "myerscode/demo-project",
  "extra": {
    "myerscode": {
      "avoid": ["myerscode/corgis"]
    }
  }
}

To skip all discoverable packages entirely, use *:

{
  "name": "myerscode/demo-project",
  "extra": {
    "myerscode": {
      "avoid": ["*"]
    }
  }
}

Discovering all packages with extras

discoverAll() returns every installed package that has any extra metadata, regardless of namespace:

$packages = $finder->discoverAll();

// [
//     'myerscode/corgis' => [
//         'myerscode' => [...],
//     ],
// ]

Discovering by Composer package type

discoverByType() filters discovery results to packages of a specific Composer type:

// Only return packages of type "composer-plugin" that register under the myerscode namespace
$plugins = $finder->discoverByType('composer-plugin', 'myerscode');

// Also works with multiple namespaces
$plugins = $finder->discoverByType('composer-plugin', ['myerscode', 'corgi']);

Checking if a package is installed

has() returns true if the named package is present in the installed packages list:

if ($finder->has('myerscode/corgis')) {
    // package is installed
}

Listing installed package names

installedPackageNames() returns a flat array of all installed package names:

$names = $finder->installedPackageNames();

// ['myerscode/utilities-bags', 'myerscode/corgis', ...]

Locating a package

locate() returns the absolute path to a package on disk. Throws PackageNotFoundException if the package is unknown or its directory cannot be resolved:

$path = $finder->locate('myerscode/corgis');

// /var/www/project/vendor/myerscode/corgis

Getting package extras

packageExtra() returns the full extra array for a package:

$extra = $finder->packageExtra('myerscode/corgis');

// [
//     'myerscode' => [
//         'corgis' => ['Gerald', 'Rupert'],
//         'providers' => ['Myerscode\\Corgis\\CorgiProvider'],
//     ],
// ]

Getting package meta for a service

packageMetaForService() returns only the extra data scoped to a specific namespace key:

$meta = $finder->packageMetaForService('myerscode/corgis', 'myerscode');

// [
//     'corgis' => ['Gerald', 'Rupert'],
//     'providers' => ['Myerscode\\Corgis\\CorgiProvider'],
// ]

Exceptions

All lookup methods (locate, packageExtra, packageMetaForService) throw Myerscode\PackageDiscovery\Exceptions\PackageNotFoundException when the requested package is not found. PackageNotFoundException extends InvalidArgumentException, so existing catch blocks continue to work.

use Myerscode\PackageDiscovery\Exceptions\PackageNotFoundException;

try {
    $path = $finder->locate('vendor/unknown-package');
} catch (PackageNotFoundException $e) {
    // handle missing package
}

Issues

Bug reports and feature requests can be submitted on the Github Issue Tracker.

Contributing

See the Myerscode contributing page for information.

License

The MIT License (MIT). Please see License File for more information.