Skip to main content
The Plugin.yml analyzer validates the structure, format, and content of your plugin’s plugin.yml manifest file. It ensures all required fields are present and correctly formatted according to PocketMine-MP standards.

​
What it checks

The analyzer performs comprehensive validation across multiple areas:

​
File existence and structure

  • Verifies that plugin.yml exists in the plugin root directory
  • Validates YAML syntax is correct and parseable
  • Ensures the file contains a YAML mapping (not a scalar or array)

​
Required fields

The analyzer checks for all required fields:
  • name - Plugin identifier
  • version - Plugin version number
  • main - Fully-qualified main class name
  • api - PocketMine-MP API version(s)

​
Field validation

Each field is validated according to specific rules:
  • Must be a string type
  • Can only contain letters, numbers, hyphens, periods, underscores, and spaces
  • Warns if name contains spaces (discouraged)
Valid names:
name: MyPlugin
name: my-plugin
name: my_plugin
Invalid names:
name: My@Plugin  # Special characters not allowed
name: 123         # Number-only not recommended
  • Must be a string or number
  • Should follow semantic versioning format (MAJOR.MINOR.PATCH)
  • Supports pre-release and build metadata
Valid versions:
version: 1.0.0
version: 2.1.3-beta
version: 1.0.0+build.123
Invalid versions:
version: v1.0      # Should be numeric
version: latest    # Not a version number
  • Must be a fully-qualified class name string
  • Must follow PHP namespace and class naming conventions
  • Must be a valid PHP identifier with backslash separators
Valid main class:
main: MyPlugin\Main
main: Company\Plugin\PluginMain
Invalid main class:
main: MyPlugin          # Missing namespace
main: My-Plugin\Main    # Invalid characters
main: 123\Plugin        # Cannot start with number
  • Can be a string (single version) or array (multiple versions)
  • Must follow format: X.Y.Z (three-part semantic version)
  • Warns if using API version older than 4.0.0
Valid API versions:
api: 5.0.0
api: [5.0.0, 4.0.0]
Invalid API versions:
api: 5.0        # Missing patch version
api: latest     # Not a version number

​
Optional fields validation

The analyzer also validates optional fields when present:
Each command must be a mapping with proper configuration:
commands:
  mycommand:
    description: My command description
    usage: /mycommand <args>
    permission: myplugin.command.mycommand
Issue detected:
commands:
  mycommand: simple_string  # Error: must be a mapping
Permission default values must be valid:
  • op - Operator only
  • notop - Non-operators only
  • true - Everyone
  • false - Nobody
permissions:
  myplugin.command:
    description: Use plugin commands
    default: op
Issue detected:
permissions:
  myplugin.command:
    default: admin  # Error: invalid value
All dependency types must be strings or arrays of strings:
  • depend - Hard dependencies (required)
  • softdepend - Soft dependencies (optional)
  • loadbefore - Load order dependencies
depend:
  - EconomyAPI
  - PermissionsEx

softdepend: [WorldProtect]
Issue detected:
depend:
  - 123  # Error: must be string
The load field controls when the plugin loads:
  • STARTUP - Load during server startup
  • POSTWORLD - Load after worlds are loaded
load: POSTWORLD
Issue detected:
load: EARLY  # Error: invalid value

​
Issues detected

The analyzer reports issues across multiple severity levels:

​
Error severity

These issues will prevent your plugin from loading.
  • Missing plugin.yml file
  • YAML syntax errors
  • Missing required fields
  • Invalid field types or formats
  • Invalid main class format
  • Invalid API version format
  • Invalid permission or command configuration

​
Warning severity

  • Plugin name contains invalid characters
  • API version is outdated (< 4.0.0)

​
Info severity

These are suggestions for improvement, not critical issues.
  • Plugin name contains spaces
  • Version doesn’t follow semantic versioning

​
Code examples

​
Correct plugin.yml

name: MyAwesomePlugin
version: 1.0.0
main: MyNamespace\MyPlugin\Main
api: 5.0.0

commands:
  myplugin:
    description: Main plugin command
    usage: /myplugin <action>
    permission: myplugin.command

permissions:
  myplugin.command:
    description: Allow using plugin commands
    default: op

​
Common issues

# Bad: Missing 'api' field
name: MyPlugin
version: 1.0.0
main: MyPlugin\Main
# Error: Required field 'api' is missing in plugin.yml

​
Fix suggestions

When the analyzer finds issues, it provides actionable suggestions:
IssueSuggestion
Missing plugin.ymlCreate a plugin.yml file with required fields: name, version, main, api
Missing required fieldAdd the ‘field_name’ field to plugin.yml
Invalid main class formatMain class must be a valid fully-qualified PHP class name
Name with spacesConsider using hyphens or underscores instead of spaces
Non-semver versionConsider using semantic versioning (MAJOR.MINOR.PATCH)
Outdated API versionUpdate your plugin to use the latest PocketMine-MP API
The analyzer validates your plugin.yml at src/Analyzer/PluginYmlAnalyzer.php:18-70

Build docs developers (and LLMs) love

Get started for freeTalk to us