DevTools

Load Axolotl-PM plugins from folders, share development virions, and build standalone PHARs through server commands, the CLI, or GitHub Actions.

See the architecture overview for how folder loading, shared virions, and PHAR builds fit together.

Quick start

1. Download the DevTools PHAR from the latest release. GitHub's "Source code" archives are for developing DevTools.
2. Stop your Axolotl-PM server and copy the PHAR to plugins/DevTools.phar.
3. Put your development plugin folder, containing plugin.yml and src/, directly inside plugins/.
4. Start the server. Confirm that DevTools reports folder loading, shared virions, and PHAR building as ready, then run /devtools status as an operator.
5. Run /devtools doctor YourPlugin and /devtools build YourPlugin. Test build/YourPlugin.phar on a clean server before deployment.

Install DevTools itself as a PHAR so its folder loader can start. Restart the server after adding or editing source plugins.

Build a plugin on GitHub

Copy the short build workflow to .github/workflows/build.yml and push. It follows the maintained DevTools v2 workflow channel by default. Use @latest when you intentionally want every stable release, including future major versions; use a release tag or full commit SHA when your project requires a controlled or strict pin. Download the PHAR from the run's Artifacts section. A plugin without dependencies needs only plugin.yml and src/; no server checkout, project-local Composer installation, devtools.yml, or virions/ is required.

What it does

• Loads folder plugins through the server's plugin manager, which handles API compatibility, dependencies, duplicates, load order, and enable failures.
• Loads one compatible copy of each local development virion from a folder or PHAR in virions/ on the shared thread-safe class loader. A folder is preferred over a same-name PHAR and the PHAR is reported as skipped.
• Selects the highest semantic virion version satisfying every declared constraint and reports dependency conflicts.
• Builds a SHA-256 PHAR with declared virions rewritten into private namespaces using a PHP syntax tree.
• Builds standalone virion PHARs and dual-role projects as separate plugin and virion artifacts.
• Extracts plugin or virion PHARs to a folder or ZIP through the server command and CLI.
• Offers optional PHPStan analysis in GitHub Actions against an explicitly selected server source.
• Validates PHAR entries before extraction and stages replacement with a backup of existing output.

Server startup and ordinary builds use local dependencies. DevTools does not replace Composer or provide hot reload.

Requirements

• PHP 8.4 or newer, 64-bit, with the extensions required by the server
• Axolotl-PM with the API declared by plugin.yml
• phar.readonly=0 only when building PHARs

See runtime validation for the tested server and PHP versions. DevTools is an independent community project.

Minimal layout

All paths below are relative to the server directory.

Path	Contents
plugins/DevTools.phar	Installed DevTools plugin
plugins/MyPlugin/plugin.yml	Plugin manifest
plugins/MyPlugin/src/	Plugin source
plugins/MyPlugin/resources/	Optional plugin resources
plugins/MyPlugin/devtools.yml	Optional build and virion declarations
virions/ExampleVirion/ or virions/ExampleVirion.phar	Local library with virion.yml and src/
build/	Generated PHARs

If your plugin uses a shared library, put the package in virions/ExampleVirion/ and declare it for both development loading and the standalone build.

# plugins/MyPlugin/devtools.yml
virions:
  - name: ExampleVirion
    version: ^1.0.0

See shared virions for package requirements and version selection. The HelloShared and SharedGreeting example demonstrates the complete workflow.

Build on every commit

The reusable workflow supports push and pull-request builds. Use the step-level action for extra setup or checkouts. PHPStan is off unless you select a level and server source. A complete example lives in examples/.github/workflows/build.yml.

Ecosystem

DevTools is currently verified in 72 public repositories across several plugin and virion ecosystems. See the ecosystem inventory for the full project list, snapshot date and detection method.

• BedrockNexus provides an official Axolotl-PM workflow template powered by DevTools.

Build with a coding agent

Use the coding agent guide for CLI automation or GitHub workflow setup. An AGENTS.md template is included in the examples ZIP.

Commands

All commands require devtools.command, which operators receive by default.

/devtools status
/devtools doctor [plugin]
/devtools virions
/devtools build [plugin|virion|both] <project> [--overwrite]
/devtools extract <phar> [--format=folder|zip] [--type=auto|plugin|virion] [--overwrite]

Migration aliases /makeplugin and /extractplugin are also available.

Documentation

Start here

• Installation, update, rollback, and uninstall
• Folder plugin behavior
• Building and validating PHARs
• Troubleshooting

Choose an advanced workflow

• CLI commands and versioned JSON contract
• Local and locked Composer dependency preparation
• Clean Axolotl-PM runtime verification
• Configuration reference
• Shared virions and version resolution
• Building a PHAR on every commit with GitHub Actions
• Building a PHAR with a coding agent
• FAQ
• Migration guide

Maintain DevTools

• Dependency ownership and packaging policy
• Developer workflow
• Architecture
• Security policy

Production guidance

Use folder plugins and shared virions for development. Deploy tested PHARs to production; editing source in place can leave partially changed code after a restart. For a project containing both plugin.yml and virion.yml, use build both to create two role-specific PHARs; DevTools never merges a plugin into a virion or a virion into another virion. Plugin-to-virion injection is rejected because a plugin manifest is not a virion contract.

License and provenance

DevTools is MIT licensed. The bundled nikic/php-parser uses BSD-3-Clause. See third-party notices for its license and provenance.