wheels plugins

Base command for plugin management in Wheels applications.

Synopsis

wheels plugins [subcommand] [options]

Description

The wheels plugins command provides comprehensive plugin management for Wheels applications. It handles plugin discovery, installation, configuration, and lifecycle management.

Subcommands

Command	Description
list	List installed plugins
search	Search for plugins on ForgeBox
info	Show detailed plugin information
install	Install a plugin
update	Update a specific plugin
update:all	Update all installed plugins
outdated	List plugins with available updates
remove	Remove a plugin
init	Initialize a new plugin project

Options

Option	Description
--help	Show help information
--version	Show version information

Direct Usage

When called without subcommands, displays plugin overview:

wheels plugins

Output:

Wheels Plugin Manager
====================

Installed Plugins: 5
├── authentication (v2.1.0) - User authentication system
├── pagination (v1.5.2) - Advanced pagination helpers
├── validation (v3.0.1) - Extended validation rules
├── caching (v2.2.0) - Enhanced caching strategies
└── api-tools (v1.8.3) - RESTful API utilities

Available Updates: 2
- validation: v3.0.1 → v3.1.0
- api-tools: v1.8.3 → v2.0.0

Run 'wheels plugins list' for detailed information

Examples

Show plugin overview

wheels plugins

Quick plugin check

wheels plugins --check

Update all plugins

wheels plugins --update-all

Plugin system info

wheels plugins --info

Plugin System

Plugin Structure

/plugins/
├── authentication/
│   ├── Authentication.cfc
│   ├── config/
│   ├── models/
│   ├── views/
│   └── plugin.json
├── pagination/
└── ...

Plugin Metadata

Each plugin contains plugin.json:

{
  "name": "authentication",
  "version": "2.1.0",
  "description": "User authentication system",
  "author": "Wheels Community",
  "wheels": ">=2.0.0",
  "dependencies": {
    "validation": ">=3.0.0"
  }
}

Plugin Registry

Official Registry

Default source for plugins:

https://www.forgebox.io/type/cfwheels-plugins/

Custom Registries

Configure additional sources:

{
  "pluginRegistries": [
    "https://www.forgebox.io/type/cfwheels-plugins/",
    "https://company.com/wheels-plugins/"
  ]
}

Plugin Lifecycle

Discovery

# Search for plugins
wheels plugins search authentication

# Browse categories
wheels plugins browse --category=security

Installation

# Install from registry
wheels plugins install authentication

# Install from GitHub
wheels plugins install github:user/wheels-plugin

# Install from file
wheels plugins install ./my-plugin.zip

Configuration

# Configure plugin
wheels plugins configure authentication

# View configuration
wheels plugins config authentication

Updates

# Check for updates
wheels plugins outdated

# Update specific plugin
wheels plugins update authentication

# Update all plugins
wheels plugins update --all

Plugin Development

Create Plugin

# Generate plugin scaffold
wheels generate plugin my-plugin

# Plugin structure created:
# /plugins/my-plugin/
#   ├── MyPlugin.cfc
#   ├── plugin.json
#   ├── config/
#   ├── tests/
#   └── README.md

Plugin API

component extends="wheels.Plugin" {
    
    function init() {
        this.version = "1.0.0";
        this.author = "Your Name";
        this.description = "Plugin description";
    }
    
    function setup() {
        // Plugin initialization
    }
    
    function teardown() {
        // Plugin cleanup
    }
}

Environment Support

Environment-Specific Plugins

{
  "plugins": {
    "production": ["caching", "monitoring"],
    "development": ["debug-toolbar", "profiler"],
    "all": ["authentication", "validation"]
  }
}

Conditional Loading

// In environment.cfm
if (get("environment") == "development") {
    addPlugin("debug-toolbar");
}

Plugin Commands

Plugins can register custom commands:

// In plugin
this.commands = {
    "auth:create-user": "commands/CreateUser.cfc",
    "auth:reset-password": "commands/ResetPassword.cfc"
};

Usage:

wheels auth:create-user [email protected]
wheels auth:reset-password user123

Dependency Management

Automatic Resolution

# Installs plugin and dependencies
wheels plugins install api-tools
# Also installs: validation, serialization

Conflict Resolution

# When conflicts exist
wheels plugins install authentication --resolve=prompt

Options:

• prompt: Ask for each conflict

• newest: Use newest version

• oldest: Keep existing version

Plugin Storage

Global Plugins

Shared across projects:

wheels plugins install authentication --global

Location: ~/.wheels/plugins/

Project Plugins

Project-specific:

wheels plugins install authentication

Location: /plugins/

Security

Plugin Verification

# Verify plugin signatures
wheels plugins verify authentication

# Install only verified plugins
wheels plugins install authentication --verified-only

Permission Control

{
  "pluginPermissions": {
    "fileSystem": ["read", "write"],
    "network": ["http", "https"],
    "database": ["read", "write"]
  }
}

Troubleshooting

Common Issues

1. Plugin Not Loading

   wheels plugins diagnose authentication

2. Dependency Conflicts

   wheels plugins deps --tree

3. Version Incompatibility

   wheels plugins check-compatibility

Best Practices

1. Version Lock: Lock plugin versions for production

2. Test Updates: Test in development first

3. Backup: Backup before major updates

4. Documentation: Document custom plugins

5. Security: Verify plugin sources

Plugin Cache

Clear Cache

wheels plugins cache clear

Rebuild Cache

wheels plugins cache rebuild

Notes

• Plugins are loaded in dependency order

• Some plugins require application restart

• Global plugins override project plugins

• Plugin conflicts are resolved by load order

See Also

• wheels plugin list - List plugins

• wheels plugin search - Search for plugins

• wheels plugin info - Show plugin details

• wheels plugin install - Install plugins

• wheels plugin update - Update plugins

• wheels plugin update:all - Update all plugins

• wheels plugin outdated - Check for updates

• wheels plugin remove - Remove plugins

• wheels plugin init - Create new plugin

• Plugin Development Guide