Plugin System

Plugin System

Understanding Plugins

What are Plugins?

Plugins are self-contained extensions that:

• Extend Functionality - Add new features to your forum
• Modify Behavior - Change how things work
• Integrate Services - Connect with external APIs
• Customize Experience - Tailor forum to your needs

Plugin Architecture

Plugins follow a structured architecture:

plugins/
└── my-plugin/
    ├── plugin.json          # Plugin metadata
    ├── MyPlugin.php         # Main plugin class
    ├── assets/              # CSS, JS, images
    │   ├── css/
    │   ├── js/
    │   └── img/
    ├── views/               # Template files
    │   └── admin.php
    └── README.md            # Documentation

Installing Plugins

Method 1: From the Admin Panel (Recommended, since 5.2.2)

1. Download the plugin .zip from the Flatboard Resource Center or from the plugin author
2. Go to Admin → Plugins
3. Click "Install a plugin"
4. Select the .zip archive and confirm — the archive is validated, extracted, and the plugin appears in the list automatically

The server validates the archive integrity, MIME type, size, and the presence of a valid plugin.json before extracting.

Method 2: Manual Installation (FTP / SSH)

Plugin packages are distributed as .zip archives. The manual workflow is: download → extract locally → upload the folder → activate.

Step 1: Download and Extract

1. Download the plugin .zip from the Flatboard Resource Center or from the plugin author
2. Verify that the plugin is compatible with your Flatboard 5 version
3. Extract the archive on your local machine — you should get a folder (e.g. my-plugin/) with plugin.json at its root

Step 2: Upload the Plugin Folder

Via FTP

Connect to your server with an FTP client (FileZilla, Cyberduck, etc.) and upload the extracted plugin folder into the plugins/ directory of your Flatboard installation:

your-flatboard/
└── plugins/
    └── my-plugin/        ← upload this folder (not the .zip)
        ├── plugin.json
        └── ...

Via SSH

If you have shell access, you can extract the archive directly on the server:

cd /path/to/your-flatboard/plugins/
unzip my-plugin.zip          # extracts to my-plugin/
chmod 755 my-plugin/ -R      # adjust permissions if needed

Step 3: Activate the Plugin

Once the plugin folder is in place:

1. Go to Admin → Plugins
2. Find the plugin in the list — it will appear as inactive
3. Click Activate

Step 4: Configure (if applicable)

If the plugin has settings, click the settings icon next to the plugin name, fill in the options, and save.

Creating a Plugin

Step 1: Create Plugin Structure

mkdir -p plugins/my-plugin/{assets/{css,js,img},views}

Step 2: Create plugin.json

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "A custom plugin for Flatboard 5",
  "author": "Your Name",
  "license": "GPL3",
  "requires": {
    "flatboard": ">=5.0.0"
  },
  "class": "App\\Plugins\\MyPlugin\\MyPluginPlugin"
}

Step 3: Create Plugin Class

plugins/my-plugin/MyPluginPlugin.php:

<?php
namespace App\Plugins\MyPlugin;

use App\Core\Plugin;

class MyPluginPlugin
{
    public function boot()
    {
        // Register hooks
        Plugin::hook('view.header.content', [$this, 'addHeaderContent']);
        Plugin::hook('app.routes.register', [$this, 'registerRoutes']);
    }

    public function addHeaderContent(&$content)
    {
        $content .= '<link rel="stylesheet" href="proxy.php?url=/plugins/my-plugin/assets/css/style.css">';
    }

    public function registerRoutes($router)
    {
        $router->get('/my-plugin', function() {
            return 'Hello from my plugin!';
        });
    }
}

Step 4: Register Hooks

Flatboard 5 provides many hooks:

• app.routes.register - Register custom routes
• view.header.styles - Add CSS styles to header
• view.footer.content - Add content to footer
• view.post.avatar - Override post avatar rendering
• view.user.avatar - Override user avatar rendering anywhere on the forum
• discussion.created - When discussion is created
• post.created - When post is created
• user.registered - When user registers
• user.updated - When user is updated
• notification.types.register - Register custom notification types
• visitor.page_info - Provide page metadata for presence indicator

See the complete hook list below for all available hooks.

Plugin Hooks

Available Hooks

Complete reference of all 74 hooks available in Flatboard 5. All data arguments marked by ref are passed by PHP reference — modifying them changes the actual value used by the framework.

Application

View — Layout

View — Banner

View — SEO

View — Auth Forms

View — Discussions & Replies

Content Events

User Events

Moderation

Search

Notifications

Markdown & Editor

Presence & Visitor Tracking

Admin

Plugin Views

Webhooks

Using Hooks

// Register a hook
Plugin::hook('discussion.created', function($discussion) {
    // Do something when discussion is created
    Logger::info("New discussion: " . $discussion['title']);
});

// Register with priority
Plugin::hook('post.created', [$this, 'handlePostCreated'], 10);

// Extend the notification type whitelist (by reference)
Plugin::hook('notification.types.register', function(array &$types): void {
    $types[] = 'my_custom_type';
    $types[] = 'reputation_badge';
});

// Override avatar rendering for a virtual user (by reference)
Plugin::hook('view.user.avatar', function(array &$data): void {
    if ($data['user_id'] === 'my-bot') {
        $data['html'] = '<span class="avatar-bot"><i class="fas fa-robot"></i></span>';
    }
});

Plugin Configuration

Settings Storage

Plugin settings are stored in the "plugin" section of plugin.json and accessed via Plugin::getData(). Do not use Config::get/set for plugin-specific settings.

use App\Core\Plugin;

// Read a setting (with optional default)
$value = Plugin::getData('my-plugin', 'setting', 'default');

// Dot-notation is supported for nested keys
$host = Plugin::getData('my-plugin', 'smtp.host', '');

// Write a setting (in-memory only)
Plugin::setData('my-plugin', 'setting', 'value');

// Persist all settings to plugin.json
Plugin::saveData('my-plugin', ['setting' => 'value', 'another' => 'data']);

Admin Interface

Create admin settings page:

1. Create view file: views/admin.php
2. Register admin route
3. Handle form submission
4. Save settings to config

Best Practices

Plugin Development

• Follow Structure - Use standard plugin structure
• Namespace Properly - Use proper namespaces
• Document Code - Add comments and documentation
• Handle Errors - Implement error handling
• Test Thoroughly - Test before release

Security

• Validate Input - Always validate user input
• Sanitize Output - Sanitize all output
• Check Permissions - Verify user permissions
• Use CSRF Protection - Protect forms with CSRF tokens

Performance

• Lazy Load - Load assets only when needed
• Cache When Possible - Cache expensive operations
• Minimize Queries - Optimize database/file access
• Use Hooks Efficiently - Don't overload hooks

Managing Plugins

Activating/Deactivating

• Activate - Enable plugin functionality
• Deactivate - Disable without uninstalling

Uninstalling a Plugin

Uninstalling permanently removes a plugin and all its data from your forum.

Using the Admin Panel

1. Navigate to Admin → Plugins
2. Deactivate the plugin first — the Uninstall button is blocked for active plugins
3. Click the Uninstall button (trash icon, red/danger style) next to the plugin
4. Confirm in the confirmation dialog that appears
5. The server will:
   • Run the plugin's uninstall() hook (if defined), then deactivate() hook
   • Remove all plugin permissions
   • Clear asset and translation caches
   • Remove the plugin's entry from plugins.enabled
   • Recursively delete the plugin directory from plugins/

Restrictions

• Core plugins (marked cantDisable = "1" in plugin.json) cannot be uninstalled — the button is hidden
• Active plugins cannot be uninstalled — deactivate the plugin first

Implementing the Uninstall Hook

Plugins can run cleanup logic when uninstalled:

public function uninstall(): void
{
    // Clean up plugin-specific data in stockage/, custom tables, etc.
    // Called before the plugin directory is deleted
}

public function deactivate(): void
{
    // Called when plugin is deactivated (also called during uninstall)
}

Updating Plugins

1. Backup - Backup your forum first
2. Download - Get new plugin version
3. Replace Files - Replace plugin files
4. Clear Cache - Clear forum cache
5. Test - Test plugin functionality

Plugin Dependencies

Some plugins require other plugins:

{
  "requires": {
    "flatboard": ">=5.0.0",
    "plugins": {
      "another-plugin": ">=1.0.0"
    }
  }
}

Troubleshooting

Plugin Not Loading

Check:

1. Plugin structure is correct
2. plugin.json is valid
3. Plugin class exists and is correct
4. Check error logs

Plugin Conflicts

Solution:

1. Deactivate conflicting plugins
2. Check hook priorities
3. Review plugin code
4. Contact plugin developers

Plugin Errors

Solution:

1. Check error logs
2. Enable debug mode (temporarily)
3. Review plugin code
4. Check Flatboard 5 compatibility

Resources

• Developer Guide - Advanced development
• API Documentation - API integration
• Theme Guide - Theme integration
• Troubleshooting - Common issues

Last updated: March 10, 2026