DevTools

Load PocketMine-MP development plugins from folders, share development virions once, and build standalone production PHARs.

Quick Start

1. Download DevTools-1.0.0.phar from the latest release. Do not download "Source code" unless you are developing DevTools.
2. Stop your compatible PocketMine-derived server, copy the PHAR to plugins/DevTools.phar, and start the server again.
3. Confirm the console says that folder loading, shared virions, and PHAR building are ready. Run /devtools status as an operator.
4. Put a development plugin folder containing plugin.yml and src/ directly inside plugins/.
5. Run /devtools doctor YourPlugin. When ready for production, run /devtools build YourPlugin and take the result from build/.

DevTools must itself be installed as a PHAR: a normal PocketMine-MP server cannot use DevTools to load DevTools from a folder before DevTools has started.

Quick Start for a plugin repository

For a normal plugin, plugin.yml and src/ are enough. Copy the complete workflow from the GitHub Actions guide to .github/workflows/build.yml, push the repository, and download the PHAR from the workflow run's Artifacts section. This path does not require a PocketMine server source checkout or a project-local Composer installation.

Only add a virion when the plugin intentionally shares a package during development:

• Put the local package in server-root virions/<VirionName>/.
• Declare it in the plugin's devtools.yml with a version constraint.
• DevTools loads the shared source during development and shades it into the production PHAR.

If the plugin has no virion, omit devtools.yml and virions/. See folder plugins for the ordinary layout and shared virions when a shared package is actually needed.

What it does

• Loads folder plugins through the server's normal plugin manager, so duplicate names, API compatibility, dependencies, cycles, load order, and enable failures remain under server handling.
• Loads one compatible copy of each local development virion from virions/ on the shared thread-safe class loader.
• Selects the highest semantic virion version satisfying every declared constraint and reports skipped, missing, duplicate, or conflicting packages.
• Builds a selected plugin into a standalone SHA-256 PHAR by AST-shading its declared virions into a private namespace.
• Optionally runs PHPStan at level 0-10 or max against a workflow-selected local server source before building; omission keeps analysis off.
• Safely extracts a PHAR through complete preflight validation and transactional replacement.

It does not download plugin or virion source during server startup or normal build resolution, replace Composer, provide hot reload, or act as a marketplace/package registry.

Requirements

• PHP 8.1 or newer, 64-bit, with the extensions required by the server
• PocketMine-derived server software compatible with the API declared by plugin.yml
• phar.readonly=0 only when building PHARs

Compatibility is capability-based where practical, and CI uses an active PocketMine-derived implementation for development types. DevTools is an independent community project, not an official release of any server project.

Minimal layout

server/
├── plugins/
│   ├── DevTools.phar
│   └── MyPlugin/
│       ├── plugin.yml
│       ├── devtools.yml       optional virion/build declaration
│       ├── src/
│       └── resources/         optional
├── virions/
│   └── ExampleVirion/
│       ├── virion.yml
│       └── src/
└── build/                     generated PHARs

To require a shared virion during development and shade it into the production build:

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

Plain names remain supported as "any version" for migration compatibility:

virions:
  - ExampleVirion

The tested HelloShared + SharedGreeting example demonstrates folder loading, shared use, version declaration, and standalone building without another repository.

Build on every commit

Plugin repositories can use the zero-setup reusable workflow for a normal build, or NhanAZ/DevTools@v1.0.0 as a step-level GitHub Action when the workflow needs explicit setup or PHPStan server checkouts. The tested workflow in examples/.github/workflows/build.yml builds a standalone PHAR on every push and pull request and uploads it to the workflow run's Artifacts section. PHPStan remains off unless the workflow explicitly selects a level and server source. See Build a PHAR on every commit for both paths.

Build with an AI agent

Paste the versioned AI agent prompt into an agent working inside a plugin repository. It tells the agent to inspect the project, configure the tested action, pin dependency sources, keep PHPStan off unless requested, and verify exactly one downloadable PHAR artifact. A persistent AGENTS.md template is also included in the examples ZIP.

Commands

All commands require devtools.command, granted to operators by default:

/devtools status
/devtools doctor [plugin]
/devtools virions
/devtools build <plugin> [--overwrite]
/devtools extract <phar> [--overwrite]

Migration aliases /makeplugin and /extractplugin are also available.

Documentation

Most users only need this README, the installation guide, and troubleshooting. The other guides are reference material for the workflow you choose.

Start here

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

Choose an advanced workflow

• Configuration reference
• Shared virions and version resolution
• Building a PHAR on every commit with GitHub Actions
• Building a PHAR with an AI agent
• FAQ
• Migration guide

Maintain DevTools

• Developer workflow
• Architecture
• Security policy

Production guidance

Use folder plugins and shared virions only for development. Editing source directly on a production server makes deployments non-reproducible and can leave partially changed code after a restart. Production servers should receive only tested PHAR artifacts from /devtools build or a trusted release.

License and provenance

DevTools is MIT licensed. nikic/php-parser is bundled under BSD-3-Clause; see third-party notices.

The behavior of pmmp/DevTools, poggit/devirion, and SOF3/pharynx informed the problem study. No source was copied from those projects. Exact inspected revisions and licenses are recorded in third-party notices.