Plugins

Comprehensive guide to managing and using plugins in PteroCA v0.6+

Overview

Plugins are extensions that add new functionality to your PteroCA panel without modifying the core codebase. The plugin system, introduced in v0.6, provides a secure and maintainable way to extend PteroCA with custom features, integrations, and payment providers.

Plugin System Available in v0.6+

The plugin system is a major feature of PteroCA v0.6 and later versions. If you're running an earlier version, please upgrade to access plugin functionality.

What Can Plugins Do?

Plugins can extend PteroCA in many ways:

• Payment Providers: Add new payment gateways (PayPal, Stripe, Coinbase, etc.)

• Custom Features: Implement unique functionality specific to your business needs

• Integrations: Connect with external services and APIs

• Dashboard Widgets: Add custom widgets to the dashboard

• Server Management: Extend server management capabilities with custom tabs and features

• Automation: Add cron tasks and console commands

• UI Extensions: Customize the admin panel with new CRUD interfaces

Benefits of Using Plugins

• Maintainable: Plugins are isolated from core code, making updates easier

• Secure: Automated security scanning and validation

• Flexible: Enable only the plugins you need

• Dependency Management: Automatic handling of plugin dependencies

• Health Monitoring: Built-in health checks and status monitoring

---

Managing Plugins in Admin Panel

The Admin Panel provides a comprehensive interface for managing your installed plugins.

PLACEHOLDER: Screenshot - Admin Panel → Plugins List View

Accessing the Plugins Section

1. Log in to the Admin Panel with an account that has plugin management permissions

2. Navigate to Admin Panel → Plugins

3. You'll see a list of all discovered plugins with their current status

Plugin Information

For each plugin, you can view:

• Name: Plugin display name

• Version: Current version number

• Author: Plugin developer

• Status: Current state (enabled, disabled, faulted, update pending)

• Health: Health check percentage (0-100%)

• Description: Brief description of what the plugin does

• Actions: Available operations (enable, disable, configure, etc.)

PLACEHOLDER: Screenshot - Plugin Details View with Status Information

Plugin States

Plugins can be in one of several states:

State	Description
ENABLED	Plugin is active and functioning
DISABLED	Plugin is installed but not active
FAULTED	Plugin has errors and cannot be enabled
UPDATE_PENDING	An update is available for this plugin
DISCOVERED	Plugin found but not yet registered

Viewing Plugin Details

Click on a plugin name to view detailed information:

• Complete manifest information

• Dependency tree

• Security scan results

• Health check details

• Configuration options

• Changelog (if available)

---

Installing Plugins

PteroCA offers three methods for installing plugins, from easiest to most advanced:

Recommended: ZIP Upload

The ZIP upload method is the easiest way to install plugins. Simply upload a plugin archive through the Admin Panel - no server access required!

Method 1: ZIP Upload via Admin Panel (Easiest)

Upload and install plugins directly through the Admin Panel without server access.

Step 1: Obtain Plugin ZIP File

1. Download the plugin as a .zip archive from the plugin developer

2. Ensure the archive is a valid plugin (contains plugin.json in the root)

Supported format:

• File format: .zip only

• Maximum file size: 50 MB

• Maximum extracted size: 100 MB

Step 2: Upload Plugin

1. Navigate to Admin Panel → Plugins

2. Click Upload Plugin button

3. Click Choose File and select your plugin ZIP file

4. (Optional) Check Enable after upload to automatically enable the plugin after installation

5. Click Upload button

PLACEHOLDER: Screenshot - Plugin Upload Form

What happens automatically:

1. ✅ Validates ZIP file format and size

2. ✅ Extracts plugin files to /plugins/ directory

3. ✅ Validates plugin manifest (plugin.json)

4. ✅ Runs security scan on plugin code

5. ✅ If "Enable after upload" checked: automatically enables the plugin

Enable After Upload

If you check "Enable after upload", the plugin will be automatically enabled and go through the full enable process (migrations, asset publishing, etc.). If unchecked, the plugin will be installed but remain in DISCOVERED state until you manually enable it.

Step 3: Configure Plugin Settings

After the plugin is enabled:

1. Navigate to Settings → Plugins

2. Find your plugin in the list

3. Click Configure or Edit

4. Fill in required settings (API keys, credentials, options)

5. Save changes

PLACEHOLDER: Screenshot - Plugin Configuration Settings Page

Security Scan Required

All uploaded plugins undergo automatic security scanning. If CRITICAL security issues are found, the plugin cannot be enabled until those issues are resolved.

Method 2: Manual File Placement

Install plugins by manually placing files on the server.

Step 1: Place Plugin Files

1. Obtain the plugin files (download or extract from archive)

2. Connect to your server via SSH or SFTP

3. Copy the plugin folder to /plugins/ directory in your PteroCA installation

4. The plugin folder name should match the plugin identifier (e.g., hello-world)

# Example structure
/var/www/pteroca/
└── plugins/
    ├── hello-world/
    │   ├── plugin.json
    │   ├── Bootstrap.php
    │   └── src/
    └── paypal-payment/
        ├── plugin.json
        └── src/

Step 2: Open Admin Panel

1. Navigate to Admin Panel → Plugins

2. The plugin appears automatically in the list (no scan command needed!)

3. Check the plugin's health status indicator

Automatic Discovery:

• Plugins are discovered automatically when you open the Plugins page

• No manual scan or registration required

• Shows validation status and any errors immediately

PLACEHOLDER: Screenshot - Admin Panel → Plugins List View

Step 3: Install Composer Dependencies (if needed)

If the plugin uses external PHP packages, you'll see a warning that Composer dependencies aren't installed.

Via CLI:

cd /var/www/pteroca
php bin/console pteroca:plugin:install-deps my-plugin

This runs composer install in the plugin directory.

When are Composer dependencies needed?

Only if the plugin has a composer.json file. Most simple plugins don't need this step. Check the plugin documentation or look for composer.json in the plugin folder.

Step 4: Enable the Plugin

Click the Enable button next to the plugin.

What happens automatically:

1. ✅ Validates plugin manifest and structure

2. ✅ Runs security scan (blocks if critical issues found)

3. ✅ Checks dependencies (plugin and Composer)

4. ✅ Executes database migrations (if plugin has migrations)

5. ✅ Publishes assets (CSS, JS, images) to /public/assets/plugins/

6. ✅ Registers services and event subscribers

7. ✅ Calls plugin bootstrap initialization

If the plugin has dependencies on other plugins, you'll be prompted to enable them first, or use the --with-dependencies flag in CLI.

PLACEHOLDER: Screenshot - Plugin Enable Success Message

Step 5: Configure Plugin Settings

After enabling, configure the plugin in the Admin Panel:

1. Navigate to Settings → Plugins

2. Find your plugin in the list

3. Click Configure or Edit

4. Fill in required settings (API keys, credentials, options)

5. Save changes

PLACEHOLDER: Screenshot - Plugin Configuration Settings Page

Permission Required

To configure plugin settings, you need the edit_settings_plugin permission. By default, only administrators have this permission.

See Roles & Permissions for more information.

Method 3: Command Line (Advanced)

For automation, scripting, or when you prefer working in the terminal.

Step 1: Place Plugin Files

Same as Method 1 - copy the plugin folder to /plugins/ directory.

# Example structure
/var/www/pteroca/
└── plugins/
    └── my-plugin/
        ├── plugin.json
        └── src/

Step 2: List Available Plugins (Optional)

Check if your plugin was discovered correctly:

php bin/console pteroca:plugin:list

Output example:

+----------------+------------------+---------+----------+---------+
| Name           | Display Name     | Version | Author   | State   |
+----------------+------------------+---------+----------+---------+
| hello-world    | Hello World      | 1.0.0   | PteroCA  | DISCOVERED |
| paypal-payment | PayPal Payment   | 1.0.0   | PteroCA  | ENABLED |
+----------------+------------------+---------+----------+---------+

About pteroca:plugin:scan

You may see references to pteroca:plugin:scan in older documentation. This command only displays plugin information - it does NOT register plugins. Plugins are automatically discovered when you use plugin:list or open the Admin Panel.

Step 3: Install Dependencies

If the plugin has a composer.json file or depends on other plugins:

Install Composer dependencies:

php bin/console pteroca:plugin:install-deps my-plugin

Check plugin dependencies:

php bin/console pteroca:plugin:depends my-plugin

This shows which other plugins are required.

Step 4: Enable the Plugin

Simple enable:

php bin/console pteroca:plugin:enable my-plugin

Enable with automatic dependency installation:

php bin/console pteroca:plugin:enable my-plugin --with-dependencies

This automatically enables any required plugins in the correct order.

What happens automatically:

1. ✅ Validates plugin manifest and structure

2. ✅ Runs security scan (blocks if critical issues found)

3. ✅ Checks dependencies (plugin and Composer)

4. ✅ Executes database migrations

5. ✅ Publishes assets to /public/assets/plugins/

6. ✅ Registers services and subscribers

7. ✅ Calls plugin bootstrap

Success output:

Enable Plugin: my-plugin
========================

Plugin Information
------------------
Name:          my-plugin
Display Name:  My Awesome Plugin
Version:       1.0.0
Author:        Developer Name
State:         DISCOVERED

[OK] Plugin 'my-plugin' has been enabled successfully

Step 5: Configure Plugin Settings

Configure via Admin Panel (Settings → Plugins).

---

Plugin Configuration

Most plugins require configuration before they can be used. Configuration is stored in the PteroCA settings system and is specific to each plugin.

Accessing Plugin Settings

1. Navigate to Settings → Plugins

2. Each enabled plugin appears with its configurable options

3. Settings are organized by hierarchy (General, Advanced)

Configuration Schema

Plugins define their configuration schema in plugin.json:

• Type: string, integer, boolean, password, text, select

• Required: Whether the setting must be provided

• Default: Default value if not set

• Hierarchy: general (basic settings) or advanced (expert options)

Required vs Optional Settings

• Required settings must be configured before the plugin can function

• Optional settings have defaults and can be customized as needed

• The Admin Panel marks required settings clearly

Settings Security

• Password fields are encrypted in the database

• Settings are validated against the schema

• Only users with edit_settings_plugin permission can modify plugin settings

• Changes are logged in the audit log

---

Managing Dependencies

Plugins can depend on other plugins or external Composer packages. PteroCA automatically manages these dependencies.

Plugin Dependencies

Some plugins require other plugins to be installed and enabled before they can work. For example, a payment gateway plugin might depend on a base payment framework plugin.

Check plugin dependencies:

php bin/console pteroca:plugin:depends my-plugin

This shows which other plugins are required and their version requirements.

Automatic Dependency Installation

Enable a plugin and all its dependencies automatically:

php bin/console pteroca:plugin:enable my-plugin --with-dependencies

This command enables the required plugins in the correct order and then enables your plugin.

Cascade Disable

When disabling a plugin that other plugins depend on, use the cascade option:

php bin/console pteroca:plugin:disable base-plugin --cascade

This disables the plugin and all plugins that depend on it, preventing broken dependencies.

Composer Dependencies

Some plugins use external PHP libraries (Composer packages). If a plugin requires Composer dependencies, install them with:

php bin/console pteroca:plugin:install-deps my-plugin

Most simple plugins don't need this step. The Admin Panel will show a warning if Composer dependencies are missing.

---

Plugin Security

PteroCA includes comprehensive security features to protect your panel from malicious plugins.

Automated Security Scanning

Every plugin undergoes automatic security scanning before being enabled. The security scanner checks for:

1. Dangerous Code Patterns: Scans PHP code for potentially harmful functions

2. SQL Injection Risks: Checks for unsafe database queries

3. Path Traversal Vulnerabilities: Looks for file system security issues

4. Hardcoded Credentials: Detects exposed API keys or passwords

5. Composer Vulnerabilities: Checks external dependencies for known security issues

6. Manifest Validation: Ensures plugin structure is correct

Severity Levels

Security issues are classified by severity:

Severity	Impact	Action
CRITICAL	Immediate security risk	Plugin cannot be enabled
HIGH	Serious vulnerability	Warning shown, enable at own risk
MEDIUM	Potential security issue	Warning shown, monitoring recommended
LOW	Minor concern	Logged for review

Manual Security Scan

Run a security scan manually:

php bin/console pteroca:plugin:security-scan my-plugin

View detailed scan results:

php bin/console pteroca:plugin:security-scan my-plugin --detailed

Security Best Practices

When using plugins:

1. Only install plugins from trusted sources

2. Review security scan results before enabling

3. Keep plugins updated to receive security patches

4. Monitor plugin health regularly

5. Disable unused plugins to reduce attack surface

6. Check plugin dependencies for known vulnerabilities

7. Review permissions granted to plugin developers

CRITICAL Vulnerabilities Block Enabling

If a plugin has CRITICAL severity vulnerabilities, it cannot be enabled until the issues are resolved. This protects your panel from immediate security risks.

---

Health Checks

PteroCA automatically monitors plugin health to detect issues before they impact your panel.

Automated Health Checks

Health checks run automatically:

• On enable: Before activating a plugin

• Scheduled: Every 6 hours for all enabled plugins

• On demand: Via CLI or Admin Panel

What Health Checks Monitor

The health check system examines:

1. Manifest Validation: Checks if plugin.json is valid and complete

2. File Integrity: Verifies all required files exist

3. Dependencies: Ensures all required plugins and packages are installed

4. Security Status: Checks for vulnerabilities and security issues

5. Autoload Check: Verifies plugin code can be loaded correctly

Health Percentage

Health is calculated as a percentage (0-100%):

• 90-100%: Excellent - Plugin is fully healthy

• 70-89%: Good - Minor issues present

• 50-69%: Fair - Some problems detected

• 30-49%: Poor - Multiple issues need attention

• 0-29%: Critical - Serious problems, consider disabling

Running Health Checks

Check all plugins:

php bin/console pteroca:plugin:health

Check specific plugin:

php bin/console pteroca:plugin:health my-plugin

Detailed health report:

php bin/console pteroca:plugin:health my-plugin --detailed

Output example:

Plugin: my-plugin (v1.0.0)
Status: ENABLED
Health: 85%

✓ Manifest validation: PASS
✓ File integrity: PASS
✓ Dependencies: PASS
⚠ Security status: WARNING (1 medium issue)
✓ Autoload check: PASS

Overall: GOOD

Health Check Results in Admin Panel

View health status visually in the Admin Panel:

1. Navigate to Admin Panel → Plugins

2. Health percentage displayed for each plugin

3. Color coding: Green (good), Yellow (fair), Red (poor)

4. Click plugin name for detailed health report

PLACEHOLDER: Screenshot - Plugin List with Health Percentages

---

Plugin Permissions

PteroCA v0.6 includes granular permissions for plugin management, allowing you to control who can perform various plugin operations.

Plugin Management Permissions

Permission	Description	Use Case
access_plugins	View plugins list in Admin Panel	Allow viewing installed plugins
view_plugin	View detailed plugin information	Allow checking plugin details and health
enable_plugin	Enable plugins	Allow activating plugins
disable_plugin	Disable plugins	Allow deactivating plugins
install_plugin	Install new plugins (upload/scan)	Allow adding new plugins
uninstall_plugin	Completely remove plugins	Allow deleting plugins
upload_plugin	Upload plugin archives	Allow file uploads (future feature)
configure_plugin	Configure plugin settings	Allow accessing plugin configuration

Plugin Settings Permissions

Permission	Description
access_settings_plugin	View plugin settings (read-only)
edit_settings_plugin	Edit plugin settings and configurations

Example Role Scenarios

Plugin Administrator

Full control over plugins:

• access_plugins, view_plugin, enable_plugin, disable_plugin

• install_plugin, uninstall_plugin, upload_plugin

• configure_plugin, access_settings_plugin, edit_settings_plugin

Plugin Manager (Limited)

Can manage existing plugins but not install new ones:

• access_plugins, view_plugin, enable_plugin, disable_plugin

• configure_plugin, access_settings_plugin, edit_settings_plugin

Plugin Viewer (Read-Only)

Can only view plugin information:

• access_plugins, view_plugin, access_settings_plugin

Assigning Permissions

Via Admin Panel:

1. Navigate to Admin Panel → Roles

2. Create or edit a role

3. Select desired plugin permissions

4. Assign the role to users

Via CLI:

# Create role with plugin permissions
php bin/console pteroca:role:create "Plugin Manager" \
  --permissions access_plugins,view_plugin,enable_plugin,disable_plugin,configure_plugin

Default Permissions

The admin role has all plugin permissions by default. The user role has no plugin permissions.

For detailed information about the permission system, see Roles & Permissions.

---

CLI Commands Quick Reference

PteroCA provides comprehensive CLI commands for plugin management. Here's a quick reference of the most commonly used commands.

Discovery and Installation

Command	Description
pteroca:plugin:scan	Display plugin information (info only, does not register)
pteroca:plugin:list	List all discovered plugins with status
pteroca:plugin:info <plugin>	Show detailed plugin information
pteroca:plugin:install-deps <plugin>	Install plugin dependencies

Enable and Disable

Command	Description
pteroca:plugin:enable <plugin>	Enable a plugin
pteroca:plugin:enable <plugin> --with-dependencies	Enable plugin and all dependencies
pteroca:plugin:disable <plugin>	Disable a plugin
pteroca:plugin:disable <plugin> --cascade	Disable plugin and dependent plugins

Health and Security

Command	Description
pteroca:plugin:health	Check health of all plugins
pteroca:plugin:health <plugin>	Check specific plugin health
pteroca:plugin:security-scan <plugin>	Run security scan on plugin

Assets and Maintenance

Command	Description
pteroca:plugin:assets:publish <plugin>	Publish plugin assets
pteroca:plugin:assets:publish --force	Republish all plugin assets
pteroca:plugin:reset <plugin>	Reset faulted plugin
pteroca:plugin:uninstall <plugin>	Completely remove plugin

Dependency Management

Command	Description
pteroca:plugin:depends <plugin>	Show plugin dependency tree
pteroca:plugin:dependents <plugin>	Show plugins depending on this one

Complete Command Documentation

For detailed documentation of all plugin commands with examples and options, see CLI Reference - Plugin Commands.

---

Troubleshooting

Common issues and solutions when working with plugins.

Plugin in FAULTED State

Symptoms: Plugin shows as FAULTED, cannot be enabled.

Causes:

• Manifest validation failed

• Missing required files

• Dependency conflicts

• Database migration errors

• Bootstrap class errors

Solutions:

1. Check plugin info for error details:

php bin/console pteroca:plugin:info my-plugin

1. Reset the plugin:

php bin/console pteroca:plugin:reset my-plugin

1. Review logs:

tail -f var/log/prod.log

1. Verify file structure matches plugin requirements

2. Check dependencies are installed and enabled

Dependency Conflicts

Symptoms: Cannot enable plugin due to dependency errors.

Solutions:

1. View dependency tree:

php bin/console pteroca:plugin:depends my-plugin

1. Install with dependencies:

php bin/console pteroca:plugin:enable my-plugin --with-dependencies

1. Check for circular dependencies - these cannot be resolved

2. Update conflicting plugins to compatible versions

Missing Autoload Classes

Symptoms: "Class not found" errors, plugin fails to load.

Solutions:

1. Verify namespace matches folder structure:

Namespace: Plugins\MyPlugin\Controller\FooController
File path: plugins/my-plugin/src/Controller/FooController.php

1. Check composer autoload if plugin uses composer.json

2. Clear cache:

php bin/console cache:clear

1. Reinstall plugin dependencies:

php bin/console pteroca:plugin:install-deps my-plugin

Migration Failures

Symptoms: Plugin enables but database changes fail.

Solutions:

1. Check migration SQL syntax (must be MySQL/MariaDB compatible)

2. Verify table names use plg_ prefix

3. Check database user permissions for CREATE/ALTER/DROP

4. Review migration files for errors:

ls plugins/my-plugin/Migrations/

1. Manually fix database if needed, then reset plugin

Assets Not Loading

Symptoms: CSS/JS not loading, broken images.

Solutions:

1. Republish assets:

php bin/console pteroca:plugin:assets:publish my-plugin --force

1. Check symlink/file exists:

ls -la public/assets/plugins/my-plugin/

1. Verify asset paths in plugin.json match actual files

2. Check web server permissions on public/assets/

3. Use correct asset function in templates:

{{ plugin_asset('my-plugin', 'css/style.css') }}

Configuration Issues

Symptoms: Plugin enabled but not working, configuration errors.

Solutions:

1. Check required settings are configured via Admin Panel (Settings → Plugins)

2. Validate settings values match expected format

3. Check permission - do you have edit_settings_plugin?

4. Review plugin documentation for configuration requirements

5. Check plugin logs for configuration validation errors

Security Scan Blocking Enable

Symptoms: Cannot enable due to security issues.

Solutions:

1. View detailed scan results:

php bin/console pteroca:plugin:security-scan my-plugin --detailed

1. CRITICAL issues must be fixed - contact plugin developer

2. HIGH/MEDIUM issues - evaluate risk, enable at your own discretion

3. Update plugin to latest version with security fixes

4. Report issues to plugin developer

Need More Help?

If you're still experiencing issues:

• Check the complete Troubleshooting Guide

• Review plugin-specific documentation

• Contact plugin developer for support

• Report bugs on GitHub Issues

---

Creating Your Own Plugins

If you're a developer interested in creating custom plugins for PteroCA, see the complete Plugin Development Guide in the "For Developers" section.

The developer guide includes:

• Technical architecture and plugin structure

• Manifest schema and configuration

• Code examples and best practices

• API reference and hooks

• Testing and debugging guides

---

Related Documentation

User Guides

• CLI Reference - Complete plugin management commands

• Roles & Permissions - Plugin permissions system

• Customization - General customization options

• Troubleshooting - General troubleshooting guide

Developer Resources

• Plugin Development - Complete developer guide

• Theme Development - Creating custom themes

Community and Support

• FAQ - Frequently asked questions

• GitHub Issues - Report bugs and request features

• Discord Community - Get help and discuss with other users

Need Help?

If you have questions about plugins or need assistance:

• Check the FAQ

• Review the Plugin Development Guide

• Ask in the Discord community

• Report issues on GitHub