Skip to content
nc-gpPublic

About

Effortless, enjoyable, and efficient PHP-based forum system.

Topics

Resources

Stars

4 stars

Watchers

3 watching

Forks

Repository files navigation

Bitboard logo
BitBoard

License: GPL 3.0 PHP 8.0+ MySQL / MariaDB No dependencies Early development

A lightweight, self-hosted forum engine in plain PHP.

BitBoard is in early development. It is not production-ready yet. Expect unfinished features, breaking changes, and missing hardening. See TODO.md for the backlog.

Features • Screenshots • Requirements • Installation • Project Structure • Roadmap • Contributing • License

Screenshots

BitBoard forum home page BitBoard thread view

Features

BitBoard is dependency-free: plain PHP, MySQLi, and vanilla JavaScript. There is no Composer, npm, or build step. Tabler Icons is the only external front-end asset and is pinned via CDN.

  • Responsive six-step web installer with requirement checks, validation, and a finish checklist.
  • Categories → forums → subforums, with locked-forum permissions.
  • Threads and replies with a Markdown editor, live preview, local drafts, CSRF protection, edit history, and permanent deletion.
  • Inline fast reply with AJAX append and a normal POST fallback.
  • Attachments on threads, replies, edits, and fast replies: private storage under app/, extension/MIME/size validation, admin-configurable limits and formats, controlled download links, and cleanup when posts or threads are deleted.
  • Reactions, quotes, multi-quote, @mentions, and a header notification bell.
  • Thread subscriptions and forum/subforum watch notifications.
  • Per-user read tracking, pagination-preserving last-post links, and “who is viewing”.
  • Custom thread prefixes, pin/lock, and move-between-forums moderation.
  • Thread and reply reporting with a staff queue (open, resolved, dismissed).
  • Search with forum, prefix, author, and date filters.
  • Member directory, online list, and public profiles with avatar, bio, and signature.
  • Account settings for email, password, bio, signature, avatar uploads, language, timezone, and notification preferences, with admin limits.
  • Email activation and password reset with expiring, single-use tokens, automatic activation resend on unverified login, email-change re-verification, and log-file or PHP mail() delivery.
  • Account deletion with password confirmation; authored threads/posts, edits, attachments, and reports are reassigned to a hidden “Deleted user” account while private account data and reactions are removed.
  • Registration hardening: an open/closed switch with a custom closed message, required configurable terms, per-IP throttling, a hidden honeypot and minimum submit delay, plus configurable email-domain allow/block lists seeded with common providers.
  • Admin panel: dashboard charts, tabbed settings, categories, forums, prefixes, ranks with a permission matrix, user management, ban/suspension records with reasons and expiry, and a filterable audit log with CSV export and pruning.
  • Numbered database migrations with automatic, locked upgrades for existing installs.
  • Foreign keys for accounts, forums, threads, posts, reactions, subscriptions, reports, bans, and notifications, with safe ON DELETE rules and orphan cleanup through migrations.
  • Theme system with the bundled default theme, a light/dark/auto switcher, and an admin theme manager for installing, previewing, activating, and deleting themes.
  • SEO slugs and canonical URLs, OpenGraph/Twitter metadata, /sitemap.xml, and /feed.xml.
  • Responsive layouts for desktop, tablet, and phone.

Thread merges/splits and two-factor authentication are not implemented yet. See TODO.md for details.

Content format

Posts use a safe Markdown subset: headings, bold, italic, strikethrough, inline and fenced code, quotes, lists, links, and images. Raw HTML is escaped, and the rendered result is sanitized before it is stored. Drafts stay in the browser’s local storage.

Requirements

Component Version / notes
PHP 8.0+ (8.1+ recommended), with the mysqli extension
Database MySQL 5.7+ or MariaDB 10.2+
Web server Apache 2.4+ with mod_rewrite, or Nginx with an equivalent rewrite rule
Filesystem Temporary write access to app/ during installation; persistent write access to app/storage/attachments/ and app/storage/mail/

BitBoard runs on Windows and Linux. Root and subdirectory installs are both supported.

Installation

  1. Download or clone the repository into your web root. Prefer keeping app/ outside the document root when your host supports it.

  2. Enable .htaccess (for Apache, AllowOverride All).

  3. Make app/ writable by the web server only during installation.

  4. Open the site in your browser and complete the six installer steps.

  5. After installation, remove write access again. The installer writes app/config.php and app/install/lock / app/install/step:

    chmod -R a-w app/install
    chmod a-w app/config.php
  6. Keep app/ out of public reach. The bundled root .htaccess blocks /app/...; use the Nginx rules below or move app/ outside the document root if your server ignores it.

  7. Keep app/storage/attachments/ writable by the web server. Attachment files are served through /attachment/{id} after forum permission checks and are never linked directly.

  8. Keep app/storage/mail/ writable if you use the log mail transport during development.

The admin panel route is chosen in installer step 5 (default /admin). Pick a non-obvious path before exposing the forum publicly.

The installer creates the first administrator with a verified email address, so that account can sign in immediately. Later registrations still require email activation.

Installing or deleting themes from the admin panel requires write access to themes/. Leave it writable if you manage themes from the browser; otherwise remove write access after copying the theme folder in manually.

app/install/lock and app/install/step are sensitive control files. Do not expose, edit, or delete them except when intentionally reinstalling on a development copy.

Reinstalling

Restore write access, delete the installer state and config, then reload the site:

chmod -R u+w app/install
chmod u+w app/config.php
rm app/install/lock app/install/step app/config.php

The database is not dropped, so existing tables and seeded rows may conflict with a fresh install. Only reinstall on a development copy.

Upgrading

Database changes ship as numbered migrations in app/migrations/. After replacing the application files, the next request applies any pending migrations automatically and records them in bit_migrations; no manual SQL or reinstall is needed.

Back up the database before upgrading. If a migration fails, the request stops before rendering a page and the error is written to the PHP error log, so the forum does not silently run against a partially upgraded schema. App\Classes\Migrator::Status($db) lists applied and pending versions for diagnostics.

The database user needs CREATE/ALTER privileges while an upgrade runs; you can revoke them again afterwards if your host allows it.

To add a migration, create the next sequential NNN_description.php file returning version, name, and an up callable. Keep migrations idempotent so they are safe on databases that already received an earlier in-place upgrade.

Manual configuration

The installer generates app/config.php. To create it by hand:

<?php

$config['host'] = 'localhost';
$config['user'] = 'bitboard';
$config['pass'] = 'change-me';
$config['name'] = 'bitboard';

// Optional: append the per-page query count as an HTML comment.
$config['debug'] = false;

app/config.php is git-ignored. Never commit real credentials.

Nginx

Apache is the supported server. For Nginx, mirror the .htaccess behavior:

location / {
    try_files $uri $uri/ @bitboard;
}

location @bitboard {
    # Apache passes the action without a leading slash; match that behavior.
    rewrite ^/(.*)$ /index.php?action=$1 last;
}

location ^~ /api/ {
    # ApiMain expects the "api/" prefix in data, e.g. data=api/settings.
    rewrite ^/api/(.*)$ /api.php?data=api/$1 last;
}

location ^~ /app/ {
    deny all;
}

Themes

Themes live in themes/<slug>/ and contain:

theme.json                Name, description, version, author
templates/                Page, widget, and layout HTML
styles/                   CSS
images/                   Theme images (logo.webp for the default header/footer)
screenshot.webp           Admin preview image (optional)

See docs/THEMES.md for theme structure and the full template variable reference.

Templates that a theme does not override fall back to the default theme. Use {theme_url} in templates and stylesheets for theme-relative assets.

The admin panel uses its own reserved theme at themes/_admin/. It has a separate shell, sidebar, top bar, templates, and styles, and is never listed or activatable as a front-end theme. Admin templates and styles live only under themes/_admin/; front-end themes no longer ship admin templates.

Only the bundled themes/default and themes/_admin directories are tracked by Git. Installed and newly created themes are ignored so each deployment can keep its own theme library out of version control.

Admins with settings access can open Admin → Themes to preview, activate, install, and delete themes, or create a new theme by copying the default theme. Installation accepts a ZIP containing theme.json and templates/, either at the root or inside one top-level folder. Only web asset files are accepted; PHP and server configuration files are rejected. The default and active themes cannot be deleted.

Mods

Trusted mods live under app/mods/<slug>/ and are managed from Admin → Mods. New mods start disabled, and disabled mods are never loaded. Administrators can install a ZIP, create a starter skeleton, enable or disable a mod, and delete disabled mods.

Mods can register action hooks, expose named theme variables such as {mod:chat.widget}, serve public routes and assets under /mod/<slug>/, declare admin-editable settings, run versioned schema migrations, and render their own templates under app/mods/<slug>/templates/.

See docs/MODS.md for the manifest format, lifecycle, hook API, routes, assets, settings, migrations, template rendering, admin actions, and security model. Mods execute trusted PHP with full application access; only enable code you have reviewed.

Project Structure

index.php                 Front controller (forum pages)
api.php                   JSON API front controller
auto_loader.php           Dependency-free PSR-4-style class loader
app/
  BitBoard.php            Bootstrap: install check, config, DB, routing
  Classes/                Database, Template, permissions, sessions, utilities
  forum/                  Controllers, pages, structs, and widgets
  install/                Web installer and access guard
  interfaces/             Page and installer step contracts
  migrations/             Numbered database upgrades, applied automatically
Api/                      API bootstrap and POST endpoints
assets/                   Global CSS/JS and installer assets
app/storage/              Private attachments, mail logs, backups, and application logs
themes/default/           Templates, styles, and images for the default theme
themes/_admin/            Reserved admin-panel shell, templates, and styles
tools/bitboard.php        CLI health check, backup, and restore commands
docs/                     Mod, theme, and template documentation

Operations

php tools/bitboard.php health
php tools/bitboard.php backup
php tools/bitboard.php backup /path/to/backup.sql
php tools/bitboard.php restore /path/to/backup.sql --force

Backups default to app/storage/backups/. Restoring into a non-empty database requires --force; take a fresh backup first. Application errors and warnings are written as JSON lines to app/storage/logs/bitboard.log and rotate at 5 MB. If bootstrap fails before the normal error page can load, a standalone 500 page is rendered.

Localization

Interface strings live in app/locales/en.php and app/locales/pl.php. English is the fallback. The runtime loads the signed-in member's locale, then the guest bb_locale cookie, then the site default from Admin → Settings, then English.

Templates use {t:key} placeholders, {locale} and {direction} on the document element. Pages and widgets use Translator::Get() or Translator::Choice() for dynamic strings and plurals. Emails use the recipient's locale when set, otherwise the site default.

Members choose a language in account settings; guests use the footer language switcher at locale/<code>. Adding a locale means adding a file to app/locales/ and registering its label and direction in app/Classes/Translator.php.

English and Polish currently cover the public forum, authentication, account settings, search, posting/editing, reports, notifications, emails, relative and timezone-aware dates, JavaScript messages, and the admin shell, dashboard, settings, categories, forums, prefixes, users, bans, themes, and audit controls. Remaining untranslated strings are historical audit-log entries written before localization was added. Custom/test themes are intentionally left to theme authors.

JavaScript reads a generated window.BB_I18N object emitted with the footer scripts. Add keys to Translator::Js() when a script needs a new translated string.

Roadmap

The full backlog lives in TODO.md. Next up:

  • Thread merge/split and optional two-factor authentication.
  • An event/hook system.
  • Remaining translation coverage, RTL support, and an expanded test suite.

Contributing

  1. Pick an item from TODO.md or open an issue first.
  2. Keep the project dependency-free: plain PHP, MySQLi, and vanilla JavaScript. Do not add Composer or npm packages.
  3. Follow the existing controller/page/widget/template structure.
  4. Test on a fresh installation and describe the manual verification steps in your pull request. There is no automated test suite yet.

Security

BitBoard is not production-ready. Do not expose it to untrusted users until the P0 items in TODO.md are resolved.

Report security issues privately through GitHub Security Advisories instead of opening a public issue with exploit details.

Credits

Contributors

Built with PHP, MySQLi, and vanilla JavaScript. Tabler Icons 3.49.0 is the only external front-end asset; tooltips, notifications, and the editor helpers are local.

License

BitBoard is licensed under the GNU General Public License v3.0.

About

Effortless, enjoyable, and efficient PHP-based forum system.

Topics

Resources

Stars

4 stars

Watchers

3 watching

Forks

Releases

Packages

Contributors

Languages