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

Documentation

Getting Started

• Installation & Configuration
• Creating Your First Plugin
• Architecture Overview

Core Features

• Activation Workflow
• Dependency Management
• Validation Pipeline
• Event System

Advanced Topics

• Routing System
• Services Configuration
• CLI Commands Reference
• Examples & Use Cases

Key Concepts

Plugin States

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:

1. PHPStan Validator: Static analysis at configured level
2. Composer Validator: Dependency validation
3. Kernel Validator: Symfony kernel boot test
4. 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

1. Follow BadPixxel coding standards (PSR-12 + PHPStan)
2. Run quality checks before committing:

   make quality
   

3. Write tests for new features
4. 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

Copyright (C) BadPixxel <www.badpixxel.com>