README

A complete and production-ready plugin management system for Symfony applications.

Features

Core Plugin Management

Plugin Discovery: Automatic discovery of plugins implementing PluginBundleInterface
Activation/Deactivation: Full lifecycle management with validation pipeline
Dependency Management: Declare dependencies between plugins with version constraints
Status Tracking: Three plugin states (ACTIVE, INACTIVE, FORCED)

Advanced Features

Validation Pipeline: Multi-validator system (PHPStan, Composer, Kernel, Dependencies)
Event System: Pre/post activation and deactivation events with cancelation support
Artifact Scanning: Automatic detection of routes, services, entities, migrations
Composer Integration: Automatic symlink management and dependency installation
CLI Commands: Complete command-line interface for plugin management

Routing & Services

3-Level Routing: Package → Bundle → Context organization
Environment-Aware: Services and routes per environment (dev, prod, test)
Multi-Context: Support for admin, api, public, secured contexts
Multiple Formats: YAML, XML, PHP configuration files

Installation

composer require ksf/plugins-bundle

Enable the Bundle

Add to config/bundles.php:

return [
    // ...
    Ksf\Core\Plugins\KsfPluginsBundle::class => ['all' => true],
];

Configure

Create config/packages/ksf_plugins.yaml:

ksf_plugins:
    plugins_directory: '%kernel.project_dir%/plugins'

    validation:
        enabled: true
        phpstan:
            enabled: true
            level: 8
            configuration: '%kernel.project_dir%/phpstan.neon'
        composer:
            enabled: true
        kernel:
            enabled: true

Quick Start

1. Create a Plugin

<?php

namespace App\Plugin\MyPlugin;

use Ksf\Core\Plugins\Contract\AbstractPluginBundle;

class MyPluginBundle extends AbstractPluginBundle
{
    public function getCode(): string
    {
        return 'my_plugin';
    }

    public function getEnvironments(): string|array
    {
        return 'all'; // or ['dev', 'prod']
    }
}

2. Discover & Activate

# Discover new plugins
bin/console plugin:discover

# List all plugins
bin/console plugin:list

# Activate a plugin
bin/console plugin:activate my_plugin

# Activate with dependencies
bin/console plugin:activate my_plugin --with-dependencies

3. Manage Plugin Structure

plugins/my-plugin/
├── src/
│   └── MyPluginBundle.php
├── config/
│   ├── routes/
│   │   ├── 1-packages/
│   │   │   └── my_plugin.yaml
│   │   ├── 2-bundles/
│   │   │   └── my_plugin.yaml
│   │   └── 3-contexts/
│   │       ├── admin/
│   │       │   └── my_plugin.yaml
│   │       └── api/
│   │           └── my_plugin.yaml
│   └── services/
│       ├── 1-packages/
│       │   └── my_plugin.yaml
│       ├── 2-bundles/
│       │   └── my_plugin.yaml
│       └── 3-contexts/
│           └── admin.yaml
├── migrations/
├── src/Entity/
└── composer.json

CLI Commands

Command	Description
`plugin:list`	List all plugins with status and filters
`plugin:activate <code>`	Activate a plugin
`plugin:deactivate <code>`	Deactivate a plugin
`plugin:discover`	Discover new plugins
`plugin:info <code>`	Display plugin information and artifacts
`plugin:dependencies <code>`	Show plugin dependencies
`plugin:clean-duplicates`	Clean duplicate plugin entries

Documentation

Getting Started

Core Features

Advanced Topics

Key Concepts

Plugin States

State	Description	Managed
ACTIVE	Enabled via Plugin Manager	✅ Yes
INACTIVE	Installed but disabled	✅ Yes
FORCED	Manually declared in bundles.php	❌ No

Dependency Management

Declare dependencies between plugins:

public function getDependencies(): array
{
    return [
        'other_plugin' => '^1.0',  // Semantic versioning
        'base_plugin' => '~2.3',   // Compatible with 2.3.x
    ];
}

Features:

✅ Version constraint validation
✅ Circular dependency detection
✅ Topological sort for load order
✅ Cascade activation
✅ Deactivation prevention

Validation Pipeline

Multi-step validation before activation:

PHPStan Validator: Static analysis at configured level
Composer Validator: Dependency validation
Kernel Validator: Symfony kernel boot test
Dependency Validator: Plugin dependencies check

Each validator can report:

❌ ERROR: Blocks activation
⚠️ WARNING: Allows activation with warning
ℹ️ INFO: Informational message

Event System

Listen to plugin lifecycle events:

use Ksf\Core\Plugins\Event\PluginActivatingEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class PluginListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            PluginActivatingEvent::class => 'onPluginActivating',
        ];
    }

    public function onPluginActivating(PluginActivatingEvent $event): void
    {
        // Cancel activation if needed
        if ($someCondition) {
            $event->stopPropagation();
        }
    }
}

Available events:

PluginActivatingEvent - Before activation (cancelable)
PluginActivatedEvent - After activation
PluginDeactivatingEvent - Before deactivation (cancelable)
PluginDeactivatedEvent - After deactivation

Requirements

PHP 8.1 or higher
Symfony 6.4 or 7.x
Composer

Testing

# Run all tests
vendor/bin/phpunit

# Run specific test suite
vendor/bin/phpunit --testsuite=Core
vendor/bin/phpunit --testsuite=Functional

# Run with coverage
vendor/bin/phpunit --coverage-html coverage/

Contributing

Follow BadPixxel coding standards (PSR-12 + PHPStan)
Run quality checks before committing:
```
make quality
```
Write tests for new features
Update documentation

License

This bundle is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

For the full copyright and license information, please view the LICENSE file that was distributed with this source code.

Support

Issues: Report bugs on GitHub
Documentation: See /docs directory
Examples: See docs/examples.md

krystal-sf / plugin-manager

Maintainers

Details