Developer Guide

Developer Guide

Architecture Overview

MVC Pattern

Flatboard 5 follows the Model-View-Controller (MVC) pattern:

app/
├── Controllers/    # Handle requests and logic
├── Models/         # Data models and business logic
├── Views/          # Template files
├── Core/           # Core framework classes
├── Helpers/        # Helper functions
├── Middleware/     # Request middleware
└── Services/      # Service classes

Directory Structure

Flatboard5/
├── app/                    # Application code
│   ├── Controllers/       # Controllers
│   ├── Models/            # Models
│   ├── Views/             # Views
│   ├── Core/              # Core classes
│   ├── Helpers/           # Helpers
│   ├── Middleware/        # Middleware
│   └── Services/          # Services
├── public/                # Public files
│   └── index.php         # Entry point
├── stockage/             # Data storage
├── uploads/              # User uploads
├── plugins/              # Plugins
├── themes/               # Themes
└── vendor/               # Dependencies

Core Components

Autoloader

PSR-4 autoloading:

use App\Core\Autoloader;

Autoloader::register(BASE_PATH);

Router

Route registration (the Router requires Request and Response instances):

use App\Core\Router;
use App\Core\Request;
use App\Core\Response;

$router = new Router($request, $response);
$router->get('/path', 'Controller@method');
$router->post('/path', 'Controller@method');

// Named routes
$router->get('/forum', 'ForumController@index')->name('forum.index');
$url = $router->url('forum.index');                      // Generate URL
$url = $router->url('discussion.show', ['id' => 42]);    // With params

// Route groups (shared prefix + middleware)
$router->group(['prefix' => '/admin', 'middleware' => ['App\Middleware\AuthMiddleware']], function($router) {
    $router->get('/dashboard', 'Admin\DashboardController@index');
});

// Parameter constraints
$router->get('/user/{id}', 'UserController@show')->where('id', '[0-9]+');

// RESTful resource routes (generates GET list, GET show, POST, PUT, DELETE)
$router->resource('/posts', 'PostController');

// Regex-based routes
$router->regex('GET', '#^/custom/(.+)$#', function($matches) { /* ... */ });

// Global before/after hooks (for monitoring, logging)
$router->beforeEach(function($request) { /* ... */ });
$router->afterEach(function($request, $response) { /* ... */ });

// Route cache for production (cached to stockage/cache/routes.php)
$router->enableCache();

Controller

Base controller:

namespace App\Controllers;

use App\Core\Controller;

class MyController extends Controller
{
    public function index()
    {
        return $this->view('template', ['data' => $data]);
    }
}

Model

Base model:

namespace App\Models;

class MyModel
{
    public static function find($id)
    {
        // Load from storage
    }

    public static function create($data)
    {
        // Create new record
    }
}

Coding Standards

PSR Standards

Follow PSR standards:

• PSR-1 - Basic coding standard
• PSR-4 - Autoloading standard
• PSR-12 - Extended coding style

Code Style

<?php
namespace App\Controllers;

use App\Core\Controller;
use App\Models\User;

class UserController extends Controller
{
    public function index()
    {
        $users = User::all();
        return $this->view('users.index', ['users' => $users]);
    }

    public function show($id)
    {
        $user = User::find($id);
        if (!$user) {
            return $this->notFound();
        }
        return $this->view('users.show', ['user' => $user]);
    }
}

Naming Conventions

• Classes: PascalCase - UserController
• Methods: camelCase - getUserData()
• Variables: camelCase - $userData
• Constants: UPPER_SNAKE_CASE - MAX_FILE_SIZE
• Files: Match class name - UserController.php

Plugin Development

Plugin Structure

plugins/my-plugin/
├── plugin.json
├── MyPluginPlugin.php
├── assets/
├── views/
└── README.md

Plugin Class

<?php
namespace App\Plugins\MyPlugin;

use App\Core\Plugin;

class MyPluginPlugin
{
    public function boot()
    {
        // Register plugin routes
        Plugin::hook('router.plugins.register', [$this, 'registerRoutes']);
        // Add CSS to page header
        Plugin::hook('view.header.styles', [$this, 'addStyles']);
    }

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

    public function addStyles(&$styles)
    {
        $styles[] = \App\Helpers\PluginAssetHelper::loadCss('my-plugin', 'css/style.css');
    }
}

Available Hooks

Below are the most commonly used hooks for plugin development:

Theme Development

Theme Structure

themes/my-theme/
├── theme.json
├── assets/
│   ├── css/
│   ├── js/
│   └── img/
└── views/

Template Overrides

Override default templates:

themes/my-theme/views/
├── layouts/
│   └── main.php
└── discussions/
    └── list.php

CSS Variables

Use CSS variables for customization:

:root {
  --primary-color: #007bff;
  --secondary-color: #6c757d;
  --background-color: #ffffff;
  --text-color: #212529;
}

Update Endpoint for Plugins and Themes

Since 5.3.7, Flatboard can check for updates on any plugin or theme that declares an update_url in its plugin.json or theme.json. When an update is available, it appears in Admin Panel > Tools > Updates alongside the core update, with the installed version, the latest available version, and a link to the changelog.

Declaring an update_url

Add the update_url field at the root of your plugin.json (or theme.json):

{
    "name": "My Plugin",
    "id": "my-plugin",
    "version": "1.2.0",
    "update_url": "https://example.com/api/my-plugin/version",
    ...
}

The value can be:

• An absolute URL — used directly (https://example.com/api/...)
• A relative path — prefixed with the forum's update_check_url config value (e.g. api/plugins/my-plugin → https://versions.flatboard.org/api/plugins/my-plugin)

If the URL is relative and no update_check_url is configured, the check is silently skipped.

Required API response format

Your endpoint must return a JSON object with at least a version field:

{
    "version": "1.3.0",
    "changelog_url": "https://example.com/my-plugin/changelog"
}

The check is performed via a simple GET request (cURL). Results are cached for 1 hour — no need to worry about hammering the endpoint.

Minimal server-side example (PHP)

<?php
header('Content-Type: application/json');
echo json_encode([
    'version'       => '1.3.0',
    'changelog_url' => 'https://example.com/my-plugin/releases/1.3.0',
]);

Plugin Settings API

Plugin settings live in the "plugin" section of plugin.json. Always use Plugin::getData/setData/saveData — never Config::get/set — for plugin-specific values:

use App\Core\Plugin;

// Read a setting (third arg is default value)
$apiKey = Plugin::getData('my-plugin', 'api_key', '');

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

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

// Persist all settings to plugin.json
Plugin::saveData('my-plugin', ['api_key' => 'abc123', 'enabled' => true]);

// Get plugin stats (for monitoring)
$stats = Plugin::getStats();
// Returns: ['total' => int, 'active' => int, 'inactive' => int, 'hooks' => int]

Presence Service

App\Services\PresenceService provides a unified API for querying who is currently on the forum (all methods are static):

use App\Services\PresenceService;

// All presence data (anonymous visitors + bots + logged-in users)
$all = PresenceService::getAllPresence(minutes: 15, includeBots: true);
// Returns: ['visitors' => [...], 'bots' => [...], 'users' => [...], 'all' => [...], 'stats' => [...]]

// Presence on a specific page
$page = PresenceService::getPresenceByPage('/d/123', minutes: 15);

// Aggregate stats only
$stats = PresenceService::getPresenceStats(minutes: 15);
// Returns: ['total' => int, 'anonymous' => int, 'authenticated' => int, 'bots' => int]

// Filter helpers (work on any presence array)
$filtered = PresenceService::filterByPageType($all['all'], 'discussion');
$filtered = PresenceService::filterByCategory($all['all'], 'general');
$filtered = PresenceService::filterByUserGroup($all['users'], 'moderator');

// Sorting
$sorted = PresenceService::sortPresence($all['all'], sortBy: 'last_activity', order: 'desc');

VisitorTrackingMiddleware runs automatically on every non-AJAX HTML request. It skips: authenticated users, paths under /api/, /presence/update, /favicon.ico, /robots.txt, static file extensions. It fires visitor.before_track before writing each record.

Translation System

Global helper

// Both are equivalent
$text = Translator::trans('key', ['var' => 'value'], 'domain');
$text = __('key', ['var' => 'value'], 'domain');

Advanced methods

// Get current language code
$lang = Translator::getLanguage();   // e.g., 'fr', 'en'

// Change language for the current request
Translator::setLanguage('en');

// Reload all translations from disk
Translator::reload();

// Reload only theme translation overrides
Translator::reloadThemeTranslations();

// Get all keys for a domain (useful for debugging)
$all = Translator::getAll('main');

// Register plugin translations programmatically
Translator::addPluginTranslations('my-plugin', ['key' => 'value']);

Storage Development

Two storage APIs serve different purposes. Choose the right one for your use case.

StorageFactory — Core Flatboard Data

Use StorageFactory::create() to read or write core Flatboard entities (users, discussions, posts, categories…). It returns the active StorageInterface implementation — JsonStorage on Community, SqliteStorage on Pro — so the same plugin code works on both editions without any change.

use App\Storage\StorageFactory;

$storage = StorageFactory::create();

// Examples of StorageInterface methods
$user        = $storage->getUserById($userId);
$discussions = $storage->getDiscussionsByCategory($categoryId);
$post        = $storage->getPostById($postId);

AtomicFileHelper — Plugin Custom Data

Use AtomicFileHelper when your plugin needs to store its own data files (not Flatboard core entities). It provides atomic read/write operations backed by file locking — never use file_get_contents / file_put_contents directly.

Plugin data is typically stored inside the plugin's own directory, under a data/ subfolder. Use Plugin::getPath() to resolve the path safely regardless of the plugin's installation location:

use App\Core\AtomicFileHelper;
use App\Core\Plugin;

$dataDir  = Plugin::getPath('my-plugin') . '/data';
$dataFile = $dataDir . '/records.json';

// Read plugin data (returns array or null if file absent)
$data = AtomicFileHelper::readAtomic($dataFile);

// Write plugin data (returns bool)
AtomicFileHelper::writeAtomic($dataFile, $data);

// Batch read multiple files in one pass
$results = AtomicFileHelper::readAtomicBatch([
    $dataDir . '/records.json',
    $dataDir . '/settings.json',
]);

Security Best Practices

Input Validation

Always validate input:

use App\Core\Validator;

// Pass request data to the constructor
$validator = new Validator($this->request->all());
$validator->required('email')->email('email');
$validator->required('username')->min('username', 3)->max('username', 30);

if (!$validator->isValid()) {
    $errors = $validator->getErrors(); // ['field' => 'error message', ...]
    Session::flash('errors', $errors);
    $this->redirect(\App\Helpers\UrlHelper::to('/register'));
    return;
}

Output Sanitization

Sanitize all output:

use App\Core\Sanitizer;

// Strip dangerous HTML, keep safe tags (for rich content)
$clean = Sanitizer::sanitizeHtml($userInput);

// Strip all HTML tags (for plain text fields)
$clean = Sanitizer::sanitizeText($userInput);

// Escape for HTML output
echo Sanitizer::escape($value);

// Escape for use in an HTML attribute
echo Sanitizer::sanitizeForAttribute($value);

CSRF Protection

Use CSRF tokens:

use App\Core\Csrf;

// Generate a token for the current session
$token = Csrf::token();

// Render a hidden input field (shortcut for use in views)
echo Csrf::field(); // <input type="hidden" name="csrf_token" value="...">

// Validate the token submitted with a form or API request
if (!Csrf::validate($token)) {
    return $this->error('Invalid CSRF token');
}

Testing

Unit Tests

Write unit tests:

use PHPUnit\Framework\TestCase;

class UserTest extends TestCase
{
    public function testUserCreation()
    {
        $user = User::create([
            'username' => 'testuser',
            'email' => 'test@example.com'
        ]);
        $this->assertNotNull($user);
    }
}

Integration Tests

Test integrations:

public function testApiEndpoint()
{
    $response = $this->get('/api/discussions');
    $this->assertEquals(200, $response->getStatusCode());
}

Performance

Caching

Use caching:

use App\Core\Cache;

// Set cache
Cache::set('key', $data, 3600);

// Get cache
$data = Cache::get('key');

// Clear cache
Cache::clear('key');

Database Optimization

Optimize queries:

// Use indexes
// Limit results
// Avoid N+1 queries
// Use transactions

Contributing

Code Contribution

1. Fork Repository - Fork on GitHub
2. Create Branch - Create feature branch
3. Write Code - Follow coding standards
4. Test - Write and run tests
5. Submit PR - Submit pull request

Documentation

• Code Comments - Add helpful comments
• PHPDoc - Document functions and classes
• README - Update README if needed
• Changelog - Update changelog

Version Compatibility

Resources

• Plugin Guide - Plugin development
• Theme Guide - Theme development
• API Documentation - API development
• GitHub Repository - Source code

Last updated: March 28, 2026