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>