PHPackages milpa/plugin - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. milpa/plugin ActiveLibrary[Framework](/categories/framework) milpa/plugin ============ The plugin system of the Milpa PHP framework: the PluginsManager runtime that boots and orders plugins, the registry port with its file and in-memory adapters, PluginBase, the installer over GitHub-native distribution (source parsing, semver-constrained release resolution, zipball download), milpa.json manifest reading/validation, dependency resolution, milpa.lock management, and the plugin migration runner. v0.11.2(1w ago)01.9k↑130.6%6Apache-2.0PHPPHP >=8.3CI passing Since Jul 8Pushed 1mo agoCompare [ Source](https://github.com/getmilpa/plugin)[ Packagist](https://packagist.org/packages/milpa/plugin)[ RSS](/packages/milpa-plugin/feed)WikiDiscussions main Synced 1w ago READMEChangelog (4)Dependencies (24)Versions (22)Used By (6) [ ![Milpa](https://raw.githubusercontent.com/getmilpa/core/main/art/lockup/milpa-lockup-v-color-light.svg) ](https://github.com/getmilpa) Milpa Plugin ============ [](#milpa-plugin) > **GitHub-native plugin distribution** for the Milpa PHP framework — semver-aware version resolution, manifest validation, dependency ordering, and a lock file, with no registry server required. [![CI](https://github.com/getmilpa/plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/getmilpa/plugin/actions/workflows/ci.yml)[![Packagist](https://camo.githubusercontent.com/61a02e0a588e77021a8d8e8e8bce40c94074475cd0b4f8e646206c3d993dd26b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d696c70612f706c7567696e2e737667)](https://packagist.org/packages/milpa/plugin)[![PHP](https://camo.githubusercontent.com/ca03f11ea27dac4dedc8ad56a7bdfc4a9ff5feb825055f9d2983616115076607/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d254532253839254135253230382e332d3737376262342e737667)](https://www.php.net/)[![License](https://camo.githubusercontent.com/798509b4df525f56802b56f8096862487f08023e3d7561c68656f8dab10d0d6e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4170616368652d2d322e302d626c75652e737667)](LICENSE)[![Docs](https://camo.githubusercontent.com/c6dc6a3411e15b0ac7cc4583e8e6a8144181caedb82f5d98753353decda06d77/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f63732d4150492532307265666572656e63652d626c75652e737667)](https://getmilpa.github.io/plugin/) `milpa/plugin` is the distinct-value core behind a Milpa host's `plugin require owner/repo`command: resolve a semver constraint against GitHub releases/tags, download and extract the matching zipball, read and validate the plugin's `milpa.json` manifest, resolve its plugin + Composer dependencies, order every installed plugin by the contracts it provides/requires, and record the result in a `milpa.lock` file. **No registry server, no Packagist-style index** — GitHub itself is the source of truth. Install ------- [](#install) ``` composer require milpa/plugin ``` Quick example ------------- [](#quick-example) ``` use Milpa\Plugin\ContractResolver; use Milpa\Plugin\DependencyResolver; use Milpa\Plugin\GitHubDownloader; use Milpa\Plugin\LockFileManager; use Milpa\Plugin\PluginManifest; // 1. Parse a GitHub source string into owner/repo/constraint. $downloader = new GitHubDownloader(); $downloader->parseSource('acme/mail-plugin:^2.0'); // -> ['owner' => 'acme', 'repo' => 'mail-plugin', 'constraint' => '^2.0'] // 2. Read + validate a milpa.json manifest (fromArray() mirrors fromPath()). $manifest = PluginManifest::fromArray([ 'name' => 'acme/mail-plugin', 'version' => '2.1.0', 'entrypoint' => 'MailPlugin.php', 'namespace' => 'Acme\\MailPlugin', 'contracts' => ['requires' => ['database']], ]); $manifest->validate(); // throws InvalidArgumentException on a malformed manifest // 3. Order plugins by their declared contracts (Kahn's algorithm; throws on cycles). $resolver = new ContractResolver(); $loadOrder = $resolver->getLoadOrder([ ['name' => 'DatabasePlugin', 'class' => 'Acme\\DatabasePlugin', 'provides' => ['database']], ['name' => 'acme/mail-plugin', 'class' => 'Acme\\MailPlugin', 'requires' => ['database']], ]); // -> load order: DatabasePlugin, acme/mail-plugin (providers before consumers) // 4. Resolve dependencies before installing (plugin deps, contracts, composer.lock). $deps = new DependencyResolver(getcwd()); $resolution = $deps->resolve($manifest, [ ['name' => 'DatabasePlugin', 'provides' => ['database']], ]); // -> $resolution->resolvable === true, $resolution->conflicts === [] // 5. Record installed state in milpa.lock. $lock = new LockFileManager(getcwd()); $lock->generate([ ['name' => 'acme/mail-plugin', 'version' => '2.1.0', 'source' => 'github:acme/mail-plugin'], ]); $lock->verify(); // true — the SHA-256 content hash matches ``` Generating a canonical manifest ------------------------------- [](#generating-a-canonical-manifest) `PluginManifest::generateFromMetadata()` turns a plugin's `#[PluginMetadata]` into `milpa.json`data — and the capability entries decide the emitted shape; the generator never invents metadata: - **every entry a structured record** (`{id, interface, contractVersion, service, …}`) → the canonical `capabilities` block, each record validated through core's capability value objects **plus** a generation-time provider check (`service` present, autoloadable, and implementing the declared interface). A record that fails validation is a **hard failure**(`InvalidArgumentException`), never a silent downgrade; - **every entry a bare FQCN string** → the legacy `contracts` block exactly as before, plus a `$warnings` entry teaching how to reach canonical; - **a mix of both shapes** in one plugin → hard failure: one plugin migrates atomically. The canonical shape is frozen in [`schema/milpa-plugin.schema.json`](schema/milpa-plugin.schema.json), which ships with this package — the suite's schema-conformance tests run against that exact file. Overwrite policy is the **host's** concern: a host command (e.g. `coa:plugins manifest --force`) decides whether an existing `milpa.json` may be replaced; the generator only returns the array. What lives where ---------------- [](#what-lives-where) ClassResponsibility`GitHubDownloader`Parses `owner/repo[:constraint]` / full GitHub URLs, lists releases/tags via the GitHub REST API, resolves the best version for a constraint, and downloads + extracts the matching zipball. Reads `GITHUB_TOKEN` for private repos or higher rate limits.`PluginManifest`Reads and validates a `milpa.json` manifest (`fromPath()` / `fromArray()`), exposes typed accessors (`getProvides()`, `getRequires()`, `getSuggests()`, typed `CapabilityProvision`/`CapabilityRequirement`/`CapabilitySuggestion` records, Composer/plugin dependencies, PHP version constraint, env vars), and generates a manifest from `#[PluginMetadata]` via `generateFromMetadata()` — canonical `capabilities` block for rich records, legacy `contracts` block (with a teaching warning) for bare FQCNs, hard failure on a mix.`ContractResolver`Validates that every plugin's `requires` is satisfied by some other plugin's `provides` (fail-fast, throws `RuntimeException`; `suggests` only logs), and topologically sorts plugins into a load order where providers come before consumers.`DependencyResolver`Resolves a plugin's contract requirements, plugin-to-plugin dependencies (with version constraint checks), and Composer dependencies (read from `composer.lock`) into a single `Milpa\DTO\DependencyResolution` — `resolvable`, `conflicts`, `missingPlugins`, `composerPackages`, `satisfiedContracts`.`LockFileManager`Generates, reads, and verifies `milpa.lock` — installed plugin names, versions, sources, install timestamps, and a SHA-256 content hash for integrity checks.Requirements ------------ [](#requirements) - PHP **≥ 8.3** - [`milpa/core`](https://packagist.org/packages/milpa/core) **^0.6** - [`psr/log`](https://packagist.org/packages/psr/log) **^3** Documentation ------------- [](#documentation) **Full API reference: [getmilpa.github.io/plugin](https://getmilpa.github.io/plugin/)** — generated straight from the source DocBlocks and dressed with the Milpa design system. Contributing ------------ [](#contributing) Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Please report security issues via [SECURITY.md](SECURITY.md), and note that this project follows a [Code of Conduct](CODE_OF_CONDUCT.md). License ------- [](#license) [Apache-2.0](LICENSE) © Rodrigo Vicente - TeamX Agency. --- Milpa is designed, built, and maintained by **[Rodrigo Vicente - TeamX Agency](https://teamx.agency/?utm_source=github&utm_medium=readme&utm_campaign=milpa&utm_content=plugin)**. ### Health Score 47 — FairBetter than 93% of packages Maintenance94 Actively maintained with recent releases Popularity22 Limited adoption so far Community16 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 71.4% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~2 days Total 19 Last Release 13d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/1993784?v=4)[rodrigomx](/maintainers/rodrigomx)[@rodrigomx](https://github.com/rodrigomx) --- Top Contributors [![rodrigoteamx](https://avatars.githubusercontent.com/u/269849276?v=4)](https://github.com/rodrigoteamx "rodrigoteamx (10 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (4 commits)") --- Tags frameworkpackagesphpsemverphpframeworkpluginsmanifestplugin-systemextensibilitymilpa ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/milpa-plugin/health.svg) ``` [![Health](https://phpackages.com/badges/milpa-plugin/health.svg)](https://phpackages.com/packages/milpa-plugin) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.3k37.6k21](/packages/tempest-framework)[cakephp/cakephp The CakePHP framework 8.9k20.0M1.9k](/packages/cakephp-cakephp)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 86337.5k](/packages/flow-php-flow)[drupal/core-recommended Locked core dependencies; require this project INSTEAD OF drupal/core. 6943.5M450](/packages/drupal-core-recommended)[typo3/cms TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL. 1.2k1.9M122](/packages/typo3-cms)[shopware/platform The Shopware e-commerce core 3.4k1.5M3](/packages/shopware-platform) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)