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
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 DELETErules 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.
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.
| 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.
-
Download or clone the repository into your web root. Prefer keeping
app/outside the document root when your host supports it. -
Enable
.htaccess(for Apache,AllowOverride All). -
Make
app/writable by the web server only during installation. -
Open the site in your browser and complete the six installer steps.
-
After installation, remove write access again. The installer writes
app/config.phpandapp/install/lock/app/install/step:chmod -R a-w app/install chmod a-w app/config.php
-
Keep
app/out of public reach. The bundled root.htaccessblocks/app/...; use the Nginx rules below or moveapp/outside the document root if your server ignores it. -
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. -
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.
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.phpThe database is not dropped, so existing tables and seeded rows may conflict with a fresh install. Only reinstall on a development copy.
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.
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.
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 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.
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.
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
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 --forceBackups 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.
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.
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.
- Pick an item from TODO.md or open an issue first.
- Keep the project dependency-free: plain PHP, MySQLi, and vanilla JavaScript. Do not add Composer or npm packages.
- Follow the existing controller/page/widget/template structure.
- Test on a fresh installation and describe the manual verification steps in your pull request. There is no automated test suite yet.
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.
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.
BitBoard is licensed under the GNU General Public License v3.0.


