Plugin Manifest

The manifest file defines your plugin's metadata, requirements, and capabilities.

Complete Schema

{
    "name": "my-plugin",
    "display_name": "My Awesome Plugin",
    "version": "1.0.0",
    "author": "Your Name <[email protected]>",
    "description": "A comprehensive plugin that extends PteroCA with custom functionality",
    "license": "MIT",
    "pteroca": {
        "min": "0.6.0",
        "max": "1.0.0"
    },
    "capabilities": [
        "routes",
        "entities",
        "migrations",
        "ui",
        "eda",
        "console",
        "cron"
    ],
    "requires": {
        "other-plugin": "^1.0",
        "another-plugin": ">=2.0.0"
    },
    "bootstrap_class": "Plugins\\MyPlugin\\Bootstrap",
    "config_schema": {
        "api_key": {
            "type": "password",
            "required": true,
            "default": "",
            "label": "API Key",
            "help": "Your API key from the service provider",
            "hierarchy": "general"
        },
        "api_endpoint": {
            "type": "string",
            "required": false,
            "default": "https://api.example.com",
            "label": "API Endpoint",
            "help": "Custom API endpoint URL",
            "hierarchy": "advanced"
        },
        "enabled_features": {
            "type": "select",
            "required": false,
            "default": "basic",
            "options": {
                "basic": "Basic Features",
                "advanced": "Advanced Features",
                "premium": "Premium Features"
            },
            "label": "Feature Level",
            "hierarchy": "general"
        },
        "debug_mode": {
            "type": "boolean",
            "required": false,
            "default": false,
            "label": "Debug Mode",
            "help": "Enable detailed logging for troubleshooting",
            "hierarchy": "advanced"
        }
    },
    "assets": {
        "css": [
            "css/styles.css",
            "css/admin.css"
        ],
        "js": [
            "js/script.js",
            "js/admin.js"
        ],
        "img": [
            "images/logo.svg",
            "images/icon.png"
        ]
    }
}

Field Descriptions

Basic Information

• name (required): Unique plugin identifier in kebab-case

  • Used in URLs, routes, settings context

  • Must be unique across all plugins

  • Can only contain lowercase letters, numbers, and hyphens

  • Example: my-plugin, paypal-payment

• display_name (required): Human-readable plugin name

  • Shown in Admin Panel and UI

  • Can contain spaces, capitals, special characters

  • Example: "My Awesome Plugin"

• version (required): Semantic version number

  • Format: MAJOR.MINOR.PATCH

  • Example: 1.0.0, 2.3.1

  • Used for dependency resolution and updates

• author (required): Plugin author information

  • Format: Name <email> or just Name

  • Example: "John Doe <[email protected]>"

• description (required): Brief plugin description

  • Shown in plugin list

  • Keep concise (1-2 sentences)

• license (required): License identifier

  • SPDX license identifier recommended

  • Example: MIT, GPL-3.0, Apache-2.0

PteroCA Version Requirements

• pteroca.min (required): Minimum PteroCA version

  • Plugin won't install on older versions

  • Example: "0.6.0"

• pteroca.max (optional): Maximum PteroCA version

  • Useful if plugin is incompatible with future versions

  • Example: "1.0.0"

Capabilities

Declare which features your plugin implements:

"capabilities": [
    "routes",      // HTTP routes and controllers
    "entities",    // Database entities
    "migrations",  // Database migrations
    "ui",          // Widgets, tabs, menu items, assets
    "eda",         // EasyAdmin CRUD controllers
    "console",     // CLI commands
    "cron"         // Scheduled tasks
]

Only declare capabilities you actually use. This helps the system:

• Validate plugin structure

• Optimize loading

• Generate documentation

• Perform health checks

Dependencies

Plugin dependencies (requires):

"requires": {
    "base-plugin": "^1.0",      // Compatible with 1.x
    "other-plugin": ">=2.0.0",  // Version 2.0.0 or higher
    "third-plugin": "~1.2"      // Compatible with 1.2.x
}

Specify other plugins that must be installed and enabled before this plugin can work. PteroCA will validate dependencies during installation and prevent enabling if requirements aren't met.

Bootstrap Class

• bootstrap_class (optional): Fully qualified class name

  • Called when plugin is enabled/disabled

  • Must implement initialize() and cleanup() methods

  • Example: "Plugins\\MyPlugin\\Bootstrap"

Configuration Schema

Define plugin settings that users can configure:

"config_schema": {
    "setting_name": {
        "type": "string",           // Field type
        "required": true,           // Is required?
        "default": "default_value", // Default value
        "label": "Setting Label",   // Display label
        "help": "Help text",        // Description
        "hierarchy": "general",     // general or advanced
        "options": {...}            // For select type
    }
}

Available types:

• string: Short text input

• text: Long text (textarea)

• integer: Numeric input

• boolean: Checkbox (true/false)

• password: Encrypted password field

• select: Dropdown with predefined options

Hierarchy levels:

• general (100): Basic settings shown first

• advanced (200): Advanced settings shown later

Assets

Declare frontend assets to be published:

"assets": {
    "css": ["css/styles.css"],       // CSS files
    "js": ["js/script.js"],          // JavaScript files
    "img": ["images/logo.svg"]       // Images
}

Assets are:

• Copied/symlinked from plugins/my-plugin/assets/ to public/assets/plugins/my-plugin/

• Automatically published when plugin is enabled

• Accessible via plugin_asset() Twig function

Naming Conventions

Consistent naming is critical for plugin functionality. Follow these conventions exactly.

Convention Table

Element	Convention	Example	Notes
Plugin name (JSON)	kebab-case	my-plugin	Used in manifest, URLs, commands
Namespace	PascalCase	Plugins\MyPlugin	PSR-4 autoloading
Table name	plg_{short}_{table}	plg_my_visit_log	Database tables
Route name	plugin_{name}_	plugin_my_plugin_index	Symfony routes
URL prefix	/plugins/{name}/	/plugins/my-plugin/	Automatic prefix
Template namespace	@Plugin{Name}/	@PluginMyPlugin/	Twig templates
Translation domain	plugin_{name}	plugin_my_plugin	Snake_case!
Console command	{name}:{cmd}	my-plugin:greet	Kebab-case
Settings context	plugin:{name}	plugin:my-plugin	Settings storage
Asset path	plugins/{name}/	plugins/my-plugin/	Public assets

Examples

Plugin: hello-world

• Manifest name: "name": "hello-world"

• Namespace: Plugins\HelloWorld

• Table: plg_hello_visit_log

• Route: plugin_hello_world_index

• URL: /plugins/hello-world/

• Template: @PluginHelloWorld/index.html.twig

• Translation: plugin_hello_world

• Command: hello-world:greet

• Settings: plugin:hello-world

Plugin: paypal-payment

• Manifest name: "name": "paypal-payment"

• Namespace: Plugins\PaypalPayment

• Route: plugin_paypal_payment_webhook

• URL: /plugins/paypal-payment/webhook

• Template: @PluginPaypalPayment/config.html.twig

• Translation: plugin_paypal_payment

• Settings: plugin:paypal-payment

Related Guides

• Plugin Structure - Directory organization

• Assets - Frontend resources

• Translations - Multi-language support

• Dependencies - Service registration