Download the PHP package rafalmasiarek/dashboard-kit without Composer

dashboard-kit

Slim 4 dashboard framework. Provides module auto-discovery, dynamic navbar, session-based auth (via AuthKit), CSRF protection, Twig templating, structured logging, mail, and a plugin extension system.

Requirements

• PHP 8.2+
• MySQL 8 or SQLite
• Composer

Installation

Quick start

Module structure

Each module is a directory containing module.php:

Modules appear in the navbar automatically. Admin modules (under admin_modules_path) appear in the /admin panel.

Database schema

Declare tables directly in module.php under the schema key. On every boot the framework compares a hash of each table's definition against the stored hash — unchanged tables are skipped entirely. Changed or new tables are created (CREATE TABLE IF NOT EXISTS) and any new columns are added (ALTER TABLE ADD COLUMN). Columns are never dropped.

Every managed table automatically gets id (UUID CHAR(36)) and created_at (DATETIME, DEFAULT CURRENT_TIMESTAMP). Supported column types: string, text, int/integer, bigint, tinyint, bool/boolean, decimal, float, datetime, date, json, uuid.

Tables outside modules

Tables that do not belong to any module can be declared at the top level of the config under schema:

Table prefix

Add table_prefix to the config to namespace all managed tables. System tables (_schema_state, _table_version, _query_cache) are never prefixed.

In handlers that build raw SQL, use CachingPdo::table() to apply the prefix consistently:

The prefix is also available as db.table_prefix in the container.

Seed data

Declare default rows under the seed key (top-level config or per-module). Each seed table is paired with a match column for the existence check — rows are inserted only when no matching record exists, making seeds idempotent on every boot.

created_at is never injected — the database fills it in via DEFAULT CURRENT_TIMESTAMP.

Query cache

All SELECT queries issued through PDO::class from the container are transparently cached — no code changes required in handlers. The cache is version-keyed: any write to a table automatically makes all cached SELECT results for that table unreachable without explicit invalidation.

Cache behaviour by statement type:

Only fetchAll() results are cached. fetch() and fetchColumn() always hit the database.

Default TTL is 300 seconds. The cache is stored in the _query_cache table and never goes stale: a write to table T makes all cached SELECT keys that referenced T unreachable — they can never be served after the write.

Plugin extension points

Plugins can extend the UI without modifying core templates:

Settings sections

Register a section card on the /settings page:

User action buttons

Register a button in Admin → Users per-user row:

Form slots

Inject HTML into the login or register forms without modifying core templates. Resolve FormSlotRegistry from the container and call register() before run().

Built-in slots:

In Twig, slots are rendered via {{ form_slot('login', 'form_fields') }} — already present in the core templates, no template changes needed.

See docs/form-slots.md for the full reference including the PHP-DI callable pitfall.

Auth failure hooks

Emitted after failed credential checks, useful for rate limiting and abuse detection:

Error handling

SafeErrorHandler handles all Slim errors with content negotiation:

• JSON clients (Accept: application/json, AJAX, CLI) receive:

• Browsers receive a Twig error template (errors/{code}.twig, errors/5xx.twig, errors/error.twig)
• Secrets (tokens, passwords, API keys) are redacted from all error output

Logging

Named Monolog channels in key=value format, registered as logger.{name} in the container:

Audit events use dot-notation names: dashboard.login, dashboard.register, dashboard.role_changed, etc.

Redirect after login

When AuthMiddleware blocks an unauthenticated request it redirects to /login?from=<encoded-path>. After successful login the controller redirects back to that path instead of the default /.

Only same-origin paths are accepted (from must start with / and not with //) to prevent open redirect attacks.

Logged-in users visiting /login or /register are redirected immediately to / — these routes are guest-only.

Built-in routes

Home page

GET / renders the built-in home.twig. The template checks auth.isLoggedIn() and shows different content for guests and authenticated users.

To customise, place home.twig in your application's templates/ directory — it takes precedence over the built-in:

Available Twig globals on this page: auth, app_name, modules, registration_enabled, flash.

Templating and layout customisation

layout.twig is split into named blocks that can be overridden independently:

To override a single block without replacing the whole layout, extend @dashboard-kit/layout.twig (the namespace avoids infinite recursion when your file is also called layout.twig):

See docs/templating.md for the full reference.

License

MIT License — see LICENSE.