Plugins Management

Overview

The Plugins module provides a powerful extensibility system that allows you to add custom functionality to your admin panel without modifying the core codebase. You can install, activate, deactivate, and manage third-party plugins or develop your own using the built-in scaffolding tool. This module gives you complete control over plugin lifecycle management, settings configuration, and activity monitoring.

Accessing Plugins Management

Navigation: Dashboard > Advanced Features > Plugins

Required Permission: plugins.view

Key Features

• Plugin Installation: Upload and install plugins from ZIP files
• Plugin Activation/Deactivation: Enable or disable plugins without uninstalling them
• Plugin Scaffolding: Generate complete plugin boilerplate code with proper structure
• Settings Management: Configure plugin-specific settings through a unified interface
• Activity Logging: Track all plugin-related actions and changes
• Cache Management: Clear plugin caches to ensure fresh data
• Metadata Management: Update plugin information, icons, and requirements

Main Interface

List View

The plugins list displays all installed plugins in a card-based layout with the following information:

Plugin Card Information:

• Icon: Plugin logo or default icon
• Name: Plugin display name
• Version: Current plugin version number
• Author: Plugin developer name
• Description: Brief description of plugin functionality
• Status Badge: Active, Inactive, or Installed indicator
• Action Buttons: Activate, Deactivate, Settings, Delete

Available Filters:

• Status Filter: Show all plugins, only active, or only inactive plugins
• Search: Filter plugins by name, author, or description

Sorting:

• Plugins are sorted alphabetically by name by default
• All plugins are displayed on a single page (no pagination)

Actions Available

• View Details: Click on a plugin card to see full details, settings, and activity logs
• Activate Plugin: Enable an inactive plugin to load its functionality
• Deactivate Plugin: Disable an active plugin without uninstalling it
• Configure Settings: Manage plugin-specific configuration options
• Update Metadata: Edit plugin information, icon, and requirements
• Clear Cache: Remove cached plugin data
• Uninstall Plugin: Completely remove a plugin and its files

Common Tasks

Installing a Plugin

1. Click the "Install Plugin" button in the top right corner
2. Fill in the installation form:
   • Plugin File: Upload the plugin ZIP file (required, max 10MB)
   • Homepage: Plugin website URL (optional)
   • Keywords: Comma-separated tags for categorization (optional)
   • License: License type (optional, defaults to MIT)
   • Icon File: Upload a custom icon image (optional, max 2MB)
3. Click "Install Plugin" to upload and extract

Validation Rules:

• Plugin file must be a valid ZIP archive
• ZIP must contain a plugin.json manifest file
• Manifest must include: name, slug, version, service_provider
• Plugin slug must be unique (not already installed)
• Plugin slug must contain only lowercase letters, numbers, and hyphens
• Version must follow semantic versioning (e.g., 1.0.0)

What Happens:

• ZIP file is uploaded and extracted to storage/app/plugins/
• Plugin manifest is validated for required fields and format
• Plugin requirements (PHP version, Laravel version, extensions) are checked
• Plugin record is created in the database with status "installed"
• Installation is logged in plugin activity logs
• Plugin files are ready but not yet active

Installation Process:

1. File upload and validation
2. ZIP extraction to temporary directory
3. Manifest validation
4. Requirements checking
5. Files moved to permanent plugin directory
6. Database record creation
7. Activity logging
8. Cache clearing

Activating a Plugin

1. Find the plugin in the list (status should be "Inactive" or "Installed")
2. Click the "Activate" button on the plugin card
3. Confirm activation if prompted

What Happens:

• Plugin service provider is registered with Laravel
• Plugin routes are loaded (web, API, admin)
• Plugin views, migrations, and translations are registered
• Plugin's activate() hook is called if defined
• Database migrations are run automatically
• Plugin assets are published to public/plugins/
• Plugin status is updated to "active"
• Activation timestamp is recorded
• Activity is logged
• Caches are cleared

Requirements for Activation:

• Plugin must be installed
• Plugin files must exist in the plugins directory
• Service provider class must be valid
• All plugin requirements must be met

Deactivating a Plugin

1. Find the active plugin in the list
2. Click the "Deactivate" button on the plugin card
3. Confirm deactivation if prompted

What Happens:

• Plugin service provider is unregistered
• Plugin routes are removed from routing table
• Plugin's deactivate() hook is called if defined
• Plugin status is updated to "inactive"
• Deactivation timestamp is recorded
• Activity is logged
• Plugin cache is cleared

Important Notes:

• Deactivation does not remove plugin files or database tables
• Plugin settings are preserved
• Plugin can be reactivated at any time
• Use deactivation for temporary disabling or troubleshooting

Configuring Plugin Settings

1. Click on a plugin card to view its details
2. Navigate to the "Settings" tab
3. View all current plugin settings in a table format
4. To add or update a setting:
   • Click "Add Setting" or "Edit" next to an existing setting
   • Enter the setting key (e.g., "api_key", "max_items")
   • Enter the setting value
   • Select the data type: string, boolean, integer, float, or json
   • Check "Encrypted" if the value should be stored securely (for API keys, passwords)
   • Click "Save"
5. To delete a setting:
   • Click "Delete" next to the setting
   • Confirm the deletion

Setting Types:

• String: Text values (default)
• Boolean: True/false values
• Integer: Whole numbers
• Float: Decimal numbers
• JSON: Complex data structures

Encrypted Settings:

• Use encryption for sensitive data like API keys, passwords, tokens
• Encrypted values are automatically decrypted when retrieved
• Encryption uses Laravel's built-in encryption system

Viewing Plugin Details

1. Click on any plugin card in the list
2. The details page shows multiple tabs:

Overview Tab:

• Plugin name, version, author, description
• Homepage link and license information
• Keywords and requirements
• Installation and activation dates
• Current status

Settings Tab:

• All plugin configuration settings
• Add, edit, or delete settings
• View setting types and encryption status

Activity Logs Tab:

• Complete history of plugin actions
• Shows: action type, user who performed it, timestamp, metadata
• Actions include: installed, activated, deactivated, uninstalled, settings changed
• Paginated list of most recent 20 activities

Metadata Tab:

• Edit plugin information
• Update homepage URL
• Modify keywords and license
• Change plugin icon
• Update requirements

Updating Plugin Metadata

1. View the plugin details page
2. Go to the "Metadata" tab
3. Update any of the following fields:
   • Homepage: Plugin website URL
   • Keywords: Comma-separated tags
   • License: License type (e.g., MIT, GPL, Apache)
   • Requirements: PHP version, Laravel version, required extensions
   • Icon: Upload a new icon image or remove existing icon
4. Click "Update Metadata" to save changes

Icon Requirements:

• Supported formats: JPEG, PNG, GIF, SVG, WebP
• Maximum file size: 2MB
• Recommended size: 512x512 pixels
• Icons are automatically optimized and converted to WebP

Clearing Plugin Cache

Clear Single Plugin Cache:

1. View the plugin details page
2. Click the "Clear Cache" button
3. Cache for that specific plugin is cleared

Clear All Plugin Caches:

1. From the plugins list page
2. Click the "Clear All Caches" button in the top toolbar
3. All plugin caches are cleared system-wide

When to Clear Cache:

• After updating plugin settings
• When plugin behavior seems incorrect
• After manually modifying plugin files
• When troubleshooting plugin issues

Uninstalling a Plugin

1. Find the plugin in the list
2. If the plugin is active, deactivate it first
3. Click the "Uninstall" button (trash icon)
4. Confirm the uninstallation in the popup dialog
5. Plugin is completely removed

What Happens:

• Plugin is deactivated if currently active
• Plugin's deactivate() hook is called
• Uninstallation is logged before removal
• Plugin record is deleted from database
• Plugin files and directories are removed from storage
• All plugin caches are cleared

Important Notes:

• Uninstallation is permanent and cannot be undone
• Plugin database tables are NOT automatically removed (manual cleanup may be needed)
• Plugin settings are removed from the database
• Plugin activity logs are preserved for audit purposes
• You must reinstall the plugin to use it again

Creating a Plugin with Scaffolding

1. Click the "Scaffold Plugin" button in the top toolbar
2. Fill in the scaffolding form:
   • Plugin Name: Display name (required, e.g., "My Custom Plugin")
   • Slug: URL-friendly identifier (optional, auto-generated from name)
   • Namespace: PHP namespace (optional, auto-generated from name)
   • Author: Your name or organization (required)
   • Author Email: Contact email (optional)
   • Description: Brief description of plugin functionality (required, max 500 chars)
   • Model Name: Primary model class name (optional, defaults to "Item")
   • Version: Semantic version number (optional, defaults to "1.0.0")
   • License: License type (optional, defaults to "MIT")
   • Homepage: Plugin website URL (optional)
   • Keywords: Comma-separated tags (optional)
3. Click "Generate Scaffold" to create the plugin structure

What Happens:

• Complete plugin directory structure is created in storage/app/plugin-development/
• All necessary files are generated from templates:
  • plugin.json - Plugin manifest
  • composer.json - Dependency management
  • Service provider class
  • Controllers (Frontend and Admin)
  • Model with basic CRUD
  • Database migration
  • Routes (web, API, admin)
  • Views (frontend and admin)
  • Configuration files
  • README documentation
  • Test files (Feature and Unit)
• Success message shows the path to your new plugin
• Plugin is ready for development but not yet installed

Generated Directory Structure:

storage/app/plugin-development/your-plugin-slug/
├── plugin.json
├── composer.json
├── README.md
├── src/
│   ├── YourPluginServiceProvider.php
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Admin/
│   │   │   └── Frontend/
│   │   ├── Middleware/
│   │   └── Requests/
│   ├── Models/
│   ├── Services/
│   └── Console/Commands/
├── database/
│   ├── migrations/
│   ├── seeders/
│   └── factories/
├── resources/
│   ├── views/
│   ├── assets/
│   └── lang/
├── routes/
│   ├── web.php
│   ├── api.php
│   └── admin.php
├── config/
├── tests/
│   ├── Feature/
│   └── Unit/
└── docs/

Next Steps After Scaffolding:

1. Navigate to the generated plugin directory
2. Customize the generated code for your needs
3. Add your business logic to controllers and models
4. Create your views and assets
5. Write tests for your functionality
6. Package the plugin as a ZIP file
7. Install it through the admin interface

Settings and Options

Plugin File Field

• Type: File upload
• Required: Yes
• Accepted Formats: ZIP archives only
• Max Size: 10MB (10,240 KB)
• Description: The plugin package containing all plugin files and manifest
• Notes: Must contain a valid plugin.json file in the root

Homepage Field

• Type: URL input
• Required: No
• Max Length: 255 characters
• Validation: Must be a valid URL format
• Description: Link to the plugin's website or documentation
• Example: "https://example.com/my-plugin"

Keywords Field

• Type: Array of strings
• Required: No
• Max Items: Unlimited
• Max Length per Keyword: 50 characters
• Description: Tags for categorizing and searching plugins
• Example: ["ecommerce", "payment", "stripe"]

License Field

• Type: Text input
• Required: No
• Max Length: 50 characters
• Default: "MIT"
• Description: The license under which the plugin is distributed
• Common Values: MIT, GPL-3.0, Apache-2.0, BSD-3-Clause

Requirements Field

• Type: JSON object
• Required: No
• Description: System requirements for the plugin
• Structure:

  {
    "php": ">=8.2",
    "laravel": ">=11.0",
    "extensions": ["gd", "curl", "mbstring"]
  }
  

Icon Field

• Type: Text input or file upload
• Required: No
• Max Length: 255 characters (for path)
• Max Size: 2MB (for upload)
• Accepted Formats: JPEG, PNG, GIF, SVG, WebP
• Description: Plugin icon displayed in the admin interface
• Notes: Can be a file path or uploaded image

Setting Key Field

• Type: Text input
• Required: Yes
• Max Length: 255 characters
• Format: Lowercase with underscores (e.g., "api_key", "max_items")
• Description: Unique identifier for the setting within the plugin

Setting Value Field

• Type: Text input, textarea, or JSON editor (depends on type)
• Required: Yes
• Description: The actual setting value
• Notes: Format depends on the selected type

Setting Type Field

• Type: Select dropdown
• Required: Yes
• Options: string, boolean, integer, float, json
• Description: Data type for proper value casting and validation

Is Encrypted Field

• Type: Checkbox
• Required: No
• Default: false
• Description: Whether the setting value should be encrypted in the database
• Use Cases: API keys, passwords, tokens, sensitive credentials

Permissions

The following permissions control access to the Plugins module:

• plugins.view: Can view the plugins list and plugin details
• plugins.install: Can install new plugins from ZIP files
• plugins.activate: Can activate installed plugins
• plugins.deactivate: Can deactivate active plugins
• plugins.configure: Can manage plugin settings
• plugins.uninstall: Can uninstall plugins
• plugins.scaffold: Can use the plugin scaffolding tool

Permission Hierarchy:

• Viewing plugins is the base permission required to access the module
• Installing, activating, and deactivating require their respective permissions
• Configuring settings is a separate permission for security
• Uninstalling requires the highest level of access
• Scaffolding is typically restricted to developers

Tips and Best Practices

• Test in Development First: Always test new plugins in a development environment before installing on production
• Backup Before Installing: Create a backup before installing or activating plugins
• Review Plugin Code: If possible, review plugin source code for security and quality
• Keep Plugins Updated: Regularly check for and install plugin updates
• Deactivate Unused Plugins: Deactivate plugins you're not using to improve performance
• Use Descriptive Settings Keys: Use clear, descriptive names for plugin settings (e.g., "stripe_api_key" not "key1")
• Encrypt Sensitive Data: Always enable encryption for API keys, passwords, and tokens
• Monitor Activity Logs: Review plugin activity logs to track changes and troubleshoot issues
• Clear Cache After Changes: Clear plugin cache after modifying settings or files
• Document Custom Plugins: Maintain good documentation for custom plugins you develop
• Follow Naming Conventions: Use kebab-case for slugs, PascalCase for class names
• Version Your Plugins: Use semantic versioning for plugin releases
• Test Plugin Interactions: Test how plugins interact with each other and core functionality

Troubleshooting

Problem: Plugin Installation Fails - "Invalid JSON in plugin manifest"

Solution: The plugin.json file in the ZIP archive is malformed. Extract the ZIP, validate the JSON syntax using a JSON validator, fix any errors, and re-package the plugin.

Problem: Plugin Installation Fails - "Plugin with slug already exists"

Solution: A plugin with the same slug is already installed. Either uninstall the existing plugin first, or change the slug in the new plugin's manifest file.

Problem: Plugin Activation Fails - "Service provider class not found"

Solution: The service provider class specified in plugin.json doesn't exist or has the wrong namespace. Check that:

• The class file exists in the correct location
• The namespace in the class matches the manifest
• The class extends BasePluginServiceProvider
• File permissions allow reading the file

Problem: Plugin Routes Not Working After Activation

Solution:

• Clear the route cache: php artisan route:clear
• Check for route conflicts with other plugins or core routes
• Verify the routes files exist in the plugin's routes/ directory
• Check that route middleware is properly configured
• Review plugin activity logs for error messages

Problem: Plugin Settings Not Saving

Solution:

• Verify you have the plugins.configure permission
• Check that the setting key is unique within the plugin
• Ensure the value matches the selected type (e.g., valid JSON for json type)
• Check browser console for JavaScript errors
• Review server logs for validation errors

Problem: Cannot Uninstall Plugin - Files Remain

Solution: This can happen on Windows systems with file locking. Try:

• Close any applications that might be accessing plugin files
• Wait a few moments and try again
• Manually delete the plugin directory from storage/app/plugins/
• Check file permissions on the plugins directory

Problem: Plugin Icon Not Displaying

Solution:

• Verify the icon file was uploaded successfully
• Check that the image format is supported (JPEG, PNG, GIF, SVG, WebP)
• Ensure the file size is under 2MB
• Clear browser cache and plugin cache
• Check file permissions on the media storage directory

Problem: Scaffolded Plugin Won't Install

Solution: After scaffolding, you need to:

1. Package the plugin directory as a ZIP file
2. Ensure the ZIP contains the plugin files at the root level (not in a subdirectory)
3. Verify plugin.json is in the root of the ZIP
4. Install through the admin interface like any other plugin

Problem: Plugin Causing Site Errors

Solution:

• Immediately deactivate the plugin
• Check Laravel logs in storage/logs/ for error details
• Review plugin activity logs for clues
• Contact the plugin author with error details
• If critical, manually remove the plugin from the database and file system

Problem: Plugin Cache Not Clearing

Solution:

• Try clearing all caches from the command line: php artisan cache:clear
• Check that the cache driver is properly configured
• Verify file permissions on the cache directory
• Restart the queue worker if using queue-based caching
• Check for Redis/Memcached connection issues if using those drivers

Related Modules

• Settings: Configure global system settings that plugins may interact with
• Audit Logs: Review all plugin-related activities and changes
• Permissions: Control who can manage plugins
• Backups: Create backups before installing or updating plugins