PHPackages                             bitbee/php-modular-dashboard - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. bitbee/php-modular-dashboard

ActiveProject[Framework](/categories/framework)

bitbee/php-modular-dashboard
============================

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

00PHP

Since Jan 24Pushed 3mo agoCompare

[ Source](https://github.com/yoodoohai/php-modular-dashboard)[ Packagist](https://packagist.org/packages/bitbee/php-modular-dashboard)[ RSS](/packages/bitbee-php-modular-dashboard/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Dashboard Session
=================

[](#dashboard-session)

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?
----------------

[](#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
--------

[](#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
------------

[](#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
-----------------

[](#available-modules)

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

- Browse available modules:
- Or check `modules/*/README.md` in your installation

Quick start (local)
-------------------

[](#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
--------------------

[](#development-workflow)

### Developing from inside a running installation

[](#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
--------------------

[](#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
-------------

[](#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
-------------------

[](#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)
---------------------------

[](#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)
---------------------------------------

[](#production-deployment-nginx--php-fpm)

### Web root MUST be `public/`

[](#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 `/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”)

[](#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)
----------------------------------

[](#security-notes-important-for-oss)

### Module upload is dangerous (RCE)

[](#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

[](#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
------------------

[](#installing-modules)

### Option 1: Git submodules (recommended for development)

[](#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- modules/
# 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

[](#option-2-composer--packagist)

Modules are also available as Composer packages:

```
composer require bitbee/php-dashboard-module-
# 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- modules/`
- Or adjust your autoloader to find modules in `vendor/`

### Option 3: Manual copy/clone

[](#option-3-manual-copyclone)

Clone or copy module directories directly into `modules/`.

Developing with submodules
--------------------------

[](#developing-with-submodules)

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

1. **Edit module code** in `modules//`
2. **Commit changes** in the module repo: ```
    cd modules/
    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/
    git commit -m "Update  module"
    ```

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

Publishing structure (core vs modules)
--------------------------------------

[](#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:

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.

###  Health Score

18

—

LowBetter than 8% of packages

Maintenance53

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/733ffa3785ee1cb0c3149521421c97bbd75781325de36e792e95722e70fd98d5?d=identicon)[yoodoohai](/maintainers/yoodoohai)

---

Top Contributors

[![yoodoohai](https://avatars.githubusercontent.com/u/171418768?v=4)](https://github.com/yoodoohai "yoodoohai (1 commits)")

### Embed Badge

![Health badge](/badges/bitbee-php-modular-dashboard/health.svg)

```
[![Health](https://phpackages.com/badges/bitbee-php-modular-dashboard/health.svg)](https://phpackages.com/packages/bitbee-php-modular-dashboard)
```

###  Alternatives

[laravel/passport

Laravel Passport provides OAuth2 server support to Laravel.

3.4k85.0M532](/packages/laravel-passport)[nolimits4web/swiper

Most modern mobile touch slider and framework with hardware accelerated transitions

41.8k177.2k1](/packages/nolimits4web-swiper)[laravel/dusk

Laravel Dusk provides simple end-to-end testing and browser automation.

1.9k36.7M259](/packages/laravel-dusk)[laravel/prompts

Add beautiful and user-friendly forms to your command-line applications.

712181.8M596](/packages/laravel-prompts)[cakephp/chronos

A simple API extension for DateTime.

1.4k47.7M121](/packages/cakephp-chronos)[laravel/pail

Easily delve into your Laravel application's log files directly from the command line.

91545.3M590](/packages/laravel-pail)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)