README

A lightweight PHP session dashboard that helps you wrap existing PHP classes as modules with a UI, routing, authentication, and fine-grained module -> method permissions — without adopting a full framework.

Who is this for?

• I have a few PHP scripts/classes and want a secure UI — Turn your existing PHP classes into authenticated web pages with minimal boilerplate.
• I want a LAN dashboard for home automation / internal tools — Build modular control panels with permission-based access.
• I want modular pages controlled by permissions — Register arbitrary PHP classes as modules and expose selected methods to specific users.

Modules are registered via config/modules.registry.json and access is controlled exclusively by module+method permissions stored per user in config/users.conf.php.

Features

• Authentication: login, logout, password reset, rate limiting, CSRF protection
• Permission model: explicit module -> method[] permissions (no implicit “admin bypass”)
• Module system: register arbitrary PHP classes/modules and expose selected methods
• Guest mode: __guest__ user can be granted specific read-only permissions
• Translations: English + German

Requirements

• PHP 8.1+
• Write permissions for logs/, data/, and config/

Module-specific requirements live in each module’s README (see modules/*/README.md).

Available modules

Modules are published separately. See each module's repository for documentation:

• Browse available modules: https://github.com/bitbee?q=php-dashboard-module-
• Or check modules/*/README.md in your installation

Quick start (local)

cp config/config.local.php.example config/config.local.php
cp config/users.conf.php.example config/users.conf.php
composer install --no-interaction
chmod +x setup-permissions.sh
./setup-permissions.sh
php -S localhost:8080 -t public

Open http://localhost:8080.

Development workflow

Developing from inside a running installation

Yes, you can develop directly in your running installation! This is the recommended workflow:

• Code changes (PHP files, templates, etc.) → committed to git
• Secrets/data (users.conf.php, config.local.php, *.sqlite, etc.) → gitignored, stay local
• You develop locally with real data, commit code, and sync code to production
• Production also has its own secrets/data (also gitignored)

The .gitignore is configured to exclude all secrets/data files, so you can safely develop with real user data while keeping code in version control.

How permissions work

Each user has explicit permissions:

'permissions' => [
  'MyModule' => ['index', 'view'],
  'AdminUsers' => ['index', 'create', 'edit', 'delete'],
]

• Navigation shows only modules/methods granted to the current user.
• Access enforcement is centralized: requests are routed through public/index.php → src/Http/Kernel.php → src/Routing/ModuleDispatcher.php, which blocks any unauthorized module/method call.

Default route

• If a user has default_module, the app tries to route there only if the user has permission.
• Otherwise, it routes to the first accessible module/method.
• If a user has no accessible routes, a generic 403 page is shown.

Registering modules

Modules are registered in config/modules.registry.json (or via the “Manage Modules” UI). The registry defines:\n\n- which module key maps to which PHP file/class\n- which methods are exposed/routable\n- which methods are hidden from navigation\n\nPermissions then decide what each user can execute.

Project layout (high level)

public/                entrypoint (thin front controller)
config/                local settings, users, module registry, translations
src/                   core runtime (auth, routing, rendering)
modules/               module implementations
templates/             shared UI templates

Production deployment (nginx + php-fpm)

Web root MUST be public/

For OSS/public deployments, only public/ is intended to be web-accessible. Everything else (especially config/ and log/state data) must be outside the web root.

If you deploy by pointing nginx root to <project>/public, the rest of the repository is not directly reachable by HTTP.

Example nginx server block (minimal):

server {
    listen 443 ssl;
    server_name example.local;

    root /var/www/dashboard_session/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
}

PHP-FPM session GC (avoid “logged out after ~1h”)

This app uses PHP sessions. If your server’s session garbage collection deletes session files quickly (e.g. session.gc_maxlifetime=3600), users will be asked to log in again once the session expires.

Recommended starting values for a small self-hosted dashboard:

• session.gc_maxlifetime: 21600 (6h) or 43200 (12h)
• session.gc_probability: 1
• session.gc_divisor: 100 (1% chance per request)

On nginx/php-fpm you can set these either in php.ini or per pool (recommended). Example (pool config, e.g. /etc/php/8.2/fpm/pool.d/www.conf):

php_admin_value[session.gc_maxlifetime] = 21600
php_admin_value[session.gc_probability] = 1
php_admin_value[session.gc_divisor] = 100

Also ensure session.save_path points to a directory where the php-fpm user can read/write, and that the OS cleanup policy does not delete sessions earlier than your gc_maxlifetime.

Security notes (important for OSS)

Module upload is dangerous (RCE)

The AdminModules UI can optionally upload PHP files. This is remote code execution by design and must be disabled in production unless you fully trust all admins and the environment.

• Default: disabled
• Enable explicitly in config/config.local.php:

return [
  'security' => [
    'module_uploads_enabled' => true,
  ],
];

Preferred installation method for modules: clone/copy them into modules/ (or use git submodules), then register them via config/modules.registry.json or the UI.

Security headers

The front controller (public/index.php) sets baseline security headers (CSP, frame-ancestors, nosniff, etc.). If you add third-party scripts, remote images, or iframe embeddings, you may need to adjust the CSP accordingly.

Installing modules

Option 1: Git submodules (recommended for development)

Modules are published as separate git repositories. Add them as submodules:

git submodule add https://github.com/bitbee/php-dashboard-module-<name> modules/<name>
# Example:
# git submodule add https://github.com/bitbee/php-dashboard-module-example modules/example

Then register them via config/modules.registry.json or the AdminModules UI.

Option 2: Composer / Packagist

Modules are also available as Composer packages:

composer require bitbee/php-dashboard-module-<name>
# Example:
# composer require bitbee/php-dashboard-module-example

After installation, modules are available in vendor/bitbee/php-dashboard-module-*/. You can either:

• Symlink them into modules/: ln -s ../../vendor/bitbee/php-dashboard-module-<name> modules/<name>
• Or adjust your autoloader to find modules in vendor/

Option 3: Manual copy/clone

Clone or copy module directories directly into modules/.

Developing with submodules

You can develop modules directly inside your running deployment when using git submodules:

1. Edit module code in modules/<name>/
2. Commit changes in the module repo:

   cd modules/<module-name>
   git add .
   git commit -m "Add feature X"
   git push

3. Update submodule pointer in the core repo:

   cd /path/to/core
   git add modules/<module-name>
   git commit -m "Update <module-name> module"

This workflow lets you iterate quickly while keeping module repos independent.

Publishing structure (core vs modules)

• Core repo: bitbee/php-modular-dashboard (this repository)
  • Contains public/, src/, templates/, and minimal built-in admin modules.
• Module repos (separate, published under bitbee/php-dashboard-module-*):
  • Each module is published as its own repository
  • Browse available modules: https://github.com/bitbee?q=php-dashboard-module-

Each module repo ships its own README.md and LICENSE, and the core repo keeps the module registry format stable so users can mix-and-match modules.