Search by

rafalmasiarek / dashboard-kit

rafalmasiarek

Slim 4 dashboard boilerplate with module auto-discovery, dynamic navbar, auth, CSRF protection and built-in API routing.

Package info

github.com/rafalmasiarek/php-dashboard-kit

pkg:composer/rafalmasiarek/dashboard-kit

Statistics

Installs: 192

Dependents: 10

Suggesters: 0

Stars: 0

Open Issues: 2


README

Packagist Version Total Downloads PHP License

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.

License

License: MIT

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files, to deal in the Software
without restriction.

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

Source: https://opensource.org/licenses/MIT

See LICENSE for full details.

Authors

Requirements

  • PHP 8.2+
  • MySQL 8 or SQLite
  • Composer

Installation

composer require rafalmasiarek/dashboard-kit

Quick start

use DI\ContainerBuilder;
use rafalmasiarek\DashboardKit\Dashboard;
use Slim\Factory\AppFactory;

$container = (new ContainerBuilder())->build();
AppFactory::setContainer($container);
$app = AppFactory::create();

Dashboard::create($app, $container, [
    'db' => [
        'driver'   => 'mysql',
        'host'     => 'localhost',
        'dbname'   => 'myapp',
        'user'     => 'root',
        'password' => 'secret',
    ],
    'modules_path'       => __DIR__ . '/modules',
    'admin_modules_path' => __DIR__ . '/admin_modules',
    'storage_path'       => __DIR__ . '/storage',
    'templates_path'     => __DIR__ . '/templates',
    'app' => [
        'env'  => 'production',
        'name' => 'My App',
    ],
]);

$app->run();

Module structure

Each module is a directory containing module.php:

// modules/notes/module.php
return [
    'title'  => 'Notes',
    'icon'   => 'πŸ“',
    'render' => function ($req, $res, $args, $twig, $db, $container) {
        return $twig->render($res, 'notes/index.twig', []);
    },
];

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.

// modules/notes/module.php
return [
    'title'  => 'Notes',
    'schema' => [
        'notes' => [
            'columns' => [
                'title'   => ['type' => 'string', 'null' => false],
                'body'    => ['type' => 'text'],
                'user_id' => ['type' => 'uuid', 'null' => false],
                'active'  => ['type' => 'tinyint', 'default' => 1],
            ],
            'indexes' => [
                ['columns' => ['user_id']],
            ],
        ],
    ],
    'render' => function ($req, $res, $args, $twig, $db, $container) { ... },
];

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:

Dashboard::create($app, $container, [
    // ...
    'schema' => [
        'shared_settings' => [
            'columns' => [
                'key'   => ['type' => 'string', 'null' => false, 'unique' => true],
                'value' => ['type' => 'text'],
            ],
        ],
    ],
]);

Table prefix

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

Dashboard::create($app, $container, [
    'table_prefix' => 'app_',
    // module table "notes" β†’ "app_notes"
]);

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

$stmt = $db->prepare("SELECT * FROM `" . $db->table('notes') . "` WHERE id = ?");

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.

'seed' => [
    'users' => [
        'match'   => 'email',        // column used for the existence check before inserting
        'with_id' => true,           // auto-generate UUID for id if absent (default)
        'rows'    => [
            [
                'email'         => 'admin@example.com',
                'role'          => 'admin',
                'active'        => 1,
                'password_hash' => password_hash('secret', PASSWORD_BCRYPT),
            ],
        ],
    ],
    'api_scopes' => [
        'match'   => 'name',
        'with_id' => false,          // table uses AUTO_INCREMENT β€” skip UUID injection
        'rows'    => [
            ['name' => 'notes:read',  'description' => 'Read notes'],
            ['name' => 'notes:write', 'description' => 'Manage notes'],
        ],
    ],
],

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:

Type Behaviour
SELECT Checks cache before executing; stores fetchAll() result on miss
INSERT / UPDATE / DELETE / REPLACE Executes normally; bumps version counter for affected tables
System tables (_query_cache, _table_version, _schema_state) Always bypass cache

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:

$container->get(SettingsSectionRegistry::class)->register('my-plugin', [
    'title' => 'My Plugin',
    'path'  => '/settings/my-plugin',
    'order' => 10,
]);

User action buttons

Register a button in Admin β†’ Users per-user row:

$container->get(UserActionRegistry::class)->register('my-action', [
    'label'        => 'Manage',
    'path_pattern' => '/admin/my-plugin/users/{id}',
    'order'        => 10,
]);

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:

Form Slot Position
login form_fields Inside <form>, before the submit button
login scripts In {% block scripts %}, outside the form
register form_fields Inside <form>, before the submit button
register scripts At the end of {% block scripts %}
use rafalmasiarek\DashboardKit\Extension\FormSlotRegistry;

$registry = $dashboard->getContainer()->get(FormSlotRegistry::class);

// Static HTML string
$registry->register('login', 'form_fields', '<div class="g-recaptcha mb-3" data-sitekey="..."></div>');

// Callable β€” evaluated at render time, can inspect session or other runtime state
$registry->register('login', 'form_fields', static function (): string {
    return ((int) ($_SESSION['login_fails'] ?? 0)) >= 3
        ? '<div class="g-recaptcha mb-3" data-sitekey="..."></div>'
        : '';
});

// Optional order parameter β€” lower numbers render first (default: 100)
$registry->register('login', 'form_fields', $tosCheckbox, order: 10);
$registry->register('login', 'form_fields', $captchaWidget, order: 50);

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:

$dashboard->on('login_failed', function (string $email, string $ip) {
    // track failure, increment counter, notify, etc.
});

$dashboard->on('register_failed', function (string $email, string $errorMessage, string $ip) {
    // track registration abuse, duplicate detection, etc.
});

Error handling

SafeErrorHandler handles all Slim errors with content negotiation:

  • JSON clients (Accept: application/json, AJAX, CLI) receive:
    { "status": "error", "code": 404, "message": "Not found.", "data": {}, "errors": [] }
  • 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:

// config
'logging' => [
    'channels' => [
        'app'   => ['path' => storage_path('logs/app.log'),   'level' => 'info'],
        'audit' => ['path' => storage_path('logs/audit.log'), 'level' => 'info'],
        'error' => ['path' => storage_path('logs/error.log'), 'level' => 'warning'],
    ],
],

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

Route Description
GET / Home page β€” auth-aware, renders home.twig
GET/POST /login Login
GET /logout Logout
GET/POST /register Registration
GET /settings User settings
GET /admin Admin panel
GET /admin/users User management

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:

{# templates/home.twig #}
{% extends "layout.twig" %}

{% block content %}
{% if auth.isLoggedIn() %}
    <h2>Welcome, {{ auth.getUser().get('email') }}</h2>
{% else %}
    <h1>{{ app_name }}</h1>
    <a href="/login" class="btn btn-primary">Log in</a>
{% endif %}
{% endblock %}

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:

Block Default Use
{% block head %} empty Extra <link> / <meta> tags
{% block navbar %} Bootstrap navbar Replace or remove the navbar
{% block header %} empty Hero/banner below navbar
{% block content %} empty Main page body
{% block footer %} empty Site-wide footer
{% block scripts %} empty Extra scripts before </body>

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):

{# templates/layout.twig #}
{% extends "@dashboard-kit/layout.twig" %}

{% block footer %}
<footer class="text-center text-muted small py-4">&copy; {{ "now"|date("Y") }} {{ app_name }}</footer>
{% endblock %}

See docs/templating.md for the full reference.

Index

Classes

Interfaces

CachingPdo

class β€” rafalmasiarek\DashboardKit\Cache\CachingPdo Β· source

PDO subclass that caches SELECT query results with tag-based invalidation. Drop-in replacement for PDO: type-compatible (extends PDO), registered as PDO::class in the DI container. All prepared statements automatically become CachingStatement instances via PDO::ATTR_STATEMENT_CLASS. exec() is overridden to invalidate tagged cache entries after data-modifying statements that bypass prepare/execute (e.g. raw INSERT/UPDATE/DELETE strings). The backing driver must be constructed against a separate raw PDO connection ('pdo.raw' in the container) to avoid a circular dependency β€” the driver itself queries _query_cache, which is already excluded from caching in CachingStatement (SYSTEM_TABLES).

extends PDO

Depends on: QueryCacheDriverInterface, SqlTableExtractor, TransactionState

Property Type Visibility Description
$extractor SqlTableExtractor private Shared SQL table name parser reused across all exec() calls.
$txState TransactionState private Shared transaction state bag coordinating this connection and all its prepared statements.
Method Visibility Returns Summary
__construct() public β€” β€”
table() public string Returns the prefixed table name for use in raw SQL queries. Use this in every handler that builds SQL manually so that the configured table prefix is applied consistently: $db->prepare("SELECT * FROM " . $db->table('short_links') . " WHERE ...") When no prefix is configured, the name is returned as-is.
exec() public int|false Executes a raw SQL statement and invalidates cache entries for write statements. DDL statements (CREATE, ALTER, DROP) are executed unchanged; they are not detected as writes and do not trigger invalidation. When a transaction is active, dirty table names are accumulated in TransactionState rather than invalidated immediately; CachingPdo::commit() flushes them once the transaction is durably written.
beginTransaction() public bool Starts a PDO transaction and enables transaction-mode on the shared state. While the transaction is active, CachingStatement will bypass the query cache on reads and accumulate write table names in TransactionState::$dirtyTables rather than invalidating immediately.
commit() public bool Commits the active transaction and invalidates cache entries for all tables written during it. Invalidation is deferred until commit so that concurrent readers only see the cache purge after the transaction is durably written, not mid-flight.
rollBack() public bool Rolls back the active transaction and discards accumulated dirty-table tracking. No invalidation is issued β€” rolled-back writes never reached the DB, so cached SELECT results remain valid and no cache purge is needed.
__construct()

CachingPdo __construct()

source

public function __construct(string $dsn, string $username, string $password, array $options, QueryCacheDriverInterface $driver, int $defaultTtl, string $tablePrefix)
Param Type Description
$dsn string PDO DSN string.
$username string Database user.
$password string Database password.
$options array<int, mixed> PDO driver options.
$driver QueryCacheDriverInterface Tag-based cache driver (must use raw PDO internally).
$defaultTtl int Default cache TTL in seconds. Default: 300.
$tablePrefix string Optional prefix prepended by table(). Default: ''.
table()

CachingPdo table()

source

public function table(string $name): string

Returns the prefixed table name for use in raw SQL queries. Use this in every handler that builds SQL manually so that the configured table prefix is applied consistently: $db->prepare("SELECT * FROM " . $db->table('short_links') . " WHERE ...") When no prefix is configured, the name is returned as-is.

Param Type Description
$name string Logical (un-prefixed) table name.

Returns: string β€” Prefixed table name ready for use in SQL.

exec()

CachingPdo exec()

source

public function exec(string $statement): int|false

Executes a raw SQL statement and invalidates cache entries for write statements. DDL statements (CREATE, ALTER, DROP) are executed unchanged; they are not detected as writes and do not trigger invalidation. When a transaction is active, dirty table names are accumulated in TransactionState rather than invalidated immediately; CachingPdo::commit() flushes them once the transaction is durably written.

Param Type Description
$statement string SQL to execute.

Returns: int\|false β€” Number of affected rows, or false on failure.

beginTransaction()

CachingPdo beginTransaction()

source

public function beginTransaction(): bool

Starts a PDO transaction and enables transaction-mode on the shared state. While the transaction is active, CachingStatement will bypass the query cache on reads and accumulate write table names in TransactionState::$dirtyTables rather than invalidating immediately.

Returns: bool

commit()

CachingPdo commit()

source

public function commit(): bool

Commits the active transaction and invalidates cache entries for all tables written during it. Invalidation is deferred until commit so that concurrent readers only see the cache purge after the transaction is durably written, not mid-flight.

Returns: bool

rollBack()

CachingPdo rollBack()

source

public function rollBack(): bool

Rolls back the active transaction and discards accumulated dirty-table tracking. No invalidation is issued β€” rolled-back writes never reached the DB, so cached SELECT results remain valid and no cache purge is needed.

Returns: bool

CachingStatement

final class β€” rafalmasiarek\DashboardKit\Cache\CachingStatement Β· source

PDOStatement subclass that transparently caches SELECT results using tag-based invalidation. Instantiated automatically by CachingPdo via PDO::ATTR_STATEMENT_CLASS. Never constructed directly. Behaviour per statement type: SELECT β€” checks the driver before executing; on miss, executes and caches the fetchAll() result keyed by sql + params (no version embedding). WRITE β€” executes normally, then invalidates all cache entries tagged with the affected table names. SYSTEM β€” queries touching _query_cache or _schema_state are always passed through to PDO unchanged (no caching, no invalidation). TRANSACTION-ACTIVE β€” bypasses cache entirely; write table names are appended to TransactionState::$dirtyTables for deferred invalidation on commit. Only fetchAll() results are cached. fetch() and fetchColumn() always hit the DB. The cache key is md5(sql + params) β€” no version numbers embedded. Invalidation is tag-driven: a write to table T deletes every entry tagged with T.

extends PDOStatement

Depends on: QueryCacheDriverInterface, SqlTableExtractor, TransactionState

Property Type Visibility Description
$boundValues array<string|int, mixed> private Values captured by bindValue() calls, used to build the cache key when execute() is called without an explicit $params array.
$hitResult list<mixed>|null private Populated on a cache hit; consumed and cleared by fetchAll().
$pendingKey string|null private Cache key waiting to be written after a SELECT miss. Set in execute(), consumed in fetchAll().
$pendingTags list<string>|null private Table tags associated with the pending cache write. Set alongside $pendingKey in execute(), consumed in fetchAll().
$fromCache bool private True when the last execute() was served from cache.
Method Visibility Returns Summary
__construct() protected β€” β€”
bindValue() public bool Intercepts parameter binding to track values for cache-key construction.
execute() public bool Executes the statement with transparent cache read-through for SELECTs.
fetchAll() public list<mixed> Returns cached rows on a hit, or fetches and stores them on a miss.
buildKey() private string Builds a deterministic cache key from the SQL and its bound parameters. No version numbers are embedded β€” invalidation is handled by tag deletion rather than key rotation, so the key remains stable across writes.
reset() private void Resets all per-execution state before each execute() call.
__construct()

CachingStatement __construct()

source

protected function __construct(QueryCacheDriverInterface $driver, int $defaultTtl, SqlTableExtractor $extractor, TransactionState $txState)
Param Type Description
$driver QueryCacheDriverInterface Tag-based cache driver.
$defaultTtl int Cache entry TTL in seconds.
$extractor SqlTableExtractor SQL table-name parser.
$txState TransactionState Shared transaction coordination bag from CachingPdo.
bindValue()

CachingStatement bindValue()

source

public function bindValue(string|int $param, mixed $value, int $type): bool

Intercepts parameter binding to track values for cache-key construction.

Param Type Description
$param string|int Column name or positional index.
$value mixed Value to bind.
$type int PDO::PARAM_* constant.

Returns: bool

execute()

CachingStatement execute()

source

public function execute(?array $params): bool

Executes the statement with transparent cache read-through for SELECTs.

Param Type Description
$params array<mixed>|null Bound values, overrides any prior bindValue() calls.

Returns: bool

fetchAll()

CachingStatement fetchAll()

source

public function fetchAll(int $mode, mixed $args): array

Returns cached rows on a hit, or fetches and stores them on a miss.

Param Type Description
$mode int PDO::FETCH_* mode.
$args mixed β€”

Returns: list<mixed>

buildKey()

CachingStatement buildKey()

source

private function buildKey(string $sql, array $params): string

Builds a deterministic cache key from the SQL and its bound parameters. No version numbers are embedded β€” invalidation is handled by tag deletion rather than key rotation, so the key remains stable across writes.

Param Type Description
$sql string β€”
$params array<mixed> β€”

Returns: string

reset()

CachingStatement reset()

source

private function reset(): void

Resets all per-execution state before each execute() call.

ArrayQueryCacheDriver

final class β€” rafalmasiarek\DashboardKit\Cache\Driver\ArrayQueryCacheDriver Β· source

In-memory per-request query cache driver backed by a plain PHP array. Entries exist only for the lifetime of the current request and are never persisted. Useful for tests, for reducing repeated identical queries within a single request when a persistent cache backend is unavailable, or as a first-level cache in front of a slower driver.

implements QueryCacheDriverInterface

Package: rafalmasiarek\DashboardKit\Cache

Property Type Visibility Description
$store array<string, array{rows: array<mixed>, tags: list<string>, expires_at: int}> private Internal store keyed by cache key. Each entry: ['rows' => list, 'tags' => list, 'expires_at' => int]
Method Visibility Returns Summary
get() public array<mixed>|null Returns cached rows if the entry exists and has not expired.
set() public void Stores a row set with the given tags and TTL.
invalidate() public void Removes all entries whose tag set intersects with the given table names.
flush() public void Removes all entries from the in-memory store.
get()

ArrayQueryCacheDriver get()

source

public function get(string $key): ?array

Returns cached rows if the entry exists and has not expired.

Param Type Description
$key string Cache key.

Returns: array<mixed>\|null β€” Cached row set, or null on miss or expiry.

set()

ArrayQueryCacheDriver set()

source

public function set(string $key, array $rows, int $ttl, string $tags): void

Stores a row set with the given tags and TTL.

Param Type Description
$key string Cache key.
$rows array<mixed> Row set to cache.
$ttl int Time-to-live in seconds.
$tags string β€”
invalidate()

ArrayQueryCacheDriver invalidate()

source

public function invalidate(string $tags): void

Removes all entries whose tag set intersects with the given table names.

Param Type Description
$tags string β€”
flush()

ArrayQueryCacheDriver flush()

source

public function flush(): void

Removes all entries from the in-memory store.

NullQueryCacheDriver

final class β€” rafalmasiarek\DashboardKit\Cache\Driver\NullQueryCacheDriver Β· source

No-op query cache driver that never stores or returns anything. Useful in environments where caching is undesirable (e.g. CLI commands, test suites, or deployments without a suitable cache backend). Every read returns null (cache miss), and write operations are silently discarded.

implements QueryCacheDriverInterface

Package: rafalmasiarek\DashboardKit\Cache

Method Visibility Returns Summary
get() public array<mixed>|null Always reports a cache miss.
set() public void Discards the row set without storing it.
invalidate() public void No-op invalidation.
flush() public void No-op flush.
get()

NullQueryCacheDriver get()

source

public function get(string $key): ?array

Always reports a cache miss.

Param Type Description
$key string Cache key.

Returns: array<mixed>\|null β€” Always null.

set()

NullQueryCacheDriver set()

source

public function set(string $key, array $rows, int $ttl, string $tags): void

Discards the row set without storing it.

Param Type Description
$key string Cache key.
$rows array<mixed> Row set to discard.
$ttl int Time-to-live in seconds (ignored).
$tags string β€”
invalidate()

NullQueryCacheDriver invalidate()

source

public function invalidate(string $tags): void

No-op invalidation.

Param Type Description
$tags string β€”
flush()

NullQueryCacheDriver flush()

source

public function flush(): void

No-op flush.

PdoQueryCacheDriver

final class β€” rafalmasiarek\DashboardKit\Cache\Driver\PdoQueryCacheDriver Β· source

Database-backed tag-based query result cache stored in _query_cache. Uses a raw PDO connection (never CachingPdo) to avoid a circular dependency. The backing table is created automatically on first use if absent. Each row stores the serialized row set (payload), a JSON array of table tags, and an expiry timestamp. Invalidation deletes all rows whose tags overlap with the given set β€” no version counters, no stale-key accumulation. MySQL and SQLite are both supported; the driver auto-detects the engine from PDO::ATTR_DRIVER_NAME and adjusts its queries accordingly.

implements QueryCacheDriverInterface

Depends on: PDO, ClockInterface

Package: rafalmasiarek\DashboardKit\Cache

Property Type Visibility Description
$driver string private Detected PDO driver name ('mysql' or 'sqlite').
Method Visibility Returns Summary
__construct() public β€” β€”
get() public array<mixed>|null Retrieves cached rows by key if the entry exists and has not expired.
set() public void Stores a row set with associated tags and a time-to-live. The payload JSON embeds diagnostic metadata (version, timestamps, TTL, table list, row count, column names) alongside the rows for introspection. The tags column is stored separately as a JSON array for SQL-level filtering during invalidation.
invalidate() public void Deletes all cache entries tagged with any of the given table names. No-op when called with no tags, preventing accidental full-table deletes.
flush() public void Removes all entries from the cache table unconditionally.
prune() public int Deletes expired cache entries and returns the number of rows removed. Wire this into any scheduled task (e.g. daily cron via dashboard-kit-scheduler) to prevent unbounded table growth from naturally expiring entries that were never explicitly invalidated.
ensureTable() private void Creates or migrates the _query_cache table. If the table is absent, it is created with the current schema. If the table exists but is missing the tags column (schema from the pre-tag-based version), it is dropped and recreated. Cache data is ephemeral, so the drop is safe.
__construct()

PdoQueryCacheDriver __construct()

source

public function __construct(PDO $pdo, ?ClockInterface $clock)
Param Type Description
$pdo PDO Raw database connection. Must not be a CachingPdo instance.
$clock ClockInterface|null Clock for cached_at/expires_at metadata. Defaults to SystemClock.
get()

PdoQueryCacheDriver get()

source

public function get(string $key): ?array

Retrieves cached rows by key if the entry exists and has not expired.

Param Type Description
$key string Cache key.

Returns: array<mixed>\|null β€” Cached row set, or null on miss or expiry.

set()

PdoQueryCacheDriver set()

source

public function set(string $key, array $rows, int $ttl, string $tags): void

Stores a row set with associated tags and a time-to-live. The payload JSON embeds diagnostic metadata (version, timestamps, TTL, table list, row count, column names) alongside the rows for introspection. The tags column is stored separately as a JSON array for SQL-level filtering during invalidation.

Param Type Description
$key string Cache key.
$rows array<mixed> Row set to cache.
$ttl int Time-to-live in seconds.
$tags string β€”
invalidate()

PdoQueryCacheDriver invalidate()

source

public function invalidate(string $tags): void

Deletes all cache entries tagged with any of the given table names. No-op when called with no tags, preventing accidental full-table deletes.

Param Type Description
$tags string β€”
flush()

PdoQueryCacheDriver flush()

source

public function flush(): void

Removes all entries from the cache table unconditionally.

prune()

PdoQueryCacheDriver prune()

source

public function prune(): int

Deletes expired cache entries and returns the number of rows removed. Wire this into any scheduled task (e.g. daily cron via dashboard-kit-scheduler) to prevent unbounded table growth from naturally expiring entries that were never explicitly invalidated.

Returns: int β€” Number of deleted rows.

ensureTable()

PdoQueryCacheDriver ensureTable()

source

private function ensureTable(): void

Creates or migrates the _query_cache table. If the table is absent, it is created with the current schema. If the table exists but is missing the tags column (schema from the pre-tag-based version), it is dropped and recreated. Cache data is ephemeral, so the drop is safe.

QueryCacheDriverInterface

interface β€” rafalmasiarek\DashboardKit\Cache\QueryCacheDriverInterface Β· source

Contract for tag-based query result cache drivers. Each SELECT result is stored under a key derived from the SQL and its bound parameters, tagged with the names of the tables the query reads. On any write to a table, the driver deletes every entry tagged with that table name β€” providing automatic, targeted cache invalidation without version counters.

Method Visibility Returns Summary
get() public array<mixed>|null Retrieves cached rows by key. Returns null on a cache miss (entry absent or expired).
set() public void Stores a row set under the given key with the supplied tags and TTL. If an entry already exists for the key, it is overwritten.
invalidate() public void Deletes all cache entries tagged with any of the given table names. Called after every write (INSERT / UPDATE / DELETE / REPLACE) outside a transaction, and once per transaction on commit with the union of all tables written during that transaction.
flush() public void Removes all entries from the cache store unconditionally. Useful for admin panel "clear cache" actions or test teardown.
get()

QueryCacheDriverInterface get()

source

public function get(string $key): ?array

Retrieves cached rows by key. Returns null on a cache miss (entry absent or expired).

Param Type Description
$key string Cache key produced by CachingStatement::buildKey().

Returns: array<mixed>\|null β€” Cached row set, or null on miss.

set()

QueryCacheDriverInterface set()

source

public function set(string $key, array $rows, int $ttl, string $tags): void

Stores a row set under the given key with the supplied tags and TTL. If an entry already exists for the key, it is overwritten.

Param Type Description
$key string Cache key.
$rows array<mixed> Row set returned by fetchAll().
$ttl int Time-to-live in seconds.
$tags string β€”
invalidate()

QueryCacheDriverInterface invalidate()

source

public function invalidate(string $tags): void

Deletes all cache entries tagged with any of the given table names. Called after every write (INSERT / UPDATE / DELETE / REPLACE) outside a transaction, and once per transaction on commit with the union of all tables written during that transaction.

Param Type Description
$tags string β€”
flush()

QueryCacheDriverInterface flush()

source

public function flush(): void

Removes all entries from the cache store unconditionally. Useful for admin panel "clear cache" actions or test teardown.

SqlTableExtractor

final class β€” rafalmasiarek\DashboardKit\Cache\SqlTableExtractor Β· source

Extracts table names and write intent from a SQL statement. Tokenizer-based, no external dependencies. Handles SELECT/INSERT/UPDATE/DELETE/REPLACE including subqueries, JOIN qualifiers, comma-separated FROM lists, backtick-quoted identifiers, and qualified column references (table.column). DDL statements (CREATE, ALTER, DROP, TRUNCATE, RENAME) are detected early and returned as non-write with an empty table list, preventing misidentification of DDL keywords inside column definitions as table names or write operations.

Method Visibility Returns Summary
extract() public array{tables: list<string>, is_write: bool} Extract table names and write status from a SQL statement. Join qualifiers (LEFT, INNER, OUTER, etc.) that appear before JOIN are skipped naturally because they are not in TABLE_INTRO and are treated as no-ops by the outer scanner. Subqueries are handled transparently: the scanner processes all tokens linearly, so tables inside subqueries are found when their own FROM/JOIN keywords are reached.
stripLiterals() private string Replace single- and double-quoted string literals with empty placeholders. Prevents SQL keywords inside string values from being misread as table-intro keywords (e.g. a value like "FROM users" inside a LIKE clause).
stripComments() private string Remove SQL line comments (--) and block comments (/* … * /).
tokenize() private list<string> Split the SQL into meaningful tokens. Matches (in priority order): 1. Backtick-quoted identifiers: table_name 2. Qualified references (col or tbl.col) β€” dot notation kept together so that users.id is one token and rejected by isIdentifier (dot present). 3. Parentheses and commas β€” structural delimiters.
unquote() private string Strip surrounding backticks from a token.
isIdentifier() private bool Return true when the (already unquoted) token is a valid table or alias name. Rejects SQL reserved words and qualified references (tokens containing a dot, which are column references like users.id).
extract()

SqlTableExtractor extract()

source

public function extract(string $sql): array

Extract table names and write status from a SQL statement. Join qualifiers (LEFT, INNER, OUTER, etc.) that appear before JOIN are skipped naturally because they are not in TABLE_INTRO and are treated as no-ops by the outer scanner. Subqueries are handled transparently: the scanner processes all tokens linearly, so tables inside subqueries are found when their own FROM/JOIN keywords are reached.

Param Type Description
$sql string Raw SQL, may contain ? or :name placeholders.

Returns: array{tables: list<string>, is_write: bool}

stripLiterals()

SqlTableExtractor stripLiterals()

source

private function stripLiterals(string $sql): string

Replace single- and double-quoted string literals with empty placeholders. Prevents SQL keywords inside string values from being misread as table-intro keywords (e.g. a value like "FROM users" inside a LIKE clause).

Param Type Description
$sql string β€”

Returns: string

stripComments()

SqlTableExtractor stripComments()

source

private function stripComments(string $sql): string

Remove SQL line comments (--) and block comments (/* … * /).

Param Type Description
$sql string β€”

Returns: string

tokenize()

SqlTableExtractor tokenize()

source

private function tokenize(string $sql): array

Split the SQL into meaningful tokens. Matches (in priority order): 1. Backtick-quoted identifiers: table_name 2. Qualified references (col or tbl.col) β€” dot notation kept together so that users.id is one token and rejected by isIdentifier (dot present). 3. Parentheses and commas β€” structural delimiters.

Param Type Description
$sql string β€”

Returns: list<string>

unquote()

SqlTableExtractor unquote()

source

private function unquote(string $token): string

Strip surrounding backticks from a token.

Param Type Description
$token string β€”

Returns: string

isIdentifier()

SqlTableExtractor isIdentifier()

source

private function isIdentifier(string $name): bool

Return true when the (already unquoted) token is a valid table or alias name. Rejects SQL reserved words and qualified references (tokens containing a dot, which are column references like users.id).

Param Type Description
$name string Unquoted token.

Returns: bool

TransactionState

final class β€” rafalmasiarek\DashboardKit\Cache\TransactionState Β· source

Shared mutable transaction state passed between CachingPdo and CachingStatement. Acts as a coordination bag: CachingPdo sets $active on begin/commit/rollback; CachingStatement reads $active to decide whether to skip the cache and appends to $dirtyTables instead of bumping immediately. CachingPdo flushes accumulated dirty tables to TableVersionTracker on commit and discards them on rollback. Passed by object handle so mutations in CachingPdo are immediately visible in every CachingStatement prepared from the same connection.

Property Type Visibility Description
$active bool public Whether a PDO transaction is currently active.
$dirtyTables list<string> public Tables touched by writes during the active transaction. Accumulated by CachingStatement and CachingPdo::exec() during a transaction. Flushed to TableVersionTracker on commit; discarded on rollback.

AuthController

class β€” rafalmasiarek\DashboardKit\Controllers\AuthController Β· source

Handles login, registration and logout flows.

Depends on: Twig, Auth, Flash, HookRegistry, AuditLog, PDO, MailerInterface

Method Visibility Returns Summary
__construct() public β€” β€”
login() public Response Renders the login form (GET) or processes credentials (POST). Reads a ?from= query parameter (GET) or a hidden 'from' field (POST) and redirects there after successful login instead of the default '/'. Only same-origin paths are accepted (must start with '/' but not '//').
register() public Response Renders the registration form (GET) or creates a new account (POST). On successful registration a UUID v4 is assigned to the new user row. If password_strength is enabled the password is scored server-side before the account is created; scores below min_score are rejected with an error.
logout() public Response Destroys the current session and redirects to /login.
sendActivationEmail() private void Generates an activation token, stores it, and sends the activation email. When the mailer is not configured, only the token is stored; no email is sent.
baseUrl() private string Derives the base URL (scheme + host + optional port) from the request.
__construct()

AuthController __construct()

source

public function __construct(Twig $view, Auth $auth, Flash $flash, array $userFields, HookRegistry $hooks, AuditLog $audit, PDO $db, array $passwordStrength, bool $requireActivation, ?MailerInterface $mailer, mixed $beforeLogin, mixed $beforeRegister, string $dashboardUrlPrefix)
Param Type Description
$view Twig Twig rendering engine.
$auth Auth AuthKit authentication service.
$flash Flash Flash message store.
$userFields array<string, array{label: string, type: string, max: int, required: bool}> Extra profile fields shown on the register form.
$hooks HookRegistry Event hook registry.
$audit AuditLog Audit logger.
$db PDO Database connection β€” used to assign UUID on registration.
$passwordStrength array<string, mixed> Resolved password-strength config (enabled, min_score, rules).
$requireActivation bool When true, sends an activation email after registration.
$mailer MailerInterface|null Mailer instance; required when requireActivation is true to send emails.
$beforeLogin callable|null Called before credential check on POST /login. Signature: (Request): ?string β€” return null to pass, string to block with that error. Set via config key 'before_login' or $container->set('auth.before_login', callable).
$beforeRegister callable|null Called before account creation on POST /register. Same signature as $beforeLogin. Set via config key 'before_register' or $container->set('auth.before_register', callable).
$dashboardUrlPrefix string Full URL prefix prepended to all dashboard redirects (e.g. '/api/admin'). Combines app.base_path and dashboard.prefix from config.
login()

AuthController login()

source

public function login(Request $request, Response $response): Response

Renders the login form (GET) or processes credentials (POST). Reads a ?from= query parameter (GET) or a hidden 'from' field (POST) and redirects there after successful login instead of the default '/'. Only same-origin paths are accepted (must start with '/' but not '//').

Param Type Description
$request Request Incoming request.
$response Response PSR-7 response.

Returns: Response

register()

AuthController register()

source

public function register(Request $request, Response $response): Response

Renders the registration form (GET) or creates a new account (POST). On successful registration a UUID v4 is assigned to the new user row. If password_strength is enabled the password is scored server-side before the account is created; scores below min_score are rejected with an error.

Param Type Description
$request Request Incoming request.
$response Response PSR-7 response.

Returns: Response

logout()

AuthController logout()

source

public function logout(Request $request, Response $response): Response

Destroys the current session and redirects to /login.

Param Type Description
$request Request Incoming request.
$response Response PSR-7 response.

Returns: Response

sendActivationEmail()

AuthController sendActivationEmail()

source

private function sendActivationEmail(\AuthKit\User $user, Request $request): void

Generates an activation token, stores it, and sends the activation email. When the mailer is not configured, only the token is stored; no email is sent.

Param Type Description
$user \AuthKit\User Newly registered user.
$request Request Current HTTP request (used to build the activation URL).
baseUrl()

AuthController baseUrl()

source

private function baseUrl(Request $request): string

Derives the base URL (scheme + host + optional port) from the request.

Param Type Description
$request Request β€”

Returns: string

PasswordResetController

class β€” rafalmasiarek\DashboardKit\Controllers\PasswordResetController Β· source

Handles the forgot-password and password-reset flows. Routes (all public, no auth required): GET /forgot-password β€” render the "enter your email" form POST /forgot-password β€” generate token and send reset email GET /reset-password/{token} β€” render the "choose new password" form POST /reset-password/{token} β€” validate token and update password Hooks emitted: password_reset_requested (string $email) password_reset_completed (\AuthKit\User $user)

Depends on: Twig, Auth, Flash, PDO, HookRegistry, AuditLog, MailerInterface

Method Visibility Returns Summary
__construct() public β€” β€”
requestForm() public Response Renders the forgot-password form.
request() public Response Processes the forgot-password form. Always responds with a neutral flash to avoid revealing whether the email is registered. When the email exists: generates a token, sends the reset email (or logs the link), and emits the password_reset_requested hook.
resetForm() public Response Renders the reset-password form for a given token. Validates the token before rendering β€” redirects to /forgot-password on invalid/expired tokens.
reset() public Response Processes the reset-password form. Validates token, password match and optional strength requirement, then updates the password hash directly (bypassing current-password check), invalidates all existing sessions, and emits the password_reset_completed hook.
tokenExists() private bool Checks whether a token exists in password_resets and has not yet expired.
baseUrl() private string Derives the base URL (scheme + host + optional port) from the request.
__construct()

PasswordResetController __construct()

source

public function __construct(Twig $view, Auth $auth, Flash $flash, PDO $db, HookRegistry $hooks, AuditLog $audit, array $passwordStrength, ?MailerInterface $mailer, string $dashboardUrlPrefix)
Param Type Description
$view Twig Twig rendering engine.
$auth Auth AuthKit authentication service.
$flash Flash Flash message store.
$db PDO Database connection.
$hooks HookRegistry Event hook registry.
$audit AuditLog Audit logger.
$passwordStrength array<string, mixed> Resolved password-strength config.
$mailer MailerInterface|null Optional mailer β€” reset link is logged when null.
$dashboardUrlPrefix string Full URL prefix for dashboard redirects (e.g. '/api/admin').
requestForm()

PasswordResetController requestForm()

source

public function requestForm(Request $request, Response $response): Response

Renders the forgot-password form.

Param Type Description
$request Request β€”
$response Response β€”

Returns: Response

request()

PasswordResetController request()

source

public function request(Request $request, Response $response): Response

Processes the forgot-password form. Always responds with a neutral flash to avoid revealing whether the email is registered. When the email exists: generates a token, sends the reset email (or logs the link), and emits the password_reset_requested hook.

Param Type Description
$request Request β€”
$response Response β€”

Returns: Response

resetForm()

PasswordResetController resetForm()

source

public function resetForm(Request $request, Response $response, array $args): Response

Renders the reset-password form for a given token. Validates the token before rendering β€” redirects to /forgot-password on invalid/expired tokens.

Param Type Description
$request Request β€”
$response Response β€”
$args array<string, string> Route arguments (token).

Returns: Response

reset()

PasswordResetController reset()

source

public function reset(Request $request, Response $response, array $args): Response

Processes the reset-password form. Validates token, password match and optional strength requirement, then updates the password hash directly (bypassing current-password check), invalidates all existing sessions, and emits the password_reset_completed hook.

Param Type Description
$request Request β€”
$response Response β€”
$args array<string, string> Route arguments (token).

Returns: Response

tokenExists()

PasswordResetController tokenExists()

source

private function tokenExists(string $token): bool

Checks whether a token exists in password_resets and has not yet expired.

Param Type Description
$token string β€”

Returns: bool

baseUrl()

PasswordResetController baseUrl()

source

private function baseUrl(Request $request): string

Derives the base URL (scheme + host + optional port) from the request.

Param Type Description
$request Request β€”

Returns: string

SettingsController

class β€” rafalmasiarek\DashboardKit\Controllers\SettingsController Β· source

Handles the current user's account settings: password, email changes, and custom profile fields. Routes are registered internally by Dashboard and protected by AuthMiddleware.

Depends on: Twig, Auth, Flash, PDO, HookRegistry, AuditLog

Method Visibility Returns Summary
__construct() public β€” β€”
index() public Response Renders the settings page.
changePassword() public Response Processes a password change request. Validates current password before applying the new one.
changeEmail() public Response Processes an email address change request. Rejects the new address if it is already taken by another account.
updateProfile() public Response Processes a profile fields update (all user_fields at once). Validates required fields before saving. Empty optional values are stored as NULL.
__construct()

SettingsController __construct()

source

public function __construct(Twig $view, Auth $auth, Flash $flash, PDO $db, array $userFields, HookRegistry $hooks, AuditLog $audit, string $dashboardUrlPrefix)
Param Type Description
$view Twig Twig rendering engine.
$auth Auth AuthKit authentication service.
$flash Flash Flash message store.
$db PDO Database connection.
$userFields array<string, array{label: string, type: string, max: int, required: bool}> Extra profile fields.
$hooks HookRegistry Event hook registry.
$audit AuditLog Audit logger.
$dashboardUrlPrefix string Full URL prefix for dashboard routes (base_path + dashboard.prefix).
index()

SettingsController index()

source

public function index(Request $request, Response $response): Response

Renders the settings page.

Param Type Description
$request Request β€”
$response Response β€”

Returns: Response

changePassword()

SettingsController changePassword()

source

public function changePassword(Request $request, Response $response): Response

Processes a password change request. Validates current password before applying the new one.

Param Type Description
$request Request β€”
$response Response β€”

Returns: Response

changeEmail()

SettingsController changeEmail()

source

public function changeEmail(Request $request, Response $response): Response

Processes an email address change request. Rejects the new address if it is already taken by another account.

Param Type Description
$request Request β€”
$response Response β€”

Returns: Response

updateProfile()

SettingsController updateProfile()

source

public function updateProfile(Request $request, Response $response): Response

Processes a profile fields update (all user_fields at once). Validates required fields before saving. Empty optional values are stored as NULL.

Param Type Description
$request Request β€”
$response Response β€”

Returns: Response

UserController

class β€” rafalmasiarek\DashboardKit\Controllers\UserController Β· source

Handles admin user management: listing, editing, role changes, suspend, unsuspend, and delete. Routes are registered internally by Dashboard and protected by admin RoleMiddleware.

Depends on: Twig, Auth, Flash, PDO, HookRegistry, AuditLog

Method Visibility Returns Summary
__construct() public β€” β€”
list() public Response Renders the user list with search, sortable columns and pagination. Query parameters: q β€” search term (matches email) sort β€” column name; allowed: id, email, role, active, suspended_at dir β€” asc or desc page β€” page number (1-based)
edit() public Response Renders the edit form for a single user, looked up by UUID.
update() public Response Processes the edit form β€” updates email, role, active flag and all custom profile fields. User is looked up by UUID; all DB writes use the internal integer ID. Fires the user_updated hook with the target user and the admin who made the change.
delete() public Response Permanently deletes a user account and invalidates all their sessions. An admin cannot delete their own account. User is looked up by UUID; deletion uses the internal integer ID. Fires the user_deleted hook with the target user and the admin.
suspend() public Response Suspends a user and immediately invalidates all their sessions. An admin cannot suspend themselves. User is looked up by UUID; DB writes use the internal integer ID.
unsuspend() public Response Removes the suspension from a user, allowing them to log in again. User is looked up by UUID; DB writes use the internal integer ID.
createForm() public Response Renders the create-user form.
create() public Response Processes the create-user form and creates a new active account. Admin-created accounts are immediately active regardless of the require_activation setting. A UUID is assigned and the user_created audit event is fired.
fetchUserRowById() private array<string, mixed>|null Fetches a single user row by ID (UUID), including all custom profile columns. Returns null when no user with that ID exists.
fetchUser() private \AuthKit\User|null Fetches a user row and wraps it in a User object. Returns null when the user does not exist.
paginationRange() private static array<int, int|string> Computes the visible page numbers for the pagination bar. Always includes the first and last page. Shows a window of Β±2 around the current page. Inserts '...' strings between non-adjacent groups.
__construct()

UserController __construct()

source

public function __construct(Twig $view, Auth $auth, Flash $flash, PDO $db, array $userFields, HookRegistry $hooks, AuditLog $audit, bool $requireActivation, string $adminPanelUrlPrefix)
Param Type Description
$view Twig Twig rendering engine.
$auth Auth AuthKit authentication service.
$flash Flash Flash message store.
$db PDO Database connection.
$userFields array<string, array{label: string, type: string, max: int, required: bool}> Configured custom profile fields.
$hooks HookRegistry Event hook registry.
$audit AuditLog Audit logger.
$requireActivation bool When true, the active column exists and is exposed in list/edit UI.
$adminPanelUrlPrefix string Full URL prefix for the admin panel (base_path + dashboard.prefix + dashboard.admin_prefix).
list()

UserController list()

source

public function list(Request $request, Response $response): Response

Renders the user list with search, sortable columns and pagination. Query parameters: q β€” search term (matches email) sort β€” column name; allowed: id, email, role, active, suspended_at dir β€” asc or desc page β€” page number (1-based)

Param Type Description
$request Request β€”
$response Response β€”

Returns: Response

edit()

UserController edit()

source

public function edit(Request $request, Response $response, array $args): Response

Renders the edit form for a single user, looked up by UUID.

Param Type Description
$request Request β€”
$response Response β€”
$args array<string, string> Route arguments (id).

Returns: Response

update()

UserController update()

source

public function update(Request $request, Response $response, array $args): Response

Processes the edit form β€” updates email, role, active flag and all custom profile fields. User is looked up by UUID; all DB writes use the internal integer ID. Fires the user_updated hook with the target user and the admin who made the change.

Param Type Description
$request Request β€”
$response Response β€”
$args array<string, string> Route arguments (id).

Returns: Response

delete()

UserController delete()

source

public function delete(Request $request, Response $response, array $args): Response

Permanently deletes a user account and invalidates all their sessions. An admin cannot delete their own account. User is looked up by UUID; deletion uses the internal integer ID. Fires the user_deleted hook with the target user and the admin.

Param Type Description
$request Request β€”
$response Response β€”
$args array<string, string> Route arguments (id).

Returns: Response

suspend()

UserController suspend()

source

public function suspend(Request $request, Response $response, array $args): Response

Suspends a user and immediately invalidates all their sessions. An admin cannot suspend themselves. User is looked up by UUID; DB writes use the internal integer ID.

Param Type Description
$request Request β€”
$response Response β€”
$args array<string, string> Route arguments (id).

Returns: Response

unsuspend()

UserController unsuspend()

source

public function unsuspend(Request $request, Response $response, array $args): Response

Removes the suspension from a user, allowing them to log in again. User is looked up by UUID; DB writes use the internal integer ID.

Param Type Description
$request Request β€”
$response Response β€”
$args array<string, string> Route arguments (id).

Returns: Response

createForm()

UserController createForm()

source

public function createForm(Request $request, Response $response): Response

Renders the create-user form.

Param Type Description
$request Request β€”
$response Response β€”

Returns: Response

create()

UserController create()

source

public function create(Request $request, Response $response): Response

Processes the create-user form and creates a new active account. Admin-created accounts are immediately active regardless of the require_activation setting. A UUID is assigned and the user_created audit event is fired.

Param Type Description
$request Request β€”
$response Response β€”

Returns: Response

fetchUserRowById()

UserController fetchUserRowById()

source

private function fetchUserRowById(string $id): ?array

Fetches a single user row by ID (UUID), including all custom profile columns. Returns null when no user with that ID exists.

Param Type Description
$id string User's UUID primary key.

Returns: array<string, mixed>\|null

fetchUser()

UserController fetchUser()

source

private function fetchUser(int|string $id): ?\AuthKit\User

Fetches a user row and wraps it in a User object. Returns null when the user does not exist.

Param Type Description
$id int|string β€”

Returns: \AuthKit\User\|null

paginationRange()

UserController paginationRange()

source

private static function paginationRange(int $current, int $total): array

Computes the visible page numbers for the pagination bar. Always includes the first and last page. Shows a window of Β±2 around the current page. Inserts '...' strings between non-adjacent groups.

Param Type Description
$current int Current page number.
$total int Total number of pages.

Returns: array<int, int\|string>

Dashboard

class β€” rafalmasiarek\DashboardKit\Dashboard Β· source

Entry point factory for building a dashboard application. Usage: Dashboard::create(DIR . '/../', ['app_name' => 'My App'])->run();

Depends on: App, Container

Method Visibility Returns Summary
__construct() private β€” β€”
create() public static self Builds and wires the full Slim application. Supported config keys: app_name (string) Displayed in navbar and page title. Default: 'App'. modules_dir (string) Absolute path to the user modules directory. admin_modules_dir (string) Absolute path to the admin modules directory. Default: {rootDir}/admin_modules. Each subfolder must contain a module.php returning an array with at least 'slug'. Supported keys: slug, title, icon, description, order, navbar, render, handle, routes, settings. 'routes' are registered under /admin/{slug} and protected by admin role. Optional 'settings' key registers a user-level section under /settings/{slug}: title (string) Section title in the settings navigation. order (int) Sort order in settings navigation. Default: 100. templates_dir (string) Absolute path to settings templates; namespace @{slug}-settings. routes (array) Same handler format as module 'routes'. Mounted under /settings/{slug} with AuthMiddleware + CsrfMiddleware only. templates_dir (string) Absolute path to user templates that override built-ins. logs_dir (string) Base directory for log files. Default: {rootDir}/storage/logs. logging (array) Per-channel overrides. Built-in channels: app, audit, error. Each entry: ['path' => 'storage/logs/app.log', 'level' => 'info', 'days' => 30]. Path may be absolute or relative to logs_dir. Extra channels are registered as logger.{name} in the container. Special key request_headers (global or per-channel) injects request headers into every log record for that channel: [] β€” no injection (default) '' β€” all request headers (prefixed req.) string[] β€” specific headers, e.g. ['X-Forwarded-For', 'User-Agent'] Global: 'logging' => ['request_headers' => [...], ...] Per-channel:'logging' => ['audit' => ['request_headers' => [...], ...]] env (string) 'dev' enables Whoops; anything else uses Twig error pages. registration (bool) When true, registers the /register route. Default: false. password_reset (bool) When true, registers /forgot-password and /reset-password routes. Default: false. require_activation (bool) When true, new registrations require email activation before login is allowed. Wires /activate/{token}, login check, and activation email (requires mailer to be configured). Default: false. before_login (callable) Called before credentials are checked on POST /login. Signature: (ServerRequestInterface): ?string Return null to allow, or a string error message to block. Can also be overridden after create() via: $dashboard->getContainer()->set('auth.before_login', callable). before_register (callable) Called before account creation on POST /register. Same signature as before_login. Database connection is read from environment variables: DB_HOST, DB_NAME, DB_USER, DB_PASS If rafalmasiarek/dashboard-kit-scheduler is installed, the scheduler addon is wired automatically β€” no additional configuration needed.
run() public void Runs the application. Call this as the last statement in public/index.php.
getApp() public App Returns the underlying Slim application for advanced customisation. Allows adding middleware or routes after Dashboard::create(): $dashboard->getApp()->add(new MyMiddleware());
on() public self Registers a hook listener for a dashboard event. Supported events and their listener signatures: register (User $user) login (User $user) logout (User $user) password_changed (User $user) email_changed (User $user, string $oldEmail) profile_updated (User $user, array $updatedFields) user_suspended (User $target, User $admin) user_unsuspended (User $target, User $admin) role_changed (User $target, string $oldRole, string $newRole, User $admin) user_updated (User $target, string[] $changedFields, User $admin) user_deleted (User $target, User $admin)
getContainer() public Container Returns the DI container for registering additional services. Returns the concrete PHP-DI Container (not ContainerInterface) so that callers can invoke set() to override or extend bindings before run().
resolveLogChannels() private static array<string, array{path: string, level: string, days: int}> Resolves the logging channel configs, merging user overrides with built-in defaults. Default channels and their defaults: app β€” {logs_dir}/app.log, level: info, days: 30 audit β€” {logs_dir}/audit.log, level: info, days: 90 error β€” {logs_dir}/error.log, level: error, days: 30 A path without a leading slash is treated as relative to $logsDir. Extra channels defined by the user are appended after the built-in ones.
absoluteLogPath() private static string Returns an absolute path for a log file.
normalizeUserFields() private static array<string, array{label: string, type: string, max: int, required: bool, options: array<string, string>}> Normalises the user_fields config array to a consistent shape. Each field entry is resolved to: label (string) type (string, default 'text') max (int, default 255) required (bool, default false) options (array<string,string>, only for type='select') A plain string value is treated as the label with all defaults applied.
buildContainer() private static Container Builds and populates the DI container.
initModuleSchemas() private static void Syncs all module schemas against the live database via SchemaStateManager. Processes module schemas from both public and admin registries, plus any top-level 'schema' key defined in $config (tables that do not belong to any module β€” stored under the pseudo-slug '_bootstrap'). Runs before route registration so all tables are guaranteed to exist on the first request. Uses a hash-based state table (_schema_state) to skip tables whose schema has not changed β€” no INFORMATION_SCHEMA queries on the happy path. 'schema_defaults.timestamps'/'schema_defaults.soft_deletes' in $config set this app's own default for every table that doesn't declare its own 'timestamps'/'soft_deletes' key β€” both default to false, unchanged from today's behavior, unless this app's config opts in. Deliberately a separate top-level key from 'schema' (reserved for the top-level standalone-table definitions handled below) to avoid colliding with it.
runSeeds() private static void Runs declarative seed definitions from the 'seed' config key. Seeds are idempotent β€” each row is skipped when a matching record already exists. Runs after schema sync so all target tables are guaranteed to exist. Uses the raw PDO connection to avoid boot-time interactions with CachingPdo.
registerRoutes() private static void Registers all routes: auth, root redirect, module pages and API endpoints. Routes are placed under the dashboard prefix group (config: dashboard.prefix). The inner admin group uses a separate prefix (config: dashboard.admin_prefix). Public-facing routes (modules with auth_required: false) are also inside the dashboard prefix group, consistent with the overall URL structure.
registerErrorHandlers() private static void Registers error handlers: Whoops for dev mode, Twig error templates for production. Template lookup hierarchy (Symfony-style): errors/404.twig β†’ errors/4xx.twig β†’ errors/error.twig All exceptions are logged to the error channel before rendering.
addRoutesMap() private static void Registers multiple named routes for a single module. Use the routes key for modules that need full CRUD (list, new, edit, delete) instead of a single render/handle pair. Route definition format: 'METHOD /path' => callable Handler signature: (ServerRequestInterface, ResponseInterface, array $args, Twig, PDO, ContainerInterface): ResponseInterface The $module array must have 'slug' (used as the route prefix) and 'routes'. Callers decide the target group: admin modules call this on the admin group, module settings call this on the /settings group β€” the method is group-agnostic. Auth and CSRF are applied at the group level, not per-route.
addModuleRoute() private static void Registers GET and POST routes for a single module. Module callback signatures (5th arg is PSR-11, optional): render: (ServerRequestInterface, ResponseInterface, Twig, PDO, ContainerInterface): ResponseInterface handle: (ServerRequestInterface, ResponseInterface, Twig, PDO, ContainerInterface): ResponseInterface
__construct()

Dashboard __construct()

source

private function __construct(App $app, Container $container, string $logsDir, array $channels)
Param Type Description
$app App Slim application instance.
$container Container PHP-DI container.
$logsDir string Absolute path to the logs directory.
$channels array<string, array{path: string, level: string, days: int}> Resolved channel configs.
create()

Dashboard create()

source

public static function create(string $rootDir, array $config): self

Builds and wires the full Slim application. Supported config keys: app_name (string) Displayed in navbar and page title. Default: 'App'. modules_dir (string) Absolute path to the user modules directory. admin_modules_dir (string) Absolute path to the admin modules directory. Default: {rootDir}/admin_modules. Each subfolder must contain a module.php returning an array with at least 'slug'. Supported keys: slug, title, icon, description, order, navbar, render, handle, routes, settings. 'routes' are registered under /admin/{slug} and protected by admin role. Optional 'settings' key registers a user-level section under /settings/{slug}: title (string) Section title in the settings navigation. order (int) Sort order in settings navigation. Default: 100. templates_dir (string) Absolute path to settings templates; namespace @{slug}-settings. routes (array) Same handler format as module 'routes'. Mounted under /settings/{slug} with AuthMiddleware + CsrfMiddleware only. templates_dir (string) Absolute path to user templates that override built-ins. logs_dir (string) Base directory for log files. Default: {rootDir}/storage/logs. logging (array) Per-channel overrides. Built-in channels: app, audit, error. Each entry: ['path' => 'storage/logs/app.log', 'level' => 'info', 'days' => 30]. Path may be absolute or relative to logs_dir. Extra channels are registered as logger.{name} in the container. Special key request_headers (global or per-channel) injects request headers into every log record for that channel: [] β€” no injection (default) '' β€” all request headers (prefixed req.) string[] β€” specific headers, e.g. ['X-Forwarded-For', 'User-Agent'] Global: 'logging' => ['request_headers' => [...], ...] Per-channel:'logging' => ['audit' => ['request_headers' => [...], ...]] env (string) 'dev' enables Whoops; anything else uses Twig error pages. registration (bool) When true, registers the /register route. Default: false. password_reset (bool) When true, registers /forgot-password and /reset-password routes. Default: false. require_activation (bool) When true, new registrations require email activation before login is allowed. Wires /activate/{token}, login check, and activation email (requires mailer to be configured). Default: false. before_login (callable) Called before credentials are checked on POST /login. Signature: (ServerRequestInterface): ?string Return null to allow, or a string error message to block. Can also be overridden after create() via: $dashboard->getContainer()->set('auth.before_login', callable). before_register (callable) Called before account creation on POST /register. Same signature as before_login. Database connection is read from environment variables: DB_HOST, DB_NAME, DB_USER, DB_PASS If rafalmasiarek/dashboard-kit-scheduler is installed, the scheduler addon is wired automatically β€” no additional configuration needed.

Param Type Description
$rootDir string Absolute path to the application root.
$config array<string, mixed> Optional configuration overrides.

Returns: self

run()

Dashboard run()

source

public function run(): void

Runs the application. Call this as the last statement in public/index.php.

getApp()

Dashboard getApp()

source

public function getApp(): App

Returns the underlying Slim application for advanced customisation. Allows adding middleware or routes after Dashboard::create(): $dashboard->getApp()->add(new MyMiddleware());

Returns: App

on()

Dashboard on()

source

public function on(string $event, callable $listener): self

Registers a hook listener for a dashboard event. Supported events and their listener signatures: register (User $user) login (User $user) logout (User $user) password_changed (User $user) email_changed (User $user, string $oldEmail) profile_updated (User $user, array $updatedFields) user_suspended (User $target, User $admin) user_unsuspended (User $target, User $admin) role_changed (User $target, string $oldRole, string $newRole, User $admin) user_updated (User $target, string[] $changedFields, User $admin) user_deleted (User $target, User $admin)

Param Type Description
$event string Event name.
$listener callable Callback invoked after the event fires.

Returns: self

getContainer()

Dashboard getContainer()

source

public function getContainer(): Container

Returns the DI container for registering additional services. Returns the concrete PHP-DI Container (not ContainerInterface) so that callers can invoke set() to override or extend bindings before run().

Returns: Container

resolveLogChannels()

Dashboard resolveLogChannels()

source

private static function resolveLogChannels(array $raw, string $logsDir): array

Resolves the logging channel configs, merging user overrides with built-in defaults. Default channels and their defaults: app β€” {logs_dir}/app.log, level: info, days: 30 audit β€” {logs_dir}/audit.log, level: info, days: 90 error β€” {logs_dir}/error.log, level: error, days: 30 A path without a leading slash is treated as relative to $logsDir. Extra channels defined by the user are appended after the built-in ones.

Param Type Description
$raw array<string, mixed> User-supplied 'logging' config key.
$logsDir string Resolved absolute logs directory.

Returns: array<string, array{path: string, level: string, days: int}>

absoluteLogPath()

Dashboard absoluteLogPath()

source

private static function absoluteLogPath(string $path, string $logsDir): string

Returns an absolute path for a log file.

Param Type Description
$path string File path (absolute or relative to $logsDir).
$logsDir string Base directory.

Returns: string

normalizeUserFields()

Dashboard normalizeUserFields()

source

private static function normalizeUserFields(array $raw): array

Normalises the user_fields config array to a consistent shape. Each field entry is resolved to: label (string) type (string, default 'text') max (int, default 255) required (bool, default false) options (array<string,string>, only for type='select') A plain string value is treated as the label with all defaults applied.

Param Type Description
$raw array<string, mixed> β€”

Returns: array<string, array{label: string, type: string, max: int, required: bool, options: array<string, string>}>

buildContainer()

Dashboard buildContainer()

source

private static function buildContainer(string $rootDir, array $config, bool $isDev): Container

Builds and populates the DI container.

Param Type Description
$rootDir string β€”
$config array<string, mixed> β€”
$isDev bool Determines default log level: DEBUG in dev, WARNING in prod.

Returns: Container

initModuleSchemas()

Dashboard initModuleSchemas()

source

private static function initModuleSchemas(ContainerInterface $container, array $config): void

Syncs all module schemas against the live database via SchemaStateManager. Processes module schemas from both public and admin registries, plus any top-level 'schema' key defined in $config (tables that do not belong to any module β€” stored under the pseudo-slug '_bootstrap'). Runs before route registration so all tables are guaranteed to exist on the first request. Uses a hash-based state table (_schema_state) to skip tables whose schema has not changed β€” no INFORMATION_SCHEMA queries on the happy path. 'schema_defaults.timestamps'/'schema_defaults.soft_deletes' in $config set this app's own default for every table that doesn't declare its own 'timestamps'/'soft_deletes' key β€” both default to false, unchanged from today's behavior, unless this app's config opts in. Deliberately a separate top-level key from 'schema' (reserved for the top-level standalone-table definitions handled below) to avoid colliding with it.

Param Type Description
$container ContainerInterface PSR-11 container.
$config array<string, mixed> Application config.
runSeeds()

Dashboard runSeeds()

source

private static function runSeeds(ContainerInterface $container, array $config): void

Runs declarative seed definitions from the 'seed' config key. Seeds are idempotent β€” each row is skipped when a matching record already exists. Runs after schema sync so all target tables are guaranteed to exist. Uses the raw PDO connection to avoid boot-time interactions with CachingPdo.

Param Type Description
$container ContainerInterface PSR-11 container.
$config array<string, mixed> Application config.
registerRoutes()

Dashboard registerRoutes()

source

private static function registerRoutes(App $app, ContainerInterface $container, array $config): void

Registers all routes: auth, root redirect, module pages and API endpoints. Routes are placed under the dashboard prefix group (config: dashboard.prefix). The inner admin group uses a separate prefix (config: dashboard.admin_prefix). Public-facing routes (modules with auth_required: false) are also inside the dashboard prefix group, consistent with the overall URL structure.

Param Type Description
$app App β€”
$container ContainerInterface PSR-11 container.
$config array<string, mixed> Resolved application config.
registerErrorHandlers()

Dashboard registerErrorHandlers()

source

private static function registerErrorHandlers(App $app, ContainerInterface $container, bool $isDev): void

Registers error handlers: Whoops for dev mode, Twig error templates for production. Template lookup hierarchy (Symfony-style): errors/404.twig β†’ errors/4xx.twig β†’ errors/error.twig All exceptions are logged to the error channel before rendering.

Param Type Description
$app App β€”
$container ContainerInterface PSR-11 container.
$isDev bool β€”
addRoutesMap()

Dashboard addRoutesMap()

source

private static function addRoutesMap(mixed $target, array $module, ContainerInterface $container): void

Registers multiple named routes for a single module. Use the routes key for modules that need full CRUD (list, new, edit, delete) instead of a single render/handle pair. Route definition format: 'METHOD /path' => callable Handler signature: (ServerRequestInterface, ResponseInterface, array $args, Twig, PDO, ContainerInterface): ResponseInterface The $module array must have 'slug' (used as the route prefix) and 'routes'. Callers decide the target group: admin modules call this on the admin group, module settings call this on the /settings group β€” the method is group-agnostic. Auth and CSRF are applied at the group level, not per-route.

Param Type Description
$target App|RouteCollectorProxy β€”
$module array<string, mixed> β€”
$container ContainerInterface PSR-11 container.
addModuleRoute()

Dashboard addModuleRoute()

source

private static function addModuleRoute(mixed $target, array $module, ContainerInterface $container): void

Registers GET and POST routes for a single module. Module callback signatures (5th arg is PSR-11, optional): render: (ServerRequestInterface, ResponseInterface, Twig, PDO, ContainerInterface): ResponseInterface handle: (ServerRequestInterface, ResponseInterface, Twig, PDO, ContainerInterface): ResponseInterface

Param Type Description
$target App|RouteCollectorProxy β€”
$module array<string, mixed> β€”
$container ContainerInterface PSR-11 container.

ActiveUserExtension

final class β€” rafalmasiarek\DashboardKit\Extension\ActiveUserExtension Β· source

Blocks login when the user's account has not yet been activated via email. Register only when require_activation is enabled: $auth->addLoginExtension(new ActiveUserExtension()); Implements SchemaProviderInterface so that Auth::createSchema() automatically creates the user_activations table required by the activation token flow.

implements LoginExtensionInterface, SchemaProviderInterface

Method Visibility Returns Summary
decide() public LoginDecision Deny login when the active flag is falsy on the user record.
additionalSchema() public list<string> Declares the user_activations table required by the activation token flow.
decide()

ActiveUserExtension decide()

source

public function decide(LoginContext $context): LoginDecision

Deny login when the active flag is falsy on the user record.

Param Type Description
$context LoginContext β€”

Returns: LoginDecision

additionalSchema()

ActiveUserExtension additionalSchema()

source

public function additionalSchema(string $driver): array

Declares the user_activations table required by the activation token flow.

Param Type Description
$driver string PDO driver name.

Returns: list<string>

FormSlotRegistry

final class β€” rafalmasiarek\DashboardKit\Extension\FormSlotRegistry Β· source

Registry for plugin-provided HTML snippets injected into auth forms. Plugins call register() during their addon registration. Each slot is identified by a form name ('login', 'register') and a slot name ('form_fields', 'scripts'). Slots are rendered via the form_slot() Twig function. Content can be a plain HTML string or a callable that returns a string. Callables are evaluated at render time, giving access to PHP runtime state such as $_SESSION, which is useful for conditional injection (e.g. show reCAPTCHA only after a threshold of failed login attempts). Built-in slot names used by dashboard-kit templates: form_fields β€” injected inside the

element, before the submit button. scripts β€” injected in the page's scripts block, outside the .

Property Type Visibility Description
$slots array<string, list<array{content: string|callable(): string, order: int}>> private Registered slot entries keyed by "{form}.{slot}".
Method Visibility Returns Summary
register() public void Register an HTML snippet or a callable for a specific form slot.
render() public string Render all registered snippets for the given form and slot. Entries are sorted by order before concatenation. Callable entries are invoked at render time so they can inspect session or request state.
register()

FormSlotRegistry register()

source

public function register(string $form, string $slot, string|callable $content, int $order): void

Register an HTML snippet or a callable for a specific form slot.

Param Type Description
$form string Form name, e.g. 'login' or 'register'.
$slot string Slot name, e.g. 'form_fields' or 'scripts'.
$content string|callable HTML string or callable returning an HTML string. Callable signature: (): string
$order int Sort order. Lower numbers are rendered first.
render()

FormSlotRegistry render()

source

public function render(string $form, string $slot): string

Render all registered snippets for the given form and slot. Entries are sorted by order before concatenation. Callable entries are invoked at render time so they can inspect session or request state.

Param Type Description
$form string Form name, e.g. 'login'.
$slot string Slot name, e.g. 'form_fields'.

Returns: string β€” Concatenated HTML, safe to output raw.

SettingsSectionRegistry

final class β€” rafalmasiarek\DashboardKit\Extension\SettingsSectionRegistry Β· source

Registry for plugin-provided settings sections. Plugins call register() during their addon registration. The settings template iterates all() to render a navigation list at the bottom of the built-in settings page, linking each section to its own URL. Section definition keys: title (string) Display name shown in the settings navigation. path (string) Absolute URL path, e.g. '/settings/api-tokens'. order (int) Sort order. Lower numbers appear first. Default: 100.

Property Type Visibility Description
$sections array<string, array{title: string, path: string, order: int}> private β€”
Method Visibility Returns Summary
register() public void Register a settings section.
all() public array<string, array{slug: string, title: string, path: string, order: int}> Return all registered sections sorted by order.
register()

SettingsSectionRegistry register()

source

public function register(string $slug, array $definition): void

Register a settings section.

Param Type Description
$slug string Unique identifier for this section.
$definition array<string, mixed> Section definition (title, path, order).
all()

SettingsSectionRegistry all()

source

public function all(): array

Return all registered sections sorted by order.

Returns: array<string, array{slug: string, title: string, path: string, order: int}>

SuspendedUserExtension

final class β€” rafalmasiarek\DashboardKit\Extension\SuspendedUserExtension Β· source

Blocks login when the user's account has been suspended by an admin. Register unconditionally via Auth::addLoginExtension(): $auth->addLoginExtension(new SuspendedUserExtension()); Implements SchemaProviderInterface so that Auth::createSchema() automatically adds the suspended_at column to the users table.

implements LoginExtensionInterface, SchemaProviderInterface

Method Visibility Returns Summary
decide() public LoginDecision Deny login when suspended_at is set on the user record.
additionalSchema() public list<string> Declares the suspended_at column required by this extension.
decide()

SuspendedUserExtension decide()

source

public function decide(LoginContext $context): LoginDecision

Deny login when suspended_at is set on the user record.

Param Type Description
$context LoginContext β€”

Returns: LoginDecision

additionalSchema()

SuspendedUserExtension additionalSchema()

source

public function additionalSchema(string $driver): array

Declares the suspended_at column required by this extension.

Param Type Description
$driver string PDO driver name.

Returns: list<string>

UserActionRegistry

final class β€” rafalmasiarek\DashboardKit\Extension\UserActionRegistry Β· source

Registry for plugin-provided user action buttons in the admin users list. Plugins call register() during their addon registration. The admin users list template iterates all() and renders an additional button per user row, constructing the URL from path_pattern by replacing {id} with the user ID. Action definition keys: label (string) Button label, e.g. 'API Scopes'. path_pattern (string) URL pattern with {id} placeholder, e.g. '/admin/api/users/{id}/scopes'. order (int) Sort order for button positioning. Default: 100.

Property Type Visibility Description
$actions array<string, array{slug: string, label: string, path_pattern: string, order: int}> private β€”
Method Visibility Returns Summary
register() public void Register a user action.
all() public array<string, array{slug: string, label: string, path_pattern: string, order: int}> Return all registered actions sorted by order.
urlFor() public string|null Resolve a URL for a specific user ID by replacing the {id} placeholder.
register()

UserActionRegistry register()

source

public function register(string $slug, array $definition): void

Register a user action.

Param Type Description
$slug string Unique identifier for this action.
$definition array<string, mixed> Action definition (label, path_pattern, order).
all()

UserActionRegistry all()

source

public function all(): array

Return all registered actions sorted by order.

Returns: array<string, array{slug: string, label: string, path_pattern: string, order: int}>

urlFor()

UserActionRegistry urlFor()

source

public function urlFor(string $slug, string $userId): ?string

Resolve a URL for a specific user ID by replacing the {id} placeholder.

Param Type Description
$slug string Action slug.
$userId string User ID to substitute.

Returns: string\|null β€” Resolved URL, or null if the action is not registered.

Flash

class β€” rafalmasiarek\DashboardKit\Flash Β· source

Session-based flash message store. Messages are written to the session and consumed exactly once on the next request. Reading via get() clears the store.

Property Type Visibility Description
$loaded array<string, list<string>>|null private Lazily loaded from session.
Method Visibility Returns Summary
add() public void Adds a flash message of the given type.
get() public array<string, list<string>> Reads and clears all flash messages for the current request.
add()

Flash add()

source

public function add(string $type, string $message): void

Adds a flash message of the given type.

Param Type Description
$type string Bootstrap alert type (success, danger, warning, info).
$message string Human-readable message text.
get()

Flash get()

source

public function get(): array

Reads and clears all flash messages for the current request.

Returns: array<string, list<string>> β€” Keyed by alert type.

FlashAuthHook

final class β€” rafalmasiarek\DashboardKit\Hook\FlashAuthHook Β· source

Bridges AuthKit's low-level lifecycle hooks to dashboard-kit's flash messages. Only overrides hooks with no HookRegistry equivalent. onLogoutExpired fires from deep inside Auth::getUser() when a session token existed but is no longer valid (expired or revoked) β€” a case no controller action ever sees, so HookRegistry (which controllers emit into) can never cover it.

extends AbstractHook

Depends on: Flash

Method Visibility Returns Summary
__construct() public β€” β€”
onLogoutExpired() public void {@inheritDoc}
__construct()

FlashAuthHook __construct()

source

public function __construct(Flash $flash)
Param Type Description
$flash Flash β€”
onLogoutExpired()

FlashAuthHook onLogoutExpired()

source

public function onLogoutExpired(): void

{@inheritDoc}

HookRegistry

class β€” rafalmasiarek\DashboardKit\Hook\HookRegistry Β· source

Lightweight event hook registry. Each event holds exactly one on()-registered listener β€” calling on() replaces any previous registration for that event. This is intentional: it allows application code to override the default flash-message hooks registered by the dashboard without ending up with two flashes firing simultaneously. addListener() is a separate, additive mechanism for events meant to host multiple independent plugins (e.g. mail_sending): every registered listener runs, in registration order, and a listener that throws is caught and logged β€” it never blocks the other listeners or whatever called emit(). Supported events and their argument signatures: register (User $user) register_failed (string $email, string $message) login (User $user) login_failed (string $email) logout (User $user) password_reset_requested (string $email) password_reset_completed (User $user) password_changed (User $user) email_changed (User $user, string $oldEmail) profile_updated (User $user, array $updatedFields) user_created (User $target, User $admin) user_suspended (User $target, User $admin) user_unsuspended (User $target, User $admin) user_updated (User $target, string[] $changedFields, User $admin) user_deleted (User $target, User $admin) mail_sending (MailMessage $message) β€” addListener() only, before delivery mail_sent (MailMessage $message) mail_failed (MailMessage $message, \Throwable $e)

Depends on: LoggerInterface

Property Type Visibility Description
$listeners array<string, callable> private β€”
$pluginListeners array<string, list<callable>> private β€”
Method Visibility Returns Summary
__construct() public β€” β€”
on() public self Registers a listener for the given event, replacing any previous one.
addListener() public self Registers an additional, isolated listener for the given event. Unlike on(), multiple callers can each addListener() for the same event without overwriting one another. A listener that throws is caught and logged by emit() β€” it never blocks the other listeners for this event, nor whatever called emit() in the first place. Intended for plugin-style integrations (e.g. mail_sending) where an addon must never be able to break the core flow it's observing.
emit() public void Calls the listener registered for the given event via on(), if any, then every listener registered via addListener(), in registration order. Exceptions thrown by the on() listener propagate to the caller, as before. Exceptions thrown by an addListener() listener are caught and logged β€” they never propagate.
__construct()

HookRegistry __construct()

source

public function __construct(?LoggerInterface $logger)
Param Type Description
$logger ?LoggerInterface β€”
on()

HookRegistry on()

source

public function on(string $event, callable $listener): self

Registers a listener for the given event, replacing any previous one.

Param Type Description
$event string Event name (see class docblock for supported events).
$listener callable Callback invoked with event-specific arguments.

Returns: self

addListener()

HookRegistry addListener()

source

public function addListener(string $event, callable $listener): self

Registers an additional, isolated listener for the given event. Unlike on(), multiple callers can each addListener() for the same event without overwriting one another. A listener that throws is caught and logged by emit() β€” it never blocks the other listeners for this event, nor whatever called emit() in the first place. Intended for plugin-style integrations (e.g. mail_sending) where an addon must never be able to break the core flow it's observing.

Param Type Description
$event string Event name (see class docblock for supported events).
$listener callable Callback invoked with event-specific arguments.

Returns: self

emit()

HookRegistry emit()

source

public function emit(string $event, mixed $args): void

Calls the listener registered for the given event via on(), if any, then every listener registered via addListener(), in registration order. Exceptions thrown by the on() listener propagate to the caller, as before. Exceptions thrown by an addListener() listener are caught and logged β€” they never propagate.

Param Type Description
$event string Event name.
$args mixed β€”

HttpMessagePicker

final class β€” rafalmasiarek\DashboardKit\Http\HttpMessagePicker Β· source

Converts a symbolic domain error code into an HTTP status + human-readable message pair. Works with any resolver object that exposes: describe(string $code): array{message: string, http?: int} Fallback rules: HTTP: resolver['http'] β†’ 200 (if $ok and code starts with "OK_") β†’ 400 Message: $fallbackMessage β†’ resolver['message'] β†’ $code itself

Method Visibility Returns Summary
pick() public static array{http: int, message: string} Resolve both the HTTP status and the human-readable message at once.
pickHttp() public static int Resolve only the HTTP status code.
pickMessage() public static string Resolve only the human-readable message.
describe() private static array{message: string, http?: int} Duck-typed describe() call with a safe fallback.
pick()

HttpMessagePicker pick()

source

public static function pick(object $resolver, string $code, bool $ok, string $fallbackMessage): array

Resolve both the HTTP status and the human-readable message at once.

Param Type Description
$resolver object Any object with a describe(string): array method.
$code string Symbolic domain code (e.g. "OK_SENT", "EMAIL_INVALID").
$ok bool True when the underlying operation succeeded.
$fallbackMessage string Optional message provided by the caller; takes precedence over the descriptor.

Returns: array{http: int, message: string}

pickHttp()

HttpMessagePicker pickHttp()

source

public static function pickHttp(object $resolver, string $code, bool $ok): int

Resolve only the HTTP status code.

Param Type Description
$resolver object β€”
$code string β€”
$ok bool β€”

Returns: int

pickMessage()

HttpMessagePicker pickMessage()

source

public static function pickMessage(object $resolver, string $code, bool $ok, string $fallbackMessage): string

Resolve only the human-readable message.

Param Type Description
$resolver object β€”
$code string β€”
$ok bool β€”
$fallbackMessage string β€”

Returns: string

describe()

HttpMessagePicker describe()

source

private static function describe(object $resolver, string $code): array

Duck-typed describe() call with a safe fallback.

Param Type Description
$resolver object β€”
$code string β€”

Returns: array{message: string, http?: int}

RequestTimingMiddleware

final class β€” rafalmasiarek\DashboardKit\Http\RequestTimingMiddleware Β· source

PSR-15 middleware that writes one access log entry per request. Uses $_SERVER['REQUEST_TIME_FLOAT'] as the start timestamp β€” set by nginx/Apache when the connection is accepted, before PHP starts executing. The measured duration therefore includes PHP startup, autoloading, container setup, and the full stack. Logged fields: method, path, status, duration_ms β€” always present query.* β€” GET parameters (sanitized) body.* β€” POST/form parameters (sanitized) referer β€” HTTP Referer header when present Sensitive fields (password, token, …) are masked as "". Identity fields (email, login, …) are AES-256-CBC encrypted with APP_KEY. Log output example: [level=info] [channel=app] access method=POST path=/login status=302 duration_ms=45.2 body.email=enc:abc123 body.password= referer=https://example.com req.ip=1.2.3.4 req.id=…

implements MiddlewareInterface

Depends on: LoggerInterface, RequestLogSanitizer

Method Visibility Returns Summary
__construct() public β€” β€”
process() public ResponseInterface Handles the request and logs one access entry after the response is produced.
__construct()

RequestTimingMiddleware __construct()

source

public function __construct(LoggerInterface $logger, RequestLogSanitizer $sanitizer)
Param Type Description
$logger LoggerInterface Logger to write access entries to.
$sanitizer RequestLogSanitizer Sanitizes query/body params before logging.
process()

RequestTimingMiddleware process()

source

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface

Handles the request and logs one access entry after the response is produced.

Param Type Description
$request ServerRequestInterface β€”
$handler RequestHandlerInterface β€”

Returns: ResponseInterface

SafeErrorHandler

final class β€” rafalmasiarek\DashboardKit\Http\SafeErrorHandler Β· source

Slim 4 default error handler with content negotiation and secret redaction. - Returns a JSON envelope for API/CLI/AJAX requests (Accept: application/json, Content-Type: application/json, X-Requested-With: XMLHttpRequest, ?format=json, or CLI SAPI). - Delegates HTML rendering to an optional callable for browser requests. - Falls back to plain text when no HTML renderer is provided or it returns null. - Redacts common secret patterns (tokens, passwords, API keys) from messages and traces. - Shortens absolute file paths when displayErrorDetails is false (production). JSON envelope shape (always present, mirrors JsonHandler for consistency): { "status": "error", "code": , "message": , "data": {}, "errors": [] }

Depends on: ResponseFactoryInterface, LoggerInterface

Property Type Visibility Description
$responseFactory ResponseFactoryInterface private PSR-7 response factory.
$logger LoggerInterface|null private Optional PSR-3 logger for error entries.
$htmlRenderer callable|null private Optional HTML renderer callback. Signature: fn(int $status, string $message, bool $showDetails, ServerRequestInterface $request): ?ResponseInterface Return null to fall through to plain-text fallback.
$whoops object|null private Optional Whoops instance used as the HTML renderer in dev mode. When set, browser requests bypass $htmlRenderer and are served by Whoops. Typed as object to avoid a hard dependency on filp/whoops at the class level (it is a require-dev package β€” may not be installed in production).
Method Visibility Returns Summary
__construct() public β€” β€”
__invoke() public ResponseInterface Invokable Slim default error handler.
statusFromException() private int Map an exception to an HTTP status code.
wantsJson() private bool Heuristics: return true when the client expects a JSON response.
wantsHtml() private bool Heuristics: return true when the client expects an HTML response.
safeTrace() private string[] Build a redacted stack trace; optionally shorten absolute paths.
safeMessage() private string Redact known secret patterns from a string. Covers: ENV-style KEY=VALUE pairs, common query/body param names (token, password, api_key, secret), and Basic-Auth credentials in URIs. Optionally shortens absolute filesystem paths.
shortenPath() private string Collapse absolute filesystem paths to ".../filename.ext".
__construct()

SafeErrorHandler __construct()

source

public function __construct(ResponseFactoryInterface $responseFactory, ?LoggerInterface $logger, ?callable $htmlRenderer, ?object $whoops)
Param Type Description
$responseFactory ResponseFactoryInterface β€”
$logger LoggerInterface|null Optional PSR-3 logger; errors are logged at error/warning level.
$htmlRenderer callable|null Optional HTML renderer for browser requests (Twig templates).
$whoops object|null Optional \Whoops\Run instance; when set, serves HTML via Whoops instead of $htmlRenderer.
__invoke()

SafeErrorHandler __invoke()

source

public function __invoke(ServerRequestInterface $request, Throwable $exception, bool $displayErrorDetails, bool $logErrors, bool $logErrorDetails): ResponseInterface

Invokable Slim default error handler.

Param Type Description
$request ServerRequestInterface β€”
$exception Throwable β€”
$displayErrorDetails bool Whether to include stack traces.
$logErrors bool Whether to log the error.
$logErrorDetails bool Whether to include the exception in log context.

Returns: ResponseInterface

statusFromException()

SafeErrorHandler statusFromException()

source

private function statusFromException(Throwable $e): int

Map an exception to an HTTP status code.

Param Type Description
$e Throwable β€”

Returns: int

wantsJson()

SafeErrorHandler wantsJson()

source

private function wantsJson(ServerRequestInterface $request): bool

Heuristics: return true when the client expects a JSON response.

Param Type Description
$request ServerRequestInterface β€”

Returns: bool

wantsHtml()

SafeErrorHandler wantsHtml()

source

private function wantsHtml(ServerRequestInterface $request): bool

Heuristics: return true when the client expects an HTML response.

Param Type Description
$request ServerRequestInterface β€”

Returns: bool

safeTrace()

SafeErrorHandler safeTrace()

source

private function safeTrace(Throwable $e, bool $shortenPaths): array

Build a redacted stack trace; optionally shorten absolute paths.

Param Type Description
$e Throwable β€”
$shortenPaths bool β€”

Returns: string[]

safeMessage()

SafeErrorHandler safeMessage()

source

private function safeMessage(string $msg, bool $shortenPaths): string

Redact known secret patterns from a string. Covers: ENV-style KEY=VALUE pairs, common query/body param names (token, password, api_key, secret), and Basic-Auth credentials in URIs. Optionally shortens absolute filesystem paths.

Param Type Description
$msg string β€”
$shortenPaths bool β€”

Returns: string

shortenPath()

SafeErrorHandler shortenPath()

source

private function shortenPath(string $s): string

Collapse absolute filesystem paths to ".../filename.ext".

Param Type Description
$s string β€”

Returns: string

AuditLog

class β€” rafalmasiarek\DashboardKit\Log\AuditLog Β· source

Writes structured audit entries for dashboard user and admin actions. Each method logs at INFO level with a consistent context shape: user_id, email β€” always present admin_id, admin_email β€” present for admin-initiated actions extra payload (old_email, fields, old_role, new_role) β€” action-specific The client IP is injected automatically into every log record by RequestHeadersProcessor (req.ip) and does not need to be passed explicitly.

Depends on: LoggerInterface

Method Visibility Returns Summary
__construct() public β€” β€”
register() public void Logs a successful user registration.
login() public void Logs a successful login.
logout() public void Logs a logout.
passwordChanged() public void Logs a password change initiated by the user themselves.
emailChanged() public void Logs an email address change.
profileUpdated() public void Logs a profile fields update.
userSuspended() public void Logs an admin suspending a user account.
userUnsuspended() public void Logs an admin unsuspending a user account.
roleChanged() public void Logs an admin changing a user's role.
userUpdated() public void Logs an admin editing a user's account fields.
userDeleted() public void Logs an admin permanently deleting a user account.
userCreated() public void Logs an admin manually creating a new user account.
activationAttempt() public void Logs an account activation attempt with its outcome.
mailAttempt() public void Logs a mail delivery attempt with its outcome. Logs at INFO on success, ERROR on failure β€” same event name in both cases, so a single grep shows the full picture: sent + failed side by side.
mailOpen() public void Logs a tracking-pixel open event β€” the recipient opened the email.
passwordResetRequested() public void Logs a password reset request (token generated and email dispatched).
passwordResetCompleted() public void Logs a successfully completed password reset.
loginFailed() public void Logs a failed login attempt.
registerFailed() public void Logs a failed registration attempt.
passwordChangeFailed() public void Logs a failed password change attempt.
passwordResetFailed() public void Logs a failed password reset completion (invalid or expired token).
ctx() private array<string, mixed> Builds the base context array for user-initiated actions.
adminCtx() private array<string, mixed> Builds the context array for admin-initiated actions targeting another user.
__construct()

AuditLog __construct()

source

public function __construct(LoggerInterface $logger)
Param Type Description
$logger LoggerInterface PSR-3 logger receiving audit entries.
register()

AuditLog register()

source

public function register(User $user): void

Logs a successful user registration.

Param Type Description
$user User Newly registered user.
login()

AuditLog login()

source

public function login(User $user): void

Logs a successful login.

Param Type Description
$user User Authenticated user.
logout()

AuditLog logout()

source

public function logout(User $user): void

Logs a logout.

Param Type Description
$user User User who logged out.
passwordChanged()

AuditLog passwordChanged()

source

public function passwordChanged(User $user): void

Logs a password change initiated by the user themselves.

Param Type Description
$user User User who changed their password.
emailChanged()

AuditLog emailChanged()

source

public function emailChanged(User $user, string $oldEmail): void

Logs an email address change.

Param Type Description
$user User User whose email changed.
$oldEmail string Previous email address.
profileUpdated()

AuditLog profileUpdated()

source

public function profileUpdated(User $user, array $fields): void

Logs a profile fields update.

Param Type Description
$user User User whose profile was updated.
$fields array<string, mixed> Map of field names that were updated.
userSuspended()

AuditLog userSuspended()

source

public function userSuspended(User $target, User $admin): void

Logs an admin suspending a user account.

Param Type Description
$target User Suspended user.
$admin User Admin who performed the action.
userUnsuspended()

AuditLog userUnsuspended()

source

public function userUnsuspended(User $target, User $admin): void

Logs an admin unsuspending a user account.

Param Type Description
$target User Unsuspended user.
$admin User Admin who performed the action.
roleChanged()

AuditLog roleChanged()

source

public function roleChanged(User $target, string $oldRole, string $newRole, User $admin): void

Logs an admin changing a user's role.

Param Type Description
$target User User whose role changed.
$oldRole string Previous role value.
$newRole string New role value.
$admin User Admin who performed the action.
userUpdated()

AuditLog userUpdated()

source

public function userUpdated(User $target, array $changedFields, User $admin): void

Logs an admin editing a user's account fields.

Param Type Description
$target User User whose account was updated.
$changedFields array<int, string> Names of fields that were modified.
$admin User Admin who performed the action.
userDeleted()

AuditLog userDeleted()

source

public function userDeleted(User $target, User $admin): void

Logs an admin permanently deleting a user account.

Param Type Description
$target User User who was deleted.
$admin User Admin who performed the action.
userCreated()

AuditLog userCreated()

source

public function userCreated(User $target, User $admin): void

Logs an admin manually creating a new user account.

Param Type Description
$target User Created user.
$admin User Admin who performed the action.
activationAttempt()

AuditLog activationAttempt()

source

public function activationAttempt(bool $success, ?int $userId, ?string $email): void

Logs an account activation attempt with its outcome.

Param Type Description
$success bool Whether the token was valid and the account was activated.
$userId int|null Resolved user ID (present on success only).
$email string|null Resolved user email (present on success only).
mailAttempt()

AuditLog mailAttempt()

source

public function mailAttempt(bool $success, string $to, string $subject, ?string $error, ?string $id): void

Logs a mail delivery attempt with its outcome. Logs at INFO on success, ERROR on failure β€” same event name in both cases, so a single grep shows the full picture: sent + failed side by side.

Param Type Description
$success bool Whether the driver accepted the message without throwing.
$to string Recipient email address.
$subject string Email subject line.
$error string|null Driver error message (present on failure only).
$id string|null Caller-supplied correlation id (MailMessage::getCorrelationId()), when set.
mailOpen()

AuditLog mailOpen()

source

public function mailOpen(string $to, string $mailType, ?string $id): void

Logs a tracking-pixel open event β€” the recipient opened the email.

Param Type Description
$to string Recipient email address.
$mailType string Application-defined mail type (e.g. 'activation', 'password-reset').
$id string|null Caller-supplied correlation id carried over from the original send, when set.
passwordResetRequested()

AuditLog passwordResetRequested()

source

public function passwordResetRequested(string $email): void

Logs a password reset request (token generated and email dispatched).

Param Type Description
$email string Email address for which the reset was requested.
passwordResetCompleted()

AuditLog passwordResetCompleted()

source

public function passwordResetCompleted(User $user): void

Logs a successfully completed password reset.

Param Type Description
$user User User who completed the reset.
loginFailed()

AuditLog loginFailed()

source

public function loginFailed(string $email, string $reason): void

Logs a failed login attempt.

Param Type Description
$email string Email address used in the attempt.
$reason string Error message returned by AuthKit.
registerFailed()

AuditLog registerFailed()

source

public function registerFailed(string $email, string $reason): void

Logs a failed registration attempt.

Param Type Description
$email string Email address used in the attempt.
$reason string Error message returned by AuthKit.
passwordChangeFailed()

AuditLog passwordChangeFailed()

source

public function passwordChangeFailed(User $user, string $reason): void

Logs a failed password change attempt.

Param Type Description
$user User User who attempted the change.
$reason string Description of why the change was rejected.
passwordResetFailed()

AuditLog passwordResetFailed()

source

public function passwordResetFailed(?string $email): void

Logs a failed password reset completion (invalid or expired token).

Param Type Description
$email string|null Email address associated with the reset attempt, if known.
ctx()

AuditLog ctx()

source

private function ctx(User $user): array

Builds the base context array for user-initiated actions.

Param Type Description
$user User β€”

Returns: array<string, mixed>

adminCtx()

AuditLog adminCtx()

source

private function adminCtx(User $target, User $admin): array

Builds the context array for admin-initiated actions targeting another user.

Param Type Description
$target User β€”
$admin User β€”

Returns: array<string, mixed>

KvLineFormatter

class β€” rafalmasiarek\DashboardKit\Log\KvLineFormatter Β· source

Formats a Monolog record as a key-value line compatible with log_ship.sh's kv parser. Output format: [YYYY-MM-DD HH:MM:SS] [level=info] [channel=audit] event_name key=val key2=val2 Configure log_ship.conf PARSERS entry: "kv | level=level | msg=message"

implements FormatterInterface

Method Visibility Returns Summary
format() public string Formats a single log record into a kv line.
formatBatch() public string Formats a batch of log records.
escapeValue() private string Escapes a value for safe kv output. Strings with spaces or quotes are double-quoted. Arrays and objects are JSON-encoded.
format()

KvLineFormatter format()

source

public function format(LogRecord $record): string

Formats a single log record into a kv line.

Param Type Description
$record LogRecord β€”

Returns: string

formatBatch()

KvLineFormatter formatBatch()

source

public function formatBatch(array $records): string

Formats a batch of log records.

Param Type Description
$records LogRecord[] β€”

Returns: string

escapeValue()

KvLineFormatter escapeValue()

source

private function escapeValue(mixed $value): string

Escapes a value for safe kv output. Strings with spaces or quotes are double-quoted. Arrays and objects are JSON-encoded.

Param Type Description
$value mixed β€”

Returns: string

LoggerFactory

class β€” rafalmasiarek\DashboardKit\Log\LoggerFactory Β· source

Builds Monolog channel loggers with KvLineFormatter. Log format is compatible with log_ship.sh's kv parser. Recommended PARSERS entry in log_ship.conf: "kv | level=level | msg=message"

Method Visibility Returns Summary
create() public static Logger Creates a channel logger from a resolved channel config. When $cascadeErrorPath is provided a second ERROR+ handler is added to that file, allowing a channel to write high-severity events to a secondary log file as well.
toMonologLevel() public static Level Maps a PSR-3 level string to a Monolog Level enum.
create()

LoggerFactory create()

source

public static function create(string $channel, string $path, string $minLevel, int $maxFiles, ?string $cascadeErrorPath, ?\DateTimeZone $timezone): Logger

Creates a channel logger from a resolved channel config. When $cascadeErrorPath is provided a second ERROR+ handler is added to that file, allowing a channel to write high-severity events to a secondary log file as well.

Param Type Description
$channel string Monolog channel name (used in log lines).
$path string Absolute path to the primary log file.
$minLevel string PSR-3 minimum level constant.
$maxFiles int Number of daily files to retain.
$cascadeErrorPath string|null When set, ERROR+ records are also written here.
$timezone \DateTimeZone|null Timezone for log timestamps; null defaults to UTC.

Returns: Logger

toMonologLevel()

LoggerFactory toMonologLevel()

source

public static function toMonologLevel(string $level): Level

Maps a PSR-3 level string to a Monolog Level enum.

Param Type Description
$level string PSR-3 level constant.

Returns: Level

RequestHeadersProcessor

class β€” rafalmasiarek\DashboardKit\Log\RequestHeadersProcessor Β· source

Monolog processor that injects selected request headers into every log record. Configured once at container build time via $headers; populated per-request by calling boot() from RequestHeadersMiddleware. Configuration options for $headers: [] β€” no header injection (noop) '' β€” dump all request headers (prefixed req.) string[] β€” dump specific headers, e.g. ['User-Agent', 'X-Forwarded-For'] Log output example: req.user_agent="Mozilla/…" req.x_forwarded_for="1.2.3.4"

Depends on: \Closure

Property Type Visibility Description
$context array<string, string> private Context injected into every log record for the current request.
Method Visibility Returns Summary
__construct() public β€” β€”
boot() public void Populates the per-request context from the incoming request. Called once per request by RequestHeadersMiddleware.
__invoke() public LogRecord Invoked by Monolog for every log record. Merges stored context into the record. Log-call context takes priority β€” the processor only fills in keys that are not already present.
headerKey() private string Normalises a header name to a log context key: "X-Forwarded-For" β†’ "req.x_forwarded_for".
__construct()

RequestHeadersProcessor __construct()

source

public function __construct(array|string $headers, ?\Closure $ipResolver)
Param Type Description
$headers array<int, string>|string [] β€” noop '*' β€” all request headers string[] β€” specific header names to include
$ipResolver \Closure|null When provided, called with no arguments and must return string IP. Injected by Dashboard::buildContainer() as a lazy closure that reads from the container-bound RealIpResolver so that container overrides made after create() are always respected. Falls back to REMOTE_ADDR when null (e.g. standalone use without dashboard-kit).
boot()

RequestHeadersProcessor boot()

source

public function boot(ServerRequestInterface $request): void

Populates the per-request context from the incoming request. Called once per request by RequestHeadersMiddleware.

Param Type Description
$request ServerRequestInterface Incoming PSR-7 request.
__invoke()

RequestHeadersProcessor __invoke()

source

public function __invoke(LogRecord $record): LogRecord

Invoked by Monolog for every log record. Merges stored context into the record. Log-call context takes priority β€” the processor only fills in keys that are not already present.

Param Type Description
$record LogRecord β€”

Returns: LogRecord

headerKey()

RequestHeadersProcessor headerKey()

source

private function headerKey(string $name): string

Normalises a header name to a log context key: "X-Forwarded-For" β†’ "req.x_forwarded_for".

Param Type Description
$name string Raw header name.

Returns: string

RequestLogSanitizer

final class β€” rafalmasiarek\DashboardKit\Log\RequestLogSanitizer Β· source

Sanitizes request parameters before writing them to access logs. Rules applied to every field key (case-insensitive prefix/substring match): - Sensitive fields (password, secret, token, …) β†’ replaced with "***" - Identity fields (email, login, username) β†’ AES-256-CBC encrypted with APP_KEY - All other fields β†’ logged as-is Encryption format: "enc:<base64(iv + ciphertext)>" Decrypt with: openssl_decrypt(base64_decode(substr($v, 4)), 'aes-256-cbc', $key, iv...) Security model: safe when log storage and APP_KEY are separated. Passwords are never stored β€” not even encrypted.

Property Type Visibility Description
$key string private readonly Raw binary encryption key (32 bytes).
Method Visibility Returns Summary
__construct() public β€” β€”
sanitize() public array<string, string> Sanitizes a flat key-value array of request parameters. Nested arrays (e.g. from multipart forms) are JSON-encoded before sanitizing.
encrypt() public string Encrypts a plaintext value with AES-256-CBC. Returns "enc:<base64(iv + ciphertext)>" or the original value on failure.
decrypt() public static string|null Decrypts a value previously encrypted by encrypt().
matches() private bool Checks whether any pattern appears as a substring of the subject.
__construct()

RequestLogSanitizer __construct()

source

public function __construct(string $appKey)
Param Type Description
$appKey string Hex-encoded APP_KEY from environment (min 32 hex chars = 16 bytes).
sanitize()

RequestLogSanitizer sanitize()

source

public function sanitize(array $params): array

Sanitizes a flat key-value array of request parameters. Nested arrays (e.g. from multipart forms) are JSON-encoded before sanitizing.

Param Type Description
$params array<string, mixed> Raw request parameters.

Returns: array<string, string> β€” Sanitized parameters safe for logging.

encrypt()

RequestLogSanitizer encrypt()

source

public function encrypt(string $value): string

Encrypts a plaintext value with AES-256-CBC. Returns "enc:<base64(iv + ciphertext)>" or the original value on failure.

Param Type Description
$value string Plaintext to encrypt.

Returns: string

decrypt()

RequestLogSanitizer decrypt()

source

public static function decrypt(string $value, string $appKey): ?string

Decrypts a value previously encrypted by encrypt().

Param Type Description
$value string Encrypted string in "enc:" format.
$appKey string APP_KEY used during encryption.

Returns: string\|null β€” Decrypted plaintext, or null on failure.

matches()

RequestLogSanitizer matches()

source

private function matches(string $subject, array $patterns): bool

Checks whether any pattern appears as a substring of the subject.

Param Type Description
$subject string Lowercase field name.
$patterns string[] List of substrings to match.

Returns: bool

SecretRedactionProcessor

final class β€” rafalmasiarek\DashboardKit\Log\SecretRedactionProcessor Β· source

Monolog processor that redacts registered secret values (see SecretRegistry) from a record's message and context. SecretRegistry::redactValues() is otherwise only applied on the crash-path (the fatal-error shutdown handler and Slim's error handler) β€” any ad-hoc $logger->error('...', ['error' => $e->getMessage()]) call in application code bypasses it entirely. Pushing this processor onto a channel closes that gap for every log call on that channel, with no change required at the call site. Recurses into arrays. A Throwable found in context can't be mutated (its message is immutable), so it is replaced by a small class/message/file/line array with the message redacted, rather than being left to serialize its raw message during formatting.

Method Visibility Returns Summary
__invoke() public LogRecord β€”
redact() private array<array-key, mixed> β€”
__invoke()

SecretRedactionProcessor __invoke()

source

public function __invoke(LogRecord $record): LogRecord
Param Type Description
$record LogRecord β€”

Returns: LogRecord

redact()

SecretRedactionProcessor redact()

source

private function redact(array $value): array
Param Type Description
$value array<array-key, mixed> β€”

Returns: array<array-key, mixed>

StderrLogger

class β€” rafalmasiarek\DashboardKit\Log\StderrLogger Β· source

Minimal PSR-3 logger that writes to stderr. Suitable for Docker and CLI environments where stderr is captured by the container runtime.

extends AbstractLogger

Method Visibility Returns Summary
__construct() public β€” β€”
log() public void Writes a log entry to stderr.
interpolate() private string Replaces {placeholder} tokens in a message with context values.
__construct()

StderrLogger __construct()

source

public function __construct(string $minLevel)
Param Type Description
$minLevel string Minimum log level to output (PSR-3 level constant).
log()

StderrLogger log()

source

public function log( $level, string|Stringable $message, array $context): void

Writes a log entry to stderr.

Param Type Description
$level mixed PSR-3 log level.
$message string|Stringable Log message.
$context array<string, mixed> Additional context values.
interpolate()

StderrLogger interpolate()

source

private function interpolate(string $message, array $context): string

Replaces {placeholder} tokens in a message with context values.

Param Type Description
$message string β€”
$context array<string, mixed> β€”

Returns: string

MailDriverInterface

interface β€” rafalmasiarek\DashboardKit\Mail\Driver\MailDriverInterface Β· source

Contract for outgoing mail transport drivers. Implement this interface to add a new driver (Mailgun, SES, Postmark, …). Register it by returning the new class from the 'driver' match in Dashboard::buildContainer().

Method Visibility Returns Summary
send() public void Delivers a single email message.
send()

MailDriverInterface send()

source

public function send(OutboundMail $mail): void

Delivers a single email message.

Param Type Description
$mail OutboundMail Fully-resolved message to deliver.
Throws When
MailException When delivery fails.

NullDriver

class β€” rafalmasiarek\DashboardKit\Mail\Driver\NullDriver Β· source

Development driver that suppresses all outgoing mail silently. Use driver: 'null' in the mailer config to prevent real emails during local development or testing. Delivery outcomes are recorded by the Mailer via AuditLog β€” no additional logging is done here.

implements MailDriverInterface

Method Visibility Returns Summary
send() public void Delivers a single email message.
send()

NullDriver send()

source

public function send(OutboundMail $mail): void

Delivers a single email message.

Param Type Description
$mail OutboundMail Fully-resolved message to deliver.
Throws When
MailException When delivery fails.

OutboundMail

final class β€” rafalmasiarek\DashboardKit\Mail\Driver\OutboundMail Β· source

Fully-resolved message handed from Mailer to a MailDriverInterface implementation. Built once per send() call from a MailMessage plus its resolved html/text body β€” drivers read properties off this, nothing else.

Depends on: \Closure

Method Visibility Returns Summary
__construct() public β€” β€”
__construct()

OutboundMail __construct()

source

public function __construct(string $fromEmail, string $fromName, string $toEmail, string $toName, string $subject, string $htmlBody, string $textBody, ?string $replyTo, array $attachments, ?string $contentType, ?string $encoding, array $cc, array $bcc, array $embeds, array $customHeaders, ?string $messageId, ?string $inReplyTo, array $references, ?string $envelopeFrom, ?\Closure $onDebugLine)
Param Type Description
$fromEmail string Sender address.
$fromName string Sender display name.
$toEmail string Recipient address.
$toName string Recipient display name (may be empty).
$subject string Email subject line.
$htmlBody string HTML version of the message body, or the full verbatim body when $contentType is set.
$textBody string Plain-text version of the message body.
$replyTo string|null Reply-To address, or null.
$attachments list<array{path: string, name?: string, mimeType?: string}> Files to attach.
$contentType string|null Overrides the normal alternative/mixed content-type construction when set β€” $htmlBody is then sent verbatim as the top-level body.
$encoding string|null Content-Transfer-Encoding paired with $contentType; ignored when $contentType is null.
$cc list<array{email: string, name?: string}> Carbon-copy recipients (header + envelope).
$bcc list<array{email: string, name?: string}> Blind carbon-copy recipients (envelope only, never in headers).
$embeds list<array{path: string, cid: string, name?: string, mimeType?: string}> Inline parts referenced from the HTML body as "cid:...".
$customHeaders array<string, string> Additional raw header lines, name => value.
$messageId string|null Value for the Message-ID header; a driver generates one when null.
$inReplyTo string|null Message-ID this message replies to.
$references list<string> Message-IDs for the References header.
$envelopeFrom string|null SMTP envelope sender (MAIL FROM); defaults to $fromEmail when null.
$onDebugLine (\Closure(string): void)|null Invoked with each raw transport transcript line, when supported by the driver.

SmtpDriver

class β€” rafalmasiarek\DashboardKit\Mail\Driver\SmtpDriver Β· source

Delivers mail via SMTP using rafalmasiarek/mailer's from-scratch SmtpClient. Config keys (passed as $config array): host β€” SMTP server hostname port β€” SMTP port (default: 587) username β€” SMTP username (leave empty to disable auth) password β€” SMTP password encryption β€” 'tls' (STARTTLS), 'ssl' (implicit TLS), or '' (none) dkim β€” optional ['private_key' => PEM string, 'domain' => ..., 'selector' => ..., 'headers' => list (default: From, To, Subject, Date, Message-ID)] Signing is skipped entirely when 'private_key' is empty/absent. tls β€” optional ['verify_peer' => bool (default true), 'ca_file' => string, 'client_cert_file' => string, 'client_key_file' => string, 'client_key_passphrase' => string] dsn β€” optional ['enabled' => bool (default false), 'ret' => 'HDRS'|'FULL', 'notify' => list<'SUCCESS'|'FAILURE'|'DELAY'|'NEVER'>]. Applied to every message when enabled; silently ignored by servers that don't advertise DSN.

implements MailDriverInterface

Depends on: DnsResolverInterface, DeadLetterStoreInterface, TlsOptions, DsnOptions

Property Type Visibility Description
$tls TlsOptions private readonly β€”
$dsn ?DsnOptions private readonly β€”
Method Visibility Returns Summary
__construct() public β€” β€”
send() public void Delivers a single email message.
maybeSign() private string Signs the message with DKIM when config['dkim']['private_key'] is set; returns it unchanged otherwise.
generateMessageId() private static string Generates a Message-ID local part + domain from the sender address.
__construct()

SmtpDriver __construct()

source

public function __construct(array $config, DnsResolverInterface $dns, ?DeadLetterStoreInterface $deadLetterStore)
Param Type Description
$config array<string, mixed> SMTP connection parameters.
$dns DnsResolverInterface Resolver used to pin the connection's target IP.
$deadLetterStore DeadLetterStoreInterface|null Receives a FailedDelivery on any send failure, when set.
send()

SmtpDriver send()

source

public function send(OutboundMail $mail): void

Delivers a single email message.

Param Type Description
$mail OutboundMail Fully-resolved message to deliver.
Throws When
MailException When delivery fails.
maybeSign()

SmtpDriver maybeSign()

source

private function maybeSign(string $rawMessage): string

Signs the message with DKIM when config['dkim']['private_key'] is set; returns it unchanged otherwise.

Param Type Description
$rawMessage string β€”

Returns: string

generateMessageId()

SmtpDriver generateMessageId()

source

private static function generateMessageId(string $fromEmail): string

Generates a Message-ID local part + domain from the sender address.

Param Type Description
$fromEmail string β€”

Returns: string

MailException

class β€” rafalmasiarek\DashboardKit\Mail\Exception\MailException Β· source

Thrown when an outgoing mail cannot be delivered.

extends \RuntimeException

MailMessage

class β€” rafalmasiarek\DashboardKit\Mail\MailMessage Β· source

Fluent builder for a single outgoing email message. Usage: MailMessage::to('user@example.com', 'Jane') ->subject('Activate your account') ->template('emails/activation.twig', ['link' => $url]); Either template() or html() must be set before passing to Mailer::send().

Depends on: RawMimeBody, \Closure

Property Type Visibility Description
$toName string private Recipient display name.
$subject string private Email subject line.
$template string|null private Twig template path relative to configured template directories.
$variables array<string, mixed> private Variables passed to the Twig template.
$bodyHtmlAppends list<array{html: string, priority: int}> private Raw HTML fragments queued via appendBodyHtml(), flattened into the 'extra_body_html' template variable (sorted by priority) on read.
$htmlBody string|null private Explicit HTML body (used when template is not set).
$textBody string|null private Explicit plain-text body (auto-generated from HTML when null).
$replyTo string|null private Reply-To address.
$attachments list<array{path: string, name?: string, mimeType?: string}> private β€”
$rawBody RawMimeBody|null private β€”
$cc list<array{email: string, name?: string}> private β€”
$bcc list<array{email: string, name?: string}> private β€”
$embeds list<array{path: string, cid: string, name?: string, mimeType?: string}> private β€”
$customHeaders array<string, string> private β€”
$messageId string|null private Caller-assigned Message-ID; a driver generates one when null.
$inReplyTo string|null private Message-ID this message replies to.
$references list<string> private β€”
$envelopeFrom string|null private SMTP envelope sender (MAIL FROM); defaults to the Mailer's fromEmail when null.
$onDebugLine \Closure(string): private void|null
$correlationId string|null private Caller-supplied id for audit/log correlation only β€” never touches SMTP/MIME.
Method Visibility Returns Summary
__construct() private β€” β€”
to() public static self Creates a new message addressed to the given recipient.
subject() public self Sets the email subject line.
template() public self Sets the Twig template to render as the message body. The template path is resolved via the configured Twig loaders β€” application templates take precedence over built-in ones.
variable() public self Merges one additional template variable in, without disturbing any others already set β€” the only way to add a variable after template() has already replaced the full set. Lets a Mailer decorator inject its own value (e.g. appending to the 'extra_body_html' list layout.twig renders) into whatever message it's wrapping, without needing to know or preserve the caller's other variables.
appendBodyHtml() public self Queues a raw HTML fragment to render after the main content, via the 'extra_body_html' loop in layout.twig β€” the generic extension point for a Mailer decorator to append something to every email (e.g. an open-tracking pixel) without layout.twig knowing what it is. Fragments render in ascending $priority order (ties keep insertion order) β€” a tracking pixel should use a high priority (e.g. 999) to guarantee it renders after anything else appended.
html() public self Sets an explicit HTML body, bypassing Twig rendering.
text() public self Sets an explicit plain-text body. When not set, Mailer auto-generates one by stripping tags from the HTML body.
replyTo() public self Sets the Reply-To address.
attach() public self Queues a file attachment.
cc() public self Adds a carbon-copy recipient. Call multiple times for multiple recipients.
bcc() public self Adds a blind carbon-copy recipient β€” envelope-only, never appears in any header. Call multiple times for multiple recipients.
embed() public self Queues an inline part referenced from the HTML body as "cid:$cid". Call multiple times for multiple embeds.
customHeader() public self Sets an additional raw header. Call multiple times for multiple headers; a repeated $name overwrites the earlier value.
messageId() public self Sets the Message-ID header value. A driver generates one when unset.
inReplyTo() public self Sets the In-Reply-To header, threading this message to a prior one.
references() public self Sets the References header.
envelopeFrom() public self Sets the SMTP envelope sender (MAIL FROM), independent of the visible From: header. Useful for routing bounces to a dedicated mailbox.
onDebugLine() public self Registers a callback invoked with each raw transport transcript line, when supported by the active driver.
correlationId() public self Sets an opaque id used purely for audit-log and hook correlation (AuditLog::mailAttempt()/mailOpen(), and readable by any hook listener off the message itself) β€” never written to any header or the SMTP envelope. Use messageId() instead when the id must appear on the wire.
rawBody() public self Sets a verbatim MIME body, bypassing template()/html()/text() resolution entirely. Used for content types the normal alternative/mixed structure cannot represent.
getToEmail() public string β€”
getToName() public string β€”
getSubject() public string β€”
getTemplate() public string|null β€”
getVariables() public array<string, mixed> Returns the template variables, with any appendBodyHtml() fragments flattened into 'extra_body_html' (sorted by priority ascending) β€” overwrites a same-named key set via template()'s own $variables.
getHtmlBody() public string|null β€”
getTextBody() public string|null β€”
getReplyTo() public string|null β€”
getAttachments() public list<array{path: string, name?: string, mimeType?: string}> β€”
getRawBody() public RawMimeBody|null β€”
getCc() public list<array{email: string, name?: string}> β€”
getBcc() public list<array{email: string, name?: string}> β€”
getEmbeds() public list<array{path: string, cid: string, name?: string, mimeType?: string}> β€”
getCustomHeaders() public array<string, string> β€”
getMessageId() public string|null β€”
getInReplyTo() public string|null β€”
getReferences() public list<string> β€”
getEnvelopeFrom() public string|null β€”
getDebugLineCallback() public \Closure(string): β€”
getCorrelationId() public string|null β€”
__construct()

MailMessage __construct()

source

private function __construct(string $toEmail)
Param Type Description
$toEmail string Recipient address.
to()

MailMessage to()

source

public static function to(string $email, string $name): self

Creates a new message addressed to the given recipient.

Param Type Description
$email string Recipient email address.
$name string Recipient display name (optional).

Returns: self

subject()

MailMessage subject()

source

public function subject(string $subject): self

Sets the email subject line.

Param Type Description
$subject string β€”

Returns: self

template()

MailMessage template()

source

public function template(string $path, array $variables): self

Sets the Twig template to render as the message body. The template path is resolved via the configured Twig loaders β€” application templates take precedence over built-in ones.

Param Type Description
$path string Template path (e.g. 'emails/activation.twig').
$variables array<string, mixed> Variables passed to the template.

Returns: self

variable()

MailMessage variable()

source

public function variable(string $key, mixed $value): self

Merges one additional template variable in, without disturbing any others already set β€” the only way to add a variable after template() has already replaced the full set. Lets a Mailer decorator inject its own value (e.g. appending to the 'extra_body_html' list layout.twig renders) into whatever message it's wrapping, without needing to know or preserve the caller's other variables.

Param Type Description
$key string β€”
$value mixed β€”

Returns: self

appendBodyHtml()

MailMessage appendBodyHtml()

source

public function appendBodyHtml(string $html, int $priority): self

Queues a raw HTML fragment to render after the main content, via the 'extra_body_html' loop in layout.twig β€” the generic extension point for a Mailer decorator to append something to every email (e.g. an open-tracking pixel) without layout.twig knowing what it is. Fragments render in ascending $priority order (ties keep insertion order) β€” a tracking pixel should use a high priority (e.g. 999) to guarantee it renders after anything else appended.

Param Type Description
$html string β€”
$priority int Lower renders first; default 0.

Returns: self

html()

MailMessage html()

source

public function html(string $html): self

Sets an explicit HTML body, bypassing Twig rendering.

Param Type Description
$html string β€”

Returns: self

text()

MailMessage text()

source

public function text(string $text): self

Sets an explicit plain-text body. When not set, Mailer auto-generates one by stripping tags from the HTML body.

Param Type Description
$text string β€”

Returns: self

replyTo()

MailMessage replyTo()

source

public function replyTo(string $email): self

Sets the Reply-To address.

Param Type Description
$email string β€”

Returns: self

attach()

MailMessage attach()

source

public function attach(string $path, string $name, ?string $mimeType): self

Queues a file attachment.

Param Type Description
$path string Absolute path to the file.
$name string Attachment filename; defaults to the file's own basename.
$mimeType string|null Explicit Content-Type; guessed from the file when null.

Returns: self

cc()

MailMessage cc()

source

public function cc(string $email, string $name): self

Adds a carbon-copy recipient. Call multiple times for multiple recipients.

Param Type Description
$email string β€”
$name string β€”

Returns: self

bcc()

MailMessage bcc()

source

public function bcc(string $email, string $name): self

Adds a blind carbon-copy recipient β€” envelope-only, never appears in any header. Call multiple times for multiple recipients.

Param Type Description
$email string β€”
$name string β€”

Returns: self

embed()

MailMessage embed()

source

public function embed(string $path, string $cid, string $name, ?string $mimeType): self

Queues an inline part referenced from the HTML body as "cid:$cid". Call multiple times for multiple embeds.

Param Type Description
$path string Absolute path to the file.
$cid string Content-ID to reference as "cid:$cid" in the HTML body.
$name string Attachment filename; defaults to the file's own basename.
$mimeType string|null Explicit Content-Type; guessed from the file when null.

Returns: self

customHeader()

MailMessage customHeader()

source

public function customHeader(string $name, string $value): self

Sets an additional raw header. Call multiple times for multiple headers; a repeated $name overwrites the earlier value.

Param Type Description
$name string β€”
$value string β€”

Returns: self

messageId()

MailMessage messageId()

source

public function messageId(string $id): self

Sets the Message-ID header value. A driver generates one when unset.

Param Type Description
$id string Without angle brackets.

Returns: self

inReplyTo()

MailMessage inReplyTo()

source

public function inReplyTo(string $messageId): self

Sets the In-Reply-To header, threading this message to a prior one.

Param Type Description
$messageId string Without angle brackets.

Returns: self

references()

MailMessage references()

source

public function references(array $messageIds): self

Sets the References header.

Param Type Description
$messageIds list<string> Without angle brackets.

Returns: self

envelopeFrom()

MailMessage envelopeFrom()

source

public function envelopeFrom(string $email): self

Sets the SMTP envelope sender (MAIL FROM), independent of the visible From: header. Useful for routing bounces to a dedicated mailbox.

Param Type Description
$email string β€”

Returns: self

onDebugLine()

MailMessage onDebugLine()

source

public function onDebugLine(callable $callback): self

Registers a callback invoked with each raw transport transcript line, when supported by the active driver.

Param Type Description
$callback callable β€”

Returns: self

correlationId()

MailMessage correlationId()

source

public function correlationId(string $id): self

Sets an opaque id used purely for audit-log and hook correlation (AuditLog::mailAttempt()/mailOpen(), and readable by any hook listener off the message itself) β€” never written to any header or the SMTP envelope. Use messageId() instead when the id must appear on the wire.

Param Type Description
$id string β€”

Returns: self

rawBody()

MailMessage rawBody()

source

public function rawBody(RawMimeBody $body): self

Sets a verbatim MIME body, bypassing template()/html()/text() resolution entirely. Used for content types the normal alternative/mixed structure cannot represent.

Param Type Description
$body RawMimeBody β€”

Returns: self

getToEmail()

MailMessage getToEmail()

source

public function getToEmail(): string

Returns: string

getToName()

MailMessage getToName()

source

public function getToName(): string

Returns: string

getSubject()

MailMessage getSubject()

source

public function getSubject(): string

Returns: string

getTemplate()

MailMessage getTemplate()

source

public function getTemplate(): ?string

Returns: string\|null

getVariables()

MailMessage getVariables()

source

public function getVariables(): array

Returns the template variables, with any appendBodyHtml() fragments flattened into 'extra_body_html' (sorted by priority ascending) β€” overwrites a same-named key set via template()'s own $variables.

Returns: array<string, mixed>

getHtmlBody()

MailMessage getHtmlBody()

source

public function getHtmlBody(): ?string

Returns: string\|null

getTextBody()

MailMessage getTextBody()

source

public function getTextBody(): ?string

Returns: string\|null

getReplyTo()

MailMessage getReplyTo()

source

public function getReplyTo(): ?string

Returns: string\|null

getAttachments()

MailMessage getAttachments()

source

public function getAttachments(): array

Returns: list<array{path: string, name?: string, mimeType?: string}>

getRawBody()

MailMessage getRawBody()

source

public function getRawBody(): ?RawMimeBody

Returns: RawMimeBody\|null

getCc()

MailMessage getCc()

source

public function getCc(): array

Returns: list<array{email: string, name?: string}>

getBcc()

MailMessage getBcc()

source

public function getBcc(): array

Returns: list<array{email: string, name?: string}>

getEmbeds()

MailMessage getEmbeds()

source

public function getEmbeds(): array

Returns: list<array{path: string, cid: string, name?: string, mimeType?: string}>

getCustomHeaders()

MailMessage getCustomHeaders()

source

public function getCustomHeaders(): array

Returns: array<string, string>

getMessageId()

MailMessage getMessageId()

source

public function getMessageId(): ?string

Returns: string\|null

getInReplyTo()

MailMessage getInReplyTo()

source

public function getInReplyTo(): ?string

Returns: string\|null

getReferences()

MailMessage getReferences()

source

public function getReferences(): array

Returns: list<string>

getEnvelopeFrom()

MailMessage getEnvelopeFrom()

source

public function getEnvelopeFrom(): ?string

Returns: string\|null

getDebugLineCallback()

MailMessage getDebugLineCallback()

source

public function getDebugLineCallback(): ?\Closure

Returns: \Closure(string): β€” void|null

getCorrelationId()

MailMessage getCorrelationId()

source

public function getCorrelationId(): ?string

Returns: string\|null

Mailer

class β€” rafalmasiarek\DashboardKit\Mail\Mailer Β· source

Sends outgoing emails by rendering Twig templates and delegating to a transport driver. Registered unconditionally in the DI container as Mailer::class. The active driver is determined by config['mailer']['driver']: 'smtp' β€” SmtpDriver (rafalmasiarek/mailer, no PHPMailer dependency) 'null' β€” NullDriver (logs and discards; default when unset) Adding a new driver: implement MailDriverInterface and add a case to the match expression in Dashboard::buildContainer(). Hooks emitted: mail_sending (MailMessage $message) β€” before delivery, via HookRegistry::addListener() only; a listener may still mutate $message (e.g. appendBodyHtml()) and can never block delivery, since a throwing listener is caught and logged by HookRegistry::emit() itself mail_sent (MailMessage $message) β€” after successful delivery mail_failed (MailMessage $message, \Throwable $e) β€” on delivery failure (exception is re-thrown)

implements MailerInterface

Depends on: MailDriverInterface, Twig, HookRegistry, AuditLog

Method Visibility Returns Summary
__construct() public β€” β€”
send() public void Emits 'mail_sending', then renders the message, hands it off to the configured driver, and emits a result hook. Before anything else: emits 'mail_sending' with (MailMessage $message) β€” addListener()-only, so a plugin that wants to mutate $message before delivery (e.g. append a tracking pixel) always runs here, never as a replacement for this class's own MailerInterface binding. On success: emits 'mail_sent' with (MailMessage $message). On failure: emits 'mail_failed' with (MailMessage $message, \Throwable $e), then re-throws.
resolveBody() private array{htmlBody: string, textBody: string} Resolves the final HTML and plain-text bodies from the message. When a Twig template is set it takes precedence over an explicit html() body. The plain-text body is auto-generated from the rendered HTML when not explicitly set.
insertBeforeClosingTag() private static string Inserts $fragment before when present, else before , else appends it verbatim. $html may be a bare content fragment (no document wrapper at all, e.g. the built-in email templates) or a complete document (e.g. an app-built HTML shell) β€” a blind append would land $fragment after in the latter case, which is invalid HTML.
htmlToText() private static string Strips HTML tags and normalises whitespace to produce a plain-text fallback.
__construct()

Mailer __construct()

source

public function __construct(MailDriverInterface $driver, Twig $view, string $fromEmail, string $fromName, HookRegistry $hooks, AuditLog $audit)
Param Type Description
$driver MailDriverInterface Active transport driver.
$view Twig Twig engine used to render email templates.
$fromEmail string Default sender address.
$fromName string Default sender display name.
$hooks HookRegistry Hook registry β€” fires mail_sent / mail_failed events.
$audit AuditLog Audit logger β€” records structured delivery outcomes.
send()

Mailer send()

source

public function send(MailMessage $message): void

Emits 'mail_sending', then renders the message, hands it off to the configured driver, and emits a result hook. Before anything else: emits 'mail_sending' with (MailMessage $message) β€” addListener()-only, so a plugin that wants to mutate $message before delivery (e.g. append a tracking pixel) always runs here, never as a replacement for this class's own MailerInterface binding. On success: emits 'mail_sent' with (MailMessage $message). On failure: emits 'mail_failed' with (MailMessage $message, \Throwable $e), then re-throws.

Param Type Description
$message MailMessage Message to send.
Throws When
MailException When the driver reports a delivery failure.
\InvalidArgumentException When neither template nor html body is set.
resolveBody()

Mailer resolveBody()

source

private function resolveBody(MailMessage $message): array

Resolves the final HTML and plain-text bodies from the message. When a Twig template is set it takes precedence over an explicit html() body. The plain-text body is auto-generated from the rendered HTML when not explicitly set.

Param Type Description
$message MailMessage β€”

Returns: array{htmlBody: string, textBody: string} β€” [htmlBody, textBody]

Throws When
\InvalidArgumentException When neither template nor html body is provided.
insertBeforeClosingTag()

Mailer insertBeforeClosingTag()

source

private static function insertBeforeClosingTag(string $html, string $fragment): string

Inserts $fragment before when present, else before , else appends it verbatim. $html may be a bare content fragment (no document wrapper at all, e.g. the built-in email templates) or a complete document (e.g. an app-built HTML shell) β€” a blind append would land $fragment after in the latter case, which is invalid HTML.

Param Type Description
$html string β€”
$fragment string β€”

Returns: string

htmlToText()

Mailer htmlToText()

source

private static function htmlToText(string $html): string

Strips HTML tags and normalises whitespace to produce a plain-text fallback.

Param Type Description
$html string β€”

Returns: string

MailerInterface

interface β€” rafalmasiarek\DashboardKit\Mail\MailerInterface Β· source

Sends outgoing emails rendered from a MailMessage. Bound in the DI container as Mailer::class (the concrete implementation) and MailerInterface::class (resolved to the same instance). Consumers should type-hint the interface, not Mailer directly, so an app can substitute a decorator (e.g. one that adds open-tracking) by overriding the MailerInterface::class binding after Dashboard::create() β€” the same pattern already used for RealIpResolver/GeoIpDriverInterface.

Method Visibility Returns Summary
send() public void Renders the message and hands it off to the configured transport driver. On success: emits 'mail_sent' with (MailMessage $message). On failure: emits 'mail_failed' with (MailMessage $message, \Throwable $e), then re-throws.
send()

MailerInterface send()

source

public function send(MailMessage $message): void

Renders the message and hands it off to the configured transport driver. On success: emits 'mail_sent' with (MailMessage $message). On failure: emits 'mail_failed' with (MailMessage $message, \Throwable $e), then re-throws.

Param Type Description
$message MailMessage Message to send.
Throws When
Exception\MailException When the driver reports a delivery failure.
\InvalidArgumentException When neither template nor html body is set.

AuthMiddleware

class β€” rafalmasiarek\DashboardKit\Middleware\AuthMiddleware Β· source

Redirects unauthenticated requests to the login page.

implements MiddlewareInterface

Depends on: Auth

Method Visibility Returns Summary
__construct() public β€” β€”
process() public ResponseInterface Passes the request through if authenticated, redirects to /login otherwise. Appends a ?from= query parameter so the login controller can redirect back to the original URL after successful authentication.
__construct()

AuthMiddleware __construct()

source

public function __construct(Auth $auth, string $dashboardUrlPrefix)
Param Type Description
$auth Auth AuthKit authentication service.
$dashboardUrlPrefix string Full URL prefix for the dashboard (e.g. '/api/admin'). Prepended to the /login redirect target.
process()

AuthMiddleware process()

source

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface

Passes the request through if authenticated, redirects to /login otherwise. Appends a ?from= query parameter so the login controller can redirect back to the original URL after successful authentication.

Param Type Description
$request ServerRequestInterface Request instance.
$handler RequestHandlerInterface Next handler in the chain.

Returns: ResponseInterface

CsrfMiddleware

class β€” rafalmasiarek\DashboardKit\Middleware\CsrfMiddleware Β· source

Validates CSRF tokens on state-changing HTTP methods. Expects a hidden field named _csrf in the request body. The token is generated in Twig templates via {{ csrf.generate() }} using the 'csrf' Twig global. GET and HEAD requests are passed through without checking.

implements MiddlewareInterface

Depends on: Csrf, RealIpResolver

Method Visibility Returns Summary
__construct() public β€” β€”
process() public ResponseInterface Validates the _csrf field for POST/PUT/PATCH/DELETE requests. For form submissions reads _csrf + _csrf_container from the parsed body. For JSON fetch requests (Content-Type: application/json) falls back to reading the same fields from the raw JSON body, also accepting the legacy csrf_token field name used by admin-requests.js. Returns HTTP 419 when the token is missing or invalid.
__construct()

CsrfMiddleware __construct()

source

public function __construct(Csrf $csrf, RealIpResolver $ipResolver)
Param Type Description
$csrf Csrf CSRF token service.
$ipResolver RealIpResolver Resolves the real client IP behind trusted proxies (e.g. Cloudflare), so bind_ip validates against the actual visitor rather than an edge/proxy address.
process()

CsrfMiddleware process()

source

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface

Validates the _csrf field for POST/PUT/PATCH/DELETE requests. For form submissions reads _csrf + _csrf_container from the parsed body. For JSON fetch requests (Content-Type: application/json) falls back to reading the same fields from the raw JSON body, also accepting the legacy csrf_token field name used by admin-requests.js. Returns HTTP 419 when the token is missing or invalid.

Param Type Description
$request ServerRequestInterface Incoming request.
$handler RequestHandlerInterface Next middleware in chain.

Returns: ResponseInterface

RequestHeadersMiddleware

class β€” rafalmasiarek\DashboardKit\Middleware\RequestHeadersMiddleware Β· source

PSR-15 middleware that boots all registered RequestHeadersProcessor instances. Added to the Slim stack automatically by Dashboard when any logging channel has request_headers configured (globally or per-channel).

implements MiddlewareInterface

Depends on: RequestHeadersProcessor

Property Type Visibility Description
$processors RequestHeadersProcessor[] private β€”
Method Visibility Returns Summary
__construct() public β€” β€”
process() public ResponseInterface Boots all processors with the current request then passes control downstream.
__construct()

RequestHeadersMiddleware __construct()

source

public function __construct(RequestHeadersProcessor $processors)
Param Type Description
$processors RequestHeadersProcessor β€”
process()

RequestHeadersMiddleware process()

source

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface

Boots all processors with the current request then passes control downstream.

Param Type Description
$request ServerRequestInterface PSR-7 server request.
$handler RequestHandlerInterface Next middleware or route handler.

Returns: ResponseInterface

RoleMiddleware

class β€” rafalmasiarek\DashboardKit\Middleware\RoleMiddleware Β· source

Enforces role-based access on top of authentication. Must be used after AuthMiddleware β€” assumes the user is already logged in. Redirects to / with 403 status when the user's role is not in the allowed list. Module usage: 'auth_required' => 'admin' 'auth_required' => ['admin', 'editor']

implements MiddlewareInterface

Depends on: ContainerInterface

Method Visibility Returns Summary
__construct() public β€” β€”
process() public ResponseInterface Passes the request through if the current user's role is in the allowed list.
__construct()

RoleMiddleware __construct()

source

public function __construct(ContainerInterface $container, array $roles, string $dashboardUrlPrefix)
Param Type Description
$container ContainerInterface PSR-11 container (Auth resolved lazily per request).
$roles string[] Allowed role values.
$dashboardUrlPrefix string Full URL prefix for dashboard routes (base_path + dashboard.prefix).
process()

RoleMiddleware process()

source

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface

Passes the request through if the current user's role is in the allowed list.

Param Type Description
$request ServerRequestInterface β€”
$handler RequestHandlerInterface β€”

Returns: ResponseInterface

SessionMiddleware

class β€” rafalmasiarek\DashboardKit\Middleware\SessionMiddleware Β· source

Ensures PHP session is started for every request. Must run before CsrfMiddleware so that $_SESSION is available when CSRF tokens are validated or generated.

implements MiddlewareInterface

Method Visibility Returns Summary
process() public ResponseInterface Starts the PHP session if not already active.
process()

SessionMiddleware process()

source

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface

Starts the PHP session if not already active.

Param Type Description
$request ServerRequestInterface Incoming request.
$handler RequestHandlerInterface Next middleware in chain.

Returns: ResponseInterface

Collection

final class β€” rafalmasiarek\DashboardKit\Model\Collection Β· source

Typed iterable wrapper for a list of Model instances or arbitrary values. Returned by Model::all(), Model::where()->get(), and relation methods. Implements standard PHP collection interfaces so it works in foreach, count(), and array-access contexts without casting to a plain array.

implements \Countable, \IteratorAggregate, \ArrayAccess

Method Visibility Returns Summary
__construct() public β€” β€”
count() public int Returns the number of items in the collection.
getIterator() public \ArrayIterator<int, T> Returns an iterator over the items.
offsetExists() public bool β€”
offsetGet() public T β€”
offsetSet() public void β€”
offsetUnset() public void β€”
first() public T|null Returns the first item, or null when the collection is empty.
last() public T|null Returns the last item, or null when the collection is empty.
isEmpty() public bool Returns true when the collection contains no items.
toArray() public list<mixed> Converts every Model item to an associative array; passes other values through.
filter() public static Returns a new collection containing only items for which the callback returns true. The resulting list is re-indexed starting from 0.
map() public static Applies the callback to every item and returns a new collection of the results.
pluck() public list<mixed> Extracts a single attribute from each item. Calls ->get($key) on Model instances; reads $item[$key] from arrays.
__construct()

Collection __construct()

source

public function __construct(array $items)
Param Type Description
$items list<T> Items in this collection.
count()

Collection count()

source

public function count(): int

Returns the number of items in the collection.

Returns: int

getIterator()

Collection getIterator()

source

public function getIterator(): \ArrayIterator

Returns an iterator over the items.

Returns: \ArrayIterator<int, T>

offsetExists()

Collection offsetExists()

source

public function offsetExists(mixed $offset): bool
Param Type Description
$offset int β€”

Returns: bool

offsetGet()

Collection offsetGet()

source

public function offsetGet(mixed $offset): mixed
Param Type Description
$offset int β€”

Returns: T

offsetSet()

Collection offsetSet()

source

public function offsetSet(mixed $offset, mixed $value): void
Param Type Description
$offset int|null β€”
$value T β€”
offsetUnset()

Collection offsetUnset()

source

public function offsetUnset(mixed $offset): void
Param Type Description
$offset int β€”
first()

Collection first()

source

public function first(): mixed

Returns the first item, or null when the collection is empty.

Returns: T\|null

last()

Collection last()

source

public function last(): mixed

Returns the last item, or null when the collection is empty.

Returns: T\|null

isEmpty()

Collection isEmpty()

source

public function isEmpty(): bool

Returns true when the collection contains no items.

Returns: bool

toArray()

Collection toArray()

source

public function toArray(): array

Converts every Model item to an associative array; passes other values through.

Returns: list<mixed>

filter()

Collection filter()

source

public function filter(callable $callback): static

Returns a new collection containing only items for which the callback returns true. The resulting list is re-indexed starting from 0.

Param Type Description
$callback callable β€”

Returns: static

map()

Collection map()

source

public function map(callable $callback): static

Applies the callback to every item and returns a new collection of the results.

Param Type Description
$callback callable β€”

Returns: static

pluck()

Collection pluck()

source

public function pluck(string $key): array

Extracts a single attribute from each item. Calls ->get($key) on Model instances; reads $item[$key] from arrays.

Param Type Description
$key string Attribute or array key to extract.

Returns: list<mixed>

Model

abstract class β€” rafalmasiarek\DashboardKit\Model\Model Β· source

Abstract base class for all application database models. Wire the PDO connection once at boot time via setConnectionResolver() β€” typically called inside Dashboard::create() so models automatically use CachingPdo and benefit from transparent SELECT caching. Each concrete model must declare at minimum: protected static string $table = 'my_table'; Type casting is declared via: protected static array $casts = ['active' => 'bool', 'created_at' => 'datetime']; Supported cast types: int, float, bool, string, datetime (β†’ DateTimeImmutable), json, array (both decode JSON to associative array). Soft delete is not GDPR/RODO erasure β€” the row still exists physically. Use forceDelete() for real erasure, or anonymize columns if the row must be kept. For retention-based cleanup of trashed rows, see prunable()/prune().

Depends on: \Closure, PDO, ClockInterface

Property Type Visibility Description
$table string protected static Database table name. Must be overridden in every concrete model.
$primaryKey string protected static Primary key column name.
$casts array<string, 'int'|'float'|'bool'|'string'|'datetime'|'json'|'array'> protected static Column type casts applied when reading attribute values.
$timestamps bool protected static Whether save() maintains created_at/updated_at automatically. On by default.
$createdAtColumn string protected static Column written on insert and on every subsequent save().
$updatedAtColumn string protected static Column written on every save(), including insert.
$softDeletes bool protected static Whether delete() soft-deletes (sets deletedAtColumn) instead of removing the row. Off by default.
$deletedAtColumn string protected static Column set by a soft delete and checked by find()/all()/where() to hide trashed rows.
$connectionResolver \Closure|null private static Lazy connection factory. Called once; result is cached in $resolved.
$resolved PDO|null private static Resolved PDO instance cached after the first db() call.
$clock ClockInterface|null private static Clock used for created_at/updated_at and any other "now" computed by Model/QueryBuilder. Defaults to SystemClock (plain system time) until an app calls setClock() β€” e.g. to wire in its own timezone-aware clock.
$attributes array<string, mixed> protected Raw attribute values as returned by the database driver.
$exists bool protected Whether this instance corresponds to a persisted database row.
Method Visibility Returns Summary
setConnectionResolver() public static void Registers the PDO factory used by all model classes. Pass a closure rather than the PDO instance directly so that the connection is not resolved until the first model query β€” important when Dashboard::create() wires models before the container is fully warm.
setClock() public static void Registers the clock used by Model/QueryBuilder for "now" β€” e.g. an app's own timezone-aware clock, overriding the plain-system-time default.
getClock() public static ClockInterface Returns the active clock, defaulting to SystemClock when setClock() was never called. Public so code outside the Model hierarchy (e.g. an addon repository with no DI of its own) can read "now" from the same single source as Model/QueryBuilder.
getTable() public static string Returns the logical table name declared by the concrete model. Used by QueryBuilder to build SQL without accessing protected statics directly.
db() protected static PDO Returns the active PDO connection, resolving it on the first call.
fromRow() public static static Creates a model instance from a raw database row without triggering a query.
find() public static static|null Finds a single model by primary key. Hidden when soft-deleted β€” use withTrashed() to look up a possibly-trashed row by id.
all() public static Collection Returns all non-trashed rows in the table as a Collection of model instances.
where() public static QueryBuilder Starts a fluent WHERE chain for the model's table. When called with two arguments, '=' is assumed as the operator: Model::where('active', 1) β†’ WHERE active = ? Model::where('role', '!=', 'user') β†’ WHERE role != ?
withTrashed() public static QueryBuilder Starts a query that also matches soft-deleted rows.
onlyTrashed() public static QueryBuilder Starts a query that matches only soft-deleted rows.
usesSoftDeletes() public static bool Whether this model soft-deletes instead of removing rows outright.
getDeletedAtColumn() public static string Column name soft-deletes are written to.
newQuery() protected static QueryBuilder Builds a fresh, unconditioned query for this model's table.
on() public static QueryBuilder Starts a query against an arbitrary table with no dedicated model class β€” for tables whose name is only known at runtime (e.g. one table per admin-defined content type). Rows come back as plain arrays, not model instances, and soft deletes are not applied.
whereIn() public static QueryBuilder Starts a fluent WHERE column IN (...) chain for the model's table.
whereNotIn() public static QueryBuilder Starts a fluent WHERE column NOT IN (...) chain for the model's table.
whereRaw() public static QueryBuilder Starts a fluent WHERE chain for the model's table with a raw SQL fragment as the first condition β€” see QueryBuilder::whereRaw().
transaction() public static T Runs $callback inside a transaction, committing on normal return and rolling back if it throws.
upsert() public static bool Inserts a row, or updates it in one atomic statement when a row already matches $uniqueBy (MySQL: ON DUPLICATE KEY UPDATE; SQLite: ON CONFLICT DO UPDATE) β€” safe under concurrent writers, unlike a SELECT-then-branch. createdAtColumn is never touched on the update branch.
insertOrIgnore() public static bool Inserts a row, silently doing nothing if it would violate a unique constraint (MySQL: INSERT IGNORE; SQLite: INSERT OR IGNORE; PostgreSQL: ON CONFLICT DO NOTHING) β€” idempotent insert, not an upsert; an existing row is never modified.
now() protected static string Current timestamp in the format written to created_at/updated_at columns.
create() public static static Inserts a new row and returns the resulting model instance.
__get() public mixed Reads an attribute value with type casting applied.
__set() public void Sets an attribute value.
__isset() public bool Returns true when the attribute exists in the current row (even if null).
get() public mixed Returns the cast value for a given attribute key.
set() public void Stores a raw value for the given attribute key.
fill() public static Sets multiple attributes at once and returns $this for chaining.
toArray() public array<string, mixed> Returns all attributes as an associative array with casts applied.
save() public bool Persists the model to the database. Issues INSERT when $exists is false; UPDATE when $exists is true. On successful INSERT, sets $exists = true and stores the last-insert-id when no primary-key value was provided in attributes. When $timestamps is enabled, createdAtColumn is set on insert (unless already present) and updatedAtColumn is set on every save.
delete() public bool Removes the row. Soft-deletes (sets deletedAtColumn, keeps the row) when $softDeletes is enabled; otherwise deletes it outright.
forceDelete() public bool Deletes the row outright, bypassing soft deletes.
restore() public bool Clears a soft delete, making the row visible to normal queries again.
trashed() public bool Whether this instance is currently soft-deleted.
prunable() protected static QueryBuilder|null Query selecting rows eligible for prune(). Null = pruning disabled. Override per model, e.g. return static::trashedOlderThan('-30 days').
pruning() protected void Called on each row before prune() force-deletes it. Override to clean up owned resources (files, cache, ...).
prune() public static int Force-deletes every row matched by prunable(), chunked, calling pruning() on each first. Call from a scheduled task, not per-request.
trashedOlderThan() protected static QueryBuilder Soft-deleted rows older than $interval (DateTime::modify() format, e.g. '-30 days').
cast() protected mixed Applies the declared cast for a column to its raw DB value.
encodeForPersistence() private array<string, mixed> Attributes ready to bind to a PDO statement: json/array-cast columns holding a non-string value (array/object) are json_encode()'d; everything else passes through unchanged. Does not mutate $this->attributes.
hasMany() protected Collection Loads all related models where $foreignKey on the related table equals this model's $localKey.
belongsTo() protected object|null Loads the single related model whose $ownerKey matches this model's $foreignKey value.
setConnectionResolver()

Model setConnectionResolver()

source

public static function setConnectionResolver(\Closure $resolver): void

Registers the PDO factory used by all model classes. Pass a closure rather than the PDO instance directly so that the connection is not resolved until the first model query β€” important when Dashboard::create() wires models before the container is fully warm.

Param Type Description
$resolver \Closure β€”
setClock()

Model setClock()

source

public static function setClock(ClockInterface $clock): void

Registers the clock used by Model/QueryBuilder for "now" β€” e.g. an app's own timezone-aware clock, overriding the plain-system-time default.

Param Type Description
$clock ClockInterface β€”
getClock()

Model getClock()

source

public static function getClock(): ClockInterface

Returns the active clock, defaulting to SystemClock when setClock() was never called. Public so code outside the Model hierarchy (e.g. an addon repository with no DI of its own) can read "now" from the same single source as Model/QueryBuilder.

Returns: ClockInterface

getTable()

Model getTable()

source

public static function getTable(): string

Returns the logical table name declared by the concrete model. Used by QueryBuilder to build SQL without accessing protected statics directly.

Returns: string

db()

Model db()

source

protected static function db(): PDO

Returns the active PDO connection, resolving it on the first call.

Returns: PDO

Throws When
\RuntimeException When no resolver has been registered.
fromRow()

Model fromRow()

source

public static function fromRow(array $row): static

Creates a model instance from a raw database row without triggering a query.

Param Type Description
$row array<string, mixed> Column-value map from PDO::FETCH_ASSOC.

Returns: static

find()

Model find()

source

public static function find(int|string $id): ?static

Finds a single model by primary key. Hidden when soft-deleted β€” use withTrashed() to look up a possibly-trashed row by id.

Param Type Description
$id int|string Primary key value.

Returns: static\|null β€” Null when no matching (non-trashed) row exists.

all()

Model all()

source

public static function all(): Collection

Returns all non-trashed rows in the table as a Collection of model instances.

Returns: Collection

where()

Model where()

source

public static function where(string $column, mixed $operatorOrValue, mixed $value): QueryBuilder

Starts a fluent WHERE chain for the model's table. When called with two arguments, '=' is assumed as the operator: Model::where('active', 1) β†’ WHERE active = ? Model::where('role', '!=', 'user') β†’ WHERE role != ?

Param Type Description
$column string Column name (not user input).
$operatorOrValue mixed Operator string when $value is provided; bound value otherwise.
$value mixed Bound value when an explicit operator is given.

Returns: QueryBuilder

withTrashed()

Model withTrashed()

source

public static function withTrashed(): QueryBuilder

Starts a query that also matches soft-deleted rows.

Returns: QueryBuilder

onlyTrashed()

Model onlyTrashed()

source

public static function onlyTrashed(): QueryBuilder

Starts a query that matches only soft-deleted rows.

Returns: QueryBuilder

usesSoftDeletes()

Model usesSoftDeletes()

source

public static function usesSoftDeletes(): bool

Whether this model soft-deletes instead of removing rows outright.

Returns: bool

getDeletedAtColumn()

Model getDeletedAtColumn()

source

public static function getDeletedAtColumn(): string

Column name soft-deletes are written to.

Returns: string

newQuery()

Model newQuery()

source

protected static function newQuery(): QueryBuilder

Builds a fresh, unconditioned query for this model's table.

Returns: QueryBuilder

on()

Model on()

source

public static function on(string $table): QueryBuilder

Starts a query against an arbitrary table with no dedicated model class β€” for tables whose name is only known at runtime (e.g. one table per admin-defined content type). Rows come back as plain arrays, not model instances, and soft deletes are not applied.

Param Type Description
$table string β€”

Returns: QueryBuilder

whereIn()

Model whereIn()

source

public static function whereIn(string $column, array $values): QueryBuilder

Starts a fluent WHERE column IN (...) chain for the model's table.

Param Type Description
$column string Column name (not user input).
$values list<mixed> β€”

Returns: QueryBuilder

whereNotIn()

Model whereNotIn()

source

public static function whereNotIn(string $column, array $values): QueryBuilder

Starts a fluent WHERE column NOT IN (...) chain for the model's table.

Param Type Description
$column string Column name (not user input).
$values list<mixed> β€”

Returns: QueryBuilder

whereRaw()

Model whereRaw()

source

public static function whereRaw(string $sql, array $params): QueryBuilder

Starts a fluent WHERE chain for the model's table with a raw SQL fragment as the first condition β€” see QueryBuilder::whereRaw().

Param Type Description
$sql string Raw SQL fragment.
$params list<mixed> Bound values for the '?' placeholders in $sql, in order.

Returns: QueryBuilder

transaction()

Model transaction()

source

public static function transaction(callable $callback): mixed

Runs $callback inside a transaction, committing on normal return and rolling back if it throws.

Param Type Description
$callback callable β€”

Returns: T

upsert()

Model upsert()

source

public static function upsert(array $attributes, array $uniqueBy, ?array $updateColumns): bool

Inserts a row, or updates it in one atomic statement when a row already matches $uniqueBy (MySQL: ON DUPLICATE KEY UPDATE; SQLite: ON CONFLICT DO UPDATE) β€” safe under concurrent writers, unlike a SELECT-then-branch. createdAtColumn is never touched on the update branch.

Param Type Description
$attributes array<string, mixed> Column-value pairs to insert.
$uniqueBy list<string> Columns identifying an existing row (unique/PK).
$updateColumns list<string>|null Columns to refresh on conflict. Defaults to every column except $uniqueBy and createdAtColumn.

Returns: bool

insertOrIgnore()

Model insertOrIgnore()

source

public static function insertOrIgnore(array $attributes): bool

Inserts a row, silently doing nothing if it would violate a unique constraint (MySQL: INSERT IGNORE; SQLite: INSERT OR IGNORE; PostgreSQL: ON CONFLICT DO NOTHING) β€” idempotent insert, not an upsert; an existing row is never modified.

Param Type Description
$attributes array<string, mixed> Column-value pairs to insert.

Returns: bool

now()

Model now()

source

protected static function now(): string

Current timestamp in the format written to created_at/updated_at columns.

Returns: string

create()

Model create()

source

public static function create(array $attributes): static

Inserts a new row and returns the resulting model instance.

Param Type Description
$attributes array<string, mixed> Column-value pairs to insert.

Returns: static

__get()

Model __get()

source

public function __get(string $name): mixed

Reads an attribute value with type casting applied.

Param Type Description
$name string β€”

Returns: mixed

__set()

Model __set()

source

public function __set(string $name, mixed $value): void

Sets an attribute value.

Param Type Description
$name string β€”
$value mixed β€”
__isset()

Model __isset()

source

public function __isset(string $name): bool

Returns true when the attribute exists in the current row (even if null).

Param Type Description
$name string β€”

Returns: bool

get()

Model get()

source

public function get(string $key): mixed

Returns the cast value for a given attribute key.

Param Type Description
$key string β€”

Returns: mixed β€” Null when the key does not exist in attributes.

set()

Model set()

source

public function set(string $key, mixed $value): void

Stores a raw value for the given attribute key.

Param Type Description
$key string β€”
$value mixed β€”
fill()

Model fill()

source

public function fill(array $attributes): static

Sets multiple attributes at once and returns $this for chaining.

Param Type Description
$attributes array<string, mixed> β€”

Returns: static

toArray()

Model toArray()

source

public function toArray(): array

Returns all attributes as an associative array with casts applied.

Returns: array<string, mixed>

save()

Model save()

source

public function save(): bool

Persists the model to the database. Issues INSERT when $exists is false; UPDATE when $exists is true. On successful INSERT, sets $exists = true and stores the last-insert-id when no primary-key value was provided in attributes. When $timestamps is enabled, createdAtColumn is set on insert (unless already present) and updatedAtColumn is set on every save.

Returns: bool β€” True on success.

delete()

Model delete()

source

public function delete(): bool

Removes the row. Soft-deletes (sets deletedAtColumn, keeps the row) when $softDeletes is enabled; otherwise deletes it outright.

Returns: bool β€” False when the instance has not been persisted yet.

forceDelete()

Model forceDelete()

source

public function forceDelete(): bool

Deletes the row outright, bypassing soft deletes.

Returns: bool β€” False when the instance has not been persisted yet.

restore()

Model restore()

source

public function restore(): bool

Clears a soft delete, making the row visible to normal queries again.

Returns: bool β€” False when this model does not use soft deletes.

trashed()

Model trashed()

source

public function trashed(): bool

Whether this instance is currently soft-deleted.

Returns: bool

prunable()

Model prunable()

source

protected static function prunable(): ?QueryBuilder

Query selecting rows eligible for prune(). Null = pruning disabled. Override per model, e.g. return static::trashedOlderThan('-30 days').

Returns: QueryBuilder\|null

pruning()

Model pruning()

source

protected function pruning(): void

Called on each row before prune() force-deletes it. Override to clean up owned resources (files, cache, ...).

prune()

Model prune()

source

public static function prune(int $chunkSize): int

Force-deletes every row matched by prunable(), chunked, calling pruning() on each first. Call from a scheduled task, not per-request.

Param Type Description
$chunkSize int Rows fetched and removed per batch.

Returns: int β€” Number of rows pruned.

trashedOlderThan()

Model trashedOlderThan()

source

protected static function trashedOlderThan(string $interval): QueryBuilder

Soft-deleted rows older than $interval (DateTime::modify() format, e.g. '-30 days').

Param Type Description
$interval string β€”

Returns: QueryBuilder

cast()

Model cast()

source

protected function cast(string $key, mixed $value): mixed

Applies the declared cast for a column to its raw DB value.

Param Type Description
$key string Column name.
$value mixed Raw value from PDO.

Returns: mixed β€” Typed value, or the raw value when no cast is declared.

encodeForPersistence()

Model encodeForPersistence()

source

private function encodeForPersistence(): array

Attributes ready to bind to a PDO statement: json/array-cast columns holding a non-string value (array/object) are json_encode()'d; everything else passes through unchanged. Does not mutate $this->attributes.

Returns: array<string, mixed>

hasMany()

Model hasMany()

source

protected function hasMany(string $related, string $foreignKey, string $localKey): Collection

Loads all related models where $foreignKey on the related table equals this model's $localKey.

Param Type Description
$related class-string<Model> Fully-qualified related model class.
$foreignKey string Column on the related table pointing back to this model.
$localKey string Column on this model used as the local identifier. Defaults to primary key.

Returns: Collection

belongsTo()

Model belongsTo()

source

protected function belongsTo(string $related, string $foreignKey, string $ownerKey): ?object

Loads the single related model whose $ownerKey matches this model's $foreignKey value.

Param Type Description
$related class-string<Model> Fully-qualified related model class.
$foreignKey string Column on this model holding the foreign key value.
$ownerKey string Column on the related table to match against. Defaults to related primary key.

Returns: object\|null

QueryBuilder

final class β€” rafalmasiarek\DashboardKit\Model\QueryBuilder Β· source

Fluent SELECT query builder for a model class or an ad-hoc table. Created by Model::where()/Model::on() and returned for method chaining. Column and table names are interpolated directly into SQL β€” callers must not pass user-supplied identifiers. Values are always bound as prepared-statement parameters, except Raw (emitted verbatim).

Depends on: PDO, ClockInterface

Property Type Visibility Description
$wheres list<array{column: string, operator: string, value: mixed}|array{column: string, in: list<mixed>, not: bool}|array{raw: string, params: list<mixed>}> private WHERE conditions accumulated via where()/whereIn()/whereRaw() calls.
$joins list<string> private JOIN clauses accumulated via join()/leftJoin().
$limitVal int|null private LIMIT value; null = no limit.
$offsetVal int|null private OFFSET value; null = no offset.
$orderBys list<string> private ORDER BY fragments, e.g. ['name ASC', 'created_at DESC'].
$selectColumns list<string> private SELECT column list. Defaults to '*'. Set via select() β€” e.g. for a join() where some joined table's columns should be left out.
$includeTrashed bool private Whether soft-deleted rows are included. Set by withTrashed()/onlyTrashed().
$onlyTrashed bool private Whether only soft-deleted rows should match. Set by onlyTrashed().
Method Visibility Returns Summary
__construct() public β€” β€”
withTrashed() public static Includes soft-deleted rows in the result, alongside normal ones.
onlyTrashed() public static Restricts the result to soft-deleted rows only.
where() public static Adds a WHERE condition. Multiple calls are combined with AND. When called with two arguments, '=' is assumed as the operator: ->where('active', 1) β†’ WHERE active = ? ->where('role', '!=', 'user') β†’ WHERE role != ? A null value renders IS NULL / IS NOT NULL instead of binding a parameter. A Raw value is emitted verbatim instead of being bound: ->where('expires_at', '>', new Raw('NOW()')) $column is backtick-wrapped as one identifier β€” do not pass a qualified 'table.column' name here (use select()/join() for those).
whereIn() public static Adds a WHERE column IN (...) condition.
whereNotIn() public static Adds a WHERE column NOT IN (...) condition.
whereRaw() public static Adds a raw WHERE fragment, ANDed with every other condition β€” an escape hatch for boolean logic where() can't express, e.g. an OR branch or an EXISTS(...) subquery: ->whereRaw('(created_by = ? OR EXISTS (SELECT 1 FROM t WHERE t.x = ?))', [$a, $b]) $sql is emitted verbatim (trusted, not user input) β€” wrap it in parentheses yourself when it contains OR, so it combines correctly with the implicit AND joining every WHERE condition.
select() public static Sets the SELECT column list, replacing the default '*'. Columns are emitted verbatim (trusted, not user input) β€” qualify them yourself for a join, e.g. select('user_tokens.token', 'users.email').
join() public static Adds an INNER JOIN clause.
leftJoin() public static Adds a LEFT JOIN clause.
joinOn() public static Adds an INNER JOIN with an arbitrary raw ON clause β€” for a multi-column condition join() can't express in one (first, operator, second) triple: ->joinOn('esign_guest_invites', 'esign_guest_invites.envelope_id = esign_signers.envelope_id ' . 'AND esign_guest_invites.signer_id = esign_signers.signer_id') $onSql is emitted verbatim (trusted, not user input) β€” it compares columns to columns, not to bound values; put value comparisons in where()/whereRaw() instead.
leftJoinOn() public static Adds a LEFT JOIN with an arbitrary raw ON clause β€” see joinOn().
insert() public string Inserts a row into this builder's table. The only way to insert when built from Model::on() β€” there is no model class to construct and save(). Ignores any accumulated WHERE/JOIN/etc.; those only apply to get()/ first()/count()/update()/delete().
upsert() public bool Inserts a row, or updates it in one atomic statement when a row already matches $uniqueBy (MySQL: ON DUPLICATE KEY UPDATE; SQLite: ON CONFLICT DO UPDATE) β€” safe under concurrent writers, unlike a SELECT-then-branch. Unlike Model::upsert(), does not auto-manage timestamps β€” this is the ad-hoc-table path, which has no createdAtColumn/updatedAtColumn to know about.
insertOrIgnore() public bool Inserts a row, silently doing nothing if it would violate a unique constraint (MySQL: INSERT IGNORE; SQLite: INSERT OR IGNORE; PostgreSQL: ON CONFLICT DO NOTHING) β€” idempotent insert, not an upsert; an existing row is never modified.
limit() public static Sets the maximum number of rows to return.
offset() public static Sets the row offset for pagination.
orderBy() public static Adds an ORDER BY clause.
get() public Collection Executes the SELECT. Returns model instances when built from a model class, or plain associative arrays for an ad-hoc table (Model::on()).
first() public object|array<string, mixed>|null Returns the first matching row, or null when none found.
count() public int Returns the total number of matching rows.
max() public int|float|string|null Returns the maximum value of $column across matching rows, or null when no row matches (SQL MAX() of an empty set).
min() public int|float|string|null Returns the minimum value of $column across matching rows, or null when no row matches (SQL MIN() of an empty set).
sum() public int|float Returns the sum of $column across matching rows. SQL SUM() of an empty set is NULL; normalized to 0 since a caller asking for a sum virtually always wants a number, not a null check.
aggregate() private int|float|string|null Runs a single-column SQL aggregate (MAX/MIN/SUM) over matching rows.
delete() public int Deletes every matching row in one statement. Soft-deletes (bulk UPDATE of deletedAtColumn) when the model uses soft deletes; otherwise a hard DELETE. Use forceDelete() to always hard-delete regardless.
forceDelete() public int Deletes every matching row outright in one statement, bypassing soft deletes.
update() public int Updates every matching row with the given column values in one statement. Does not auto-manage timestamps β€” include updatedAtColumn in $attributes if it should be refreshed. A Raw value is emitted verbatim instead of bound β€” e.g. ->update(['attempts' => new Raw('attempts + 1')]) for an atomic, concurrency-safe increment.
buildSelect() private array{sql: string, params: list<mixed>} Builds the full SELECT SQL string and parameter list.
joinSql() private string Joins accumulated join()/leftJoin() clauses into one SQL fragment.
buildWhere() private array{string, list<mixed>} Builds the WHERE clause string and collects bound values, including the soft-delete filter implied by withTrashed()/onlyTrashed() when the model uses soft deletes.
renderCondition() private string Renders one WHERE condition, appending any bound parameter to $params by reference.
softDeleteClause() private string|null Soft-delete SQL fragment implied by the model and withTrashed()/onlyTrashed(), if any.
__construct()

QueryBuilder __construct()

source

public function __construct(?string $modelClass, string $table, PDO $pdo, ClockInterface $clock, bool $softDeletes, string $deletedAtColumn)
Param Type Description
$modelClass string|null Fully-qualified model class, or null for an ad-hoc table (Model::on()) β€” rows are returned as plain arrays instead of model instances when null.
$table string Table name.
$pdo PDO Active database connection.
$clock ClockInterface Clock used for soft-delete's deleted_at timestamp.
$softDeletes bool Whether to filter deleted_at automatically.
$deletedAtColumn string Column soft-deletes are written to.
withTrashed()

QueryBuilder withTrashed()

source

public function withTrashed(): static

Includes soft-deleted rows in the result, alongside normal ones.

Returns: static

onlyTrashed()

QueryBuilder onlyTrashed()

source

public function onlyTrashed(): static

Restricts the result to soft-deleted rows only.

Returns: static

where()

QueryBuilder where()

source

public function where(string $column, mixed $operatorOrValue, mixed $value): static

Adds a WHERE condition. Multiple calls are combined with AND. When called with two arguments, '=' is assumed as the operator: ->where('active', 1) β†’ WHERE active = ? ->where('role', '!=', 'user') β†’ WHERE role != ? A null value renders IS NULL / IS NOT NULL instead of binding a parameter. A Raw value is emitted verbatim instead of being bound: ->where('expires_at', '>', new Raw('NOW()')) $column is backtick-wrapped as one identifier β€” do not pass a qualified 'table.column' name here (use select()/join() for those).

Param Type Description
$column string Column name (trusted, not user input).
$operatorOrValue mixed Operator string when $value is given; bound value otherwise.
$value mixed Bound value, null, or Raw when an explicit operator is given.

Returns: static

whereIn()

QueryBuilder whereIn()

source

public function whereIn(string $column, array $values): static

Adds a WHERE column IN (...) condition.

Param Type Description
$column string Column name (trusted, not user input).
$values list<mixed> Bound values. An empty list matches no rows.

Returns: static

whereNotIn()

QueryBuilder whereNotIn()

source

public function whereNotIn(string $column, array $values): static

Adds a WHERE column NOT IN (...) condition.

Param Type Description
$column string Column name (trusted, not user input).
$values list<mixed> Bound values. An empty list matches every row.

Returns: static

whereRaw()

QueryBuilder whereRaw()

source

public function whereRaw(string $sql, array $params): static

Adds a raw WHERE fragment, ANDed with every other condition β€” an escape hatch for boolean logic where() can't express, e.g. an OR branch or an EXISTS(...) subquery: ->whereRaw('(created_by = ? OR EXISTS (SELECT 1 FROM t WHERE t.x = ?))', [$a, $b]) $sql is emitted verbatim (trusted, not user input) β€” wrap it in parentheses yourself when it contains OR, so it combines correctly with the implicit AND joining every WHERE condition.

Param Type Description
$sql string Raw SQL fragment.
$params list<mixed> Bound values for the '?' placeholders in $sql, in order.

Returns: static

select()

QueryBuilder select()

source

public function select(string $columns): static

Sets the SELECT column list, replacing the default '*'. Columns are emitted verbatim (trusted, not user input) β€” qualify them yourself for a join, e.g. select('user_tokens.token', 'users.email').

Param Type Description
$columns string β€”

Returns: static

join()

QueryBuilder join()

source

public function join(string $table, string $first, string $operator, string $second): static

Adds an INNER JOIN clause.

Param Type Description
$table string Table to join (trusted, not user input).
$first string Column on the already-selected table(s).
$operator string Comparison operator, usually '='.
$second string Column on $table.

Returns: static

leftJoin()

QueryBuilder leftJoin()

source

public function leftJoin(string $table, string $first, string $operator, string $second): static

Adds a LEFT JOIN clause.

Param Type Description
$table string Table to join (trusted, not user input).
$first string Column on the already-selected table(s).
$operator string Comparison operator, usually '='.
$second string Column on $table.

Returns: static

joinOn()

QueryBuilder joinOn()

source

public function joinOn(string $table, string $onSql): static

Adds an INNER JOIN with an arbitrary raw ON clause β€” for a multi-column condition join() can't express in one (first, operator, second) triple: ->joinOn('esign_guest_invites', 'esign_guest_invites.envelope_id = esign_signers.envelope_id ' . 'AND esign_guest_invites.signer_id = esign_signers.signer_id') $onSql is emitted verbatim (trusted, not user input) β€” it compares columns to columns, not to bound values; put value comparisons in where()/whereRaw() instead.

Param Type Description
$table string Table to join (trusted, not user input).
$onSql string Raw ON clause (trusted, not user input).

Returns: static

leftJoinOn()

QueryBuilder leftJoinOn()

source

public function leftJoinOn(string $table, string $onSql): static

Adds a LEFT JOIN with an arbitrary raw ON clause β€” see joinOn().

Param Type Description
$table string Table to join (trusted, not user input).
$onSql string Raw ON clause (trusted, not user input).

Returns: static

insert()

QueryBuilder insert()

source

public function insert(array $attributes): string

Inserts a row into this builder's table. The only way to insert when built from Model::on() β€” there is no model class to construct and save(). Ignores any accumulated WHERE/JOIN/etc.; those only apply to get()/ first()/count()/update()/delete().

Param Type Description
$attributes array<string, mixed> β€”

Returns: string β€” Last-insert-id, or '' if the driver reports none.

upsert()

QueryBuilder upsert()

source

public function upsert(array $attributes, array $uniqueBy, ?array $updateColumns): bool

Inserts a row, or updates it in one atomic statement when a row already matches $uniqueBy (MySQL: ON DUPLICATE KEY UPDATE; SQLite: ON CONFLICT DO UPDATE) β€” safe under concurrent writers, unlike a SELECT-then-branch. Unlike Model::upsert(), does not auto-manage timestamps β€” this is the ad-hoc-table path, which has no createdAtColumn/updatedAtColumn to know about.

Param Type Description
$attributes array<string, mixed> β€”
$uniqueBy list<string> Columns identifying an existing row (unique/PK).
$updateColumns list<string>|null Columns to refresh on conflict. Defaults to every column except $uniqueBy.

Returns: bool

insertOrIgnore()

QueryBuilder insertOrIgnore()

source

public function insertOrIgnore(array $attributes): bool

Inserts a row, silently doing nothing if it would violate a unique constraint (MySQL: INSERT IGNORE; SQLite: INSERT OR IGNORE; PostgreSQL: ON CONFLICT DO NOTHING) β€” idempotent insert, not an upsert; an existing row is never modified.

Param Type Description
$attributes array<string, mixed> β€”

Returns: bool

limit()

QueryBuilder limit()

source

public function limit(int $limit): static

Sets the maximum number of rows to return.

Param Type Description
$limit int β€”

Returns: static

offset()

QueryBuilder offset()

source

public function offset(int $offset): static

Sets the row offset for pagination.

Param Type Description
$offset int β€”

Returns: static

orderBy()

QueryBuilder orderBy()

source

public function orderBy(string $column, string $direction): static

Adds an ORDER BY clause.

Param Type Description
$column string Column name (trusted, not user input).
$direction string 'ASC' or 'DESC'. Defaults to 'ASC'.

Returns: static

get()

QueryBuilder get()

source

public function get(): Collection

Executes the SELECT. Returns model instances when built from a model class, or plain associative arrays for an ad-hoc table (Model::on()).

Returns: Collection

first()

QueryBuilder first()

source

public function first(): object|array|null

Returns the first matching row, or null when none found.

Returns: object\|array<string, mixed>\|null

count()

QueryBuilder count()

source

public function count(): int

Returns the total number of matching rows.

Returns: int

max()

QueryBuilder max()

source

public function max(string $column): int|float|string|null

Returns the maximum value of $column across matching rows, or null when no row matches (SQL MAX() of an empty set).

Param Type Description
$column string Column name (trusted, not user input).

Returns: int\|float\|string\|null

min()

QueryBuilder min()

source

public function min(string $column): int|float|string|null

Returns the minimum value of $column across matching rows, or null when no row matches (SQL MIN() of an empty set).

Param Type Description
$column string Column name (trusted, not user input).

Returns: int\|float\|string\|null

sum()

QueryBuilder sum()

source

public function sum(string $column): int|float

Returns the sum of $column across matching rows. SQL SUM() of an empty set is NULL; normalized to 0 since a caller asking for a sum virtually always wants a number, not a null check.

Param Type Description
$column string Column name (trusted, not user input).

Returns: int\|float

aggregate()

QueryBuilder aggregate()

source

private function aggregate(string $fn, string $column): int|float|string|null

Runs a single-column SQL aggregate (MAX/MIN/SUM) over matching rows.

Param Type Description
$fn string Aggregate function name β€” caller-controlled constant, not user input.
$column string Column name (trusted, not user input).

Returns: int\|float\|string\|null

delete()

QueryBuilder delete()

source

public function delete(): int

Deletes every matching row in one statement. Soft-deletes (bulk UPDATE of deletedAtColumn) when the model uses soft deletes; otherwise a hard DELETE. Use forceDelete() to always hard-delete regardless.

Returns: int β€” Number of rows affected.

forceDelete()

QueryBuilder forceDelete()

source

public function forceDelete(): int

Deletes every matching row outright in one statement, bypassing soft deletes.

Returns: int β€” Number of rows affected.

update()

QueryBuilder update()

source

public function update(array $attributes): int

Updates every matching row with the given column values in one statement. Does not auto-manage timestamps β€” include updatedAtColumn in $attributes if it should be refreshed. A Raw value is emitted verbatim instead of bound β€” e.g. ->update(['attempts' => new Raw('attempts + 1')]) for an atomic, concurrency-safe increment.

Param Type Description
$attributes array<string, mixed> β€”

Returns: int β€” Number of rows affected.

buildSelect()

QueryBuilder buildSelect()

source

private function buildSelect(): array

Builds the full SELECT SQL string and parameter list.

Returns: array{sql: string, params: list<mixed>}

joinSql()

QueryBuilder joinSql()

source

private function joinSql(): string

Joins accumulated join()/leftJoin() clauses into one SQL fragment.

Returns: string

buildWhere()

QueryBuilder buildWhere()

source

private function buildWhere(): array

Builds the WHERE clause string and collects bound values, including the soft-delete filter implied by withTrashed()/onlyTrashed() when the model uses soft deletes.

Returns: array{string, list<mixed>}

renderCondition()

QueryBuilder renderCondition()

source

private function renderCondition(string $column, string $operator, mixed $value, array $params): string

Renders one WHERE condition, appending any bound parameter to $params by reference.

Param Type Description
$column string β€”
$operator string β€”
$value mixed β€”
$params list<mixed> β€”

Returns: string

softDeleteClause()

QueryBuilder softDeleteClause()

source

private function softDeleteClause(): ?string

Soft-delete SQL fragment implied by the model and withTrashed()/onlyTrashed(), if any.

Returns: string\|null

Raw

final class β€” rafalmasiarek\DashboardKit\Model\Raw Β· source

Wraps a raw SQL expression (e.g. 'NOW()') so QueryBuilder emits it unescaped in a WHERE clause instead of binding it as a parameter.

Method Visibility Returns Summary
__construct() public β€” β€”
__construct()

Raw __construct()

source

public function __construct(string $sql)
Param Type Description
$sql string Raw SQL fragment, emitted verbatim.

ModuleRegistry

class β€” rafalmasiarek\DashboardKit\Module\ModuleRegistry Β· source

Discovers and indexes application modules from a directory tree. Each module is a directory containing a module.php file that returns a configuration array. The registry tracks template paths and provides filtered views for navbar rendering and scheduling.

Property Type Visibility Description
$modules array<string, array<string, mixed>> private β€”
Method Visibility Returns Summary
discover() public void Scans a directory for module.php files and registers each module found. Calling discover() multiple times merges results β€” later calls override earlier ones when slugs collide, allowing user modules to shadow built-ins.
all() public array<string, array<string, mixed>> Returns all registered modules sorted by order.
find() public array<string, mixed>|null Finds a single module by its slug.
navbarItems() public array<string, array<string, mixed>> Returns modules that should appear in the navigation bar.
resolvePath() private static string|null Resolves the effective navbar path for a module. Resolution order: 1. Explicit 'path' key. 2. For 'routes' modules: first GET route without dynamic segments ({param}). 3. Default: '/{slug}'. Returns null when a routes module has no static GET route β€” the navbar template should render the item as disabled in that case.
scheduledModules() public array<string, array<string, mixed>> Returns modules that define at least one scheduled task.
discover()

ModuleRegistry discover()

source

public function discover(string $dir): void

Scans a directory for module.php files and registers each module found. Calling discover() multiple times merges results β€” later calls override earlier ones when slugs collide, allowing user modules to shadow built-ins.

Param Type Description
$dir string Root directory to scan (glob pattern: {dir}/[*]/module.php).
all()

ModuleRegistry all()

source

public function all(): array

Returns all registered modules sorted by order.

Returns: array<string, array<string, mixed>>

find()

ModuleRegistry find()

source

public function find(string $slug): ?array

Finds a single module by its slug.

Param Type Description
$slug string Module slug identifier.

Returns: array<string, mixed>\|null

navbarItems()

ModuleRegistry navbarItems()

source

public function navbarItems(): array

Returns modules that should appear in the navigation bar.

Returns: array<string, array<string, mixed>>

resolvePath()

ModuleRegistry resolvePath()

source

private static function resolvePath(array $module): ?string

Resolves the effective navbar path for a module. Resolution order: 1. Explicit 'path' key. 2. For 'routes' modules: first GET route without dynamic segments ({param}). 3. Default: '/{slug}'. Returns null when a routes module has no static GET route β€” the navbar template should render the item as disabled in that case.

Param Type Description
$module array<string, mixed> β€”

Returns: string\|null

scheduledModules()

ModuleRegistry scheduledModules()

source

public function scheduledModules(): array

Returns modules that define at least one scheduled task.

Returns: array<string, array<string, mixed>>

DashboardUserColumnsProvider

final class β€” rafalmasiarek\DashboardKit\Schema\DashboardUserColumnsProvider Β· source

Declares the extra columns on the users table that dashboard-kit always requires. Pass unconditionally to Auth::createSchema() so that role and active exist regardless of which login extensions are registered: $auth->createSchema(new DashboardUserColumnsProvider(), ...); Column semantics: role β€” 'user' or 'admin'; governs access to the /admin panel. active β€” 1 = account usable, 0 = pending activation or manually disabled. Defaults to 0 (safe minimum). Code that creates immediately-usable accounts must set active = 1 explicitly (admin panel, registration without require_activation). updated_at β€” Timestamp of the last mutation to any column in this row. MySQL: maintained automatically via ON UPDATE CURRENT_TIMESTAMP. SQLite: must be updated explicitly by application code on writes.

implements SchemaProviderInterface

Method Visibility Returns Summary
additionalSchema() public list<string> β€”
additionalSchema()

DashboardUserColumnsProvider additionalSchema()

source

public function additionalSchema(string $driver): array
Param Type Description
$driver string PDO driver name.

Returns: list<string>

ModuleSchemaBuilder

final class β€” rafalmasiarek\DashboardKit\Schema\ModuleSchemaBuilder Β· source

Builds and executes CREATE TABLE IF NOT EXISTS statements from a declarative array. Supports MySQL and SQLite. Schema arrays are defined in module.php under the 'schema' key and processed by SchemaStateManager on every boot. System columns injected automatically (unless already defined by the user): id β€” CHAR(36) NOT NULL, PRIMARY KEY (UUID v4, application-generated) created_at β€” DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP updated_at β€” DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, plus ON UPDATE CURRENT_TIMESTAMP on MySQL only (no SQLite equivalent), when 'timestamps' resolves to true (see constructor). deleted_at β€” DATETIME NULL DEFAULT NULL, matching Model's $softDeletes convention, when 'soft_deletes' resolves to true. A table's own 'timestamps'/'soft_deletes' key always wins; when a table doesn't set one, it falls back to this instance's $defaultTimestamps/ $defaultSoftDeletes constructor arguments β€” set by the app that constructs this builder (see Dashboard::initModuleSchemas() and its 'schema.timestamps'/'schema.soft_deletes' config keys), not hardcoded here. Table definition format: 'schema' => [ 'my_table' => [ 'timestamps' => true, // override this builder's default 'soft_deletes' => true, // override this builder's default 'columns' => [ 'user_id' => ['type' => 'id_ref', 'null' => false], 'label' => ['type' => 'varchar(255)', 'null' => false], 'note' => ['type' => 'text', 'default' => null], ], 'indexes' => [ // Simple format (non-unique index): 'idx_user_id' => ['user_id'], // Associative format (supports unique): 'uniq_label' => ['columns' => ['label'], 'unique' => true], // Both formats may be mixed in one table. ], 'foreign_keys' => [ ['column' => 'user_id', 'references' => 'users', 'on' => 'id', 'on_delete' => 'CASCADE'], ], ], ] Special column type 'id_ref' always resolves to CHAR(36) regardless of driver, matching the UUID-based primary key used for all module tables.

Method Visibility Returns Summary
__construct() public β€” β€”
build() public void Executes CREATE TABLE IF NOT EXISTS for every table in the schema definition.
statementsFor() public list<string> Generates all SQL statements needed to create one table. For MySQL, indexes and foreign keys are emitted inline inside CREATE TABLE. For SQLite, indexes are emitted as separate CREATE INDEX IF NOT EXISTS statements.
declaredColumns() public array<string, string> Returns all declared column DDL fragments keyed by column name, after auto-injection. Used by SchemaStateManager to detect missing columns and generate ALTER TABLE statements.
expandDefinition() private array<string, mixed> Expands a raw table definition by injecting system columns. Injection rules: - 'id' prepended as CHAR(36) NOT NULL (UUID PK) unless the user defines their own 'id' column, their own 'primary', or sets 'no_id' => true (for a table whose PK is a different column, e.g. a token string, or a composite-key junction table with no single PK column at all). - 'created_at' appended as DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP if not defined. - 'updated_at' appended with ON UPDATE CURRENT_TIMESTAMP if 'timestamps' resolves to true (table's own key, falling back to $defaultTimestamps) and not already defined. - 'deleted_at' appended as DATETIME NULL DEFAULT NULL if 'soft_deletes' resolves to true (table's own key, falling back to $defaultSoftDeletes) and not already defined. User-defined columns always take priority over injected ones.
columnDdl() private string Builds a single column definition fragment.
foreignKeyDdl() private string Builds a FOREIGN KEY constraint fragment.
defaultFragment() private string Generates the DEFAULT fragment for a column definition. Raw SQL expressions (CURRENT_TIMESTAMP, NULL) are emitted unquoted.
parseIndexDef() private array{list<string>, bool} Parses an index definition into a column list and a unique flag. Supports two formats: - Simple (legacy): ['col1', 'col2'] β€” non-unique - Associative: ['columns' => ['col1'], 'unique' => true]
mapType() private string Maps a generic type name to a driver-specific SQL type. 'id_ref' always resolves to CHAR(36) to match the UUID-based primary key convention. SQLite uses type affinity: integers β†’ INTEGER, strings β†’ TEXT, floats β†’ REAL.
__construct()

ModuleSchemaBuilder __construct()

source

public function __construct(bool $defaultTimestamps, bool $defaultSoftDeletes)
Param Type Description
$defaultTimestamps bool Fallback for a table that doesn't set its own 'timestamps' key. False keeps this builder's behavior unchanged for any caller that doesn't pass an argument.
$defaultSoftDeletes bool Fallback for a table that doesn't set its own 'soft_deletes' key. Same default rationale.
build()

ModuleSchemaBuilder build()

source

public function build(array $tables, PDO $pdo): void

Executes CREATE TABLE IF NOT EXISTS for every table in the schema definition.

Param Type Description
$tables array<string, array<string, mixed>> Map of table name β†’ table definition.
$pdo PDO Active database connection.
statementsFor()

ModuleSchemaBuilder statementsFor()

source

public function statementsFor(string $table, array $definition, string $driver): array

Generates all SQL statements needed to create one table. For MySQL, indexes and foreign keys are emitted inline inside CREATE TABLE. For SQLite, indexes are emitted as separate CREATE INDEX IF NOT EXISTS statements.

Param Type Description
$table string Table name.
$definition array<string, mixed> Table definition array.
$driver string PDO driver name ('mysql' or 'sqlite').

Returns: list<string>

declaredColumns()

ModuleSchemaBuilder declaredColumns()

source

public function declaredColumns(array $definition, string $driver): array

Returns all declared column DDL fragments keyed by column name, after auto-injection. Used by SchemaStateManager to detect missing columns and generate ALTER TABLE statements.

Param Type Description
$definition array<string, mixed> Table definition array.
$driver string PDO driver name.

Returns: array<string, string> β€” Map of column name β†’ full DDL fragment (e.g. "col VARCHAR(255) NOT NULL").

expandDefinition()

ModuleSchemaBuilder expandDefinition()

source

private function expandDefinition(array $definition): array

Expands a raw table definition by injecting system columns. Injection rules: - 'id' prepended as CHAR(36) NOT NULL (UUID PK) unless the user defines their own 'id' column, their own 'primary', or sets 'no_id' => true (for a table whose PK is a different column, e.g. a token string, or a composite-key junction table with no single PK column at all). - 'created_at' appended as DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP if not defined. - 'updated_at' appended with ON UPDATE CURRENT_TIMESTAMP if 'timestamps' resolves to true (table's own key, falling back to $defaultTimestamps) and not already defined. - 'deleted_at' appended as DATETIME NULL DEFAULT NULL if 'soft_deletes' resolves to true (table's own key, falling back to $defaultSoftDeletes) and not already defined. User-defined columns always take priority over injected ones.

Param Type Description
$definition array<string, mixed> Raw table definition.

Returns: array<string, mixed> β€” Expanded definition with system columns merged in.

columnDdl()

ModuleSchemaBuilder columnDdl()

source

private function columnDdl(string $name, array $col, string $driver): string

Builds a single column definition fragment.

Param Type Description
$name string Column name.
$col array<string, mixed> Column options.
$driver string PDO driver name.

Returns: string

foreignKeyDdl()

ModuleSchemaBuilder foreignKeyDdl()

source

private function foreignKeyDdl(array $fk): string

Builds a FOREIGN KEY constraint fragment.

Param Type Description
$fk array<string, mixed> Foreign key definition.

Returns: string

defaultFragment()

ModuleSchemaBuilder defaultFragment()

source

private function defaultFragment(array $col): string

Generates the DEFAULT fragment for a column definition. Raw SQL expressions (CURRENT_TIMESTAMP, NULL) are emitted unquoted.

Param Type Description
$col array<string, mixed> β€”

Returns: string

parseIndexDef()

ModuleSchemaBuilder parseIndexDef()

source

private function parseIndexDef(array $indexDef): array

Parses an index definition into a column list and a unique flag. Supports two formats: - Simple (legacy): ['col1', 'col2'] β€” non-unique - Associative: ['columns' => ['col1'], 'unique' => true]

Param Type Description
$indexDef array<mixed> Raw value from the 'indexes' map.

Returns: array{list<string>, bool}

mapType()

ModuleSchemaBuilder mapType()

source

private function mapType(string $type, string $driver): string

Maps a generic type name to a driver-specific SQL type. 'id_ref' always resolves to CHAR(36) to match the UUID-based primary key convention. SQLite uses type affinity: integers β†’ INTEGER, strings β†’ TEXT, floats β†’ REAL.

Param Type Description
$type string Declared type from the schema array (e.g. 'int', 'varchar(255)', 'id_ref').
$driver string PDO driver name.

Returns: string

PasswordResetSchemaProvider

final class β€” rafalmasiarek\DashboardKit\Schema\PasswordResetSchemaProvider Β· source

Declares the password_resets table required by the password-reset flow. Pass to Auth::createSchema() only when password_reset is enabled: $auth->createSchema(new DashboardUserColumnsProvider(), new PasswordResetSchemaProvider(), ...);

implements SchemaProviderInterface

Method Visibility Returns Summary
additionalSchema() public list<string> β€”
additionalSchema()

PasswordResetSchemaProvider additionalSchema()

source

public function additionalSchema(string $driver): array
Param Type Description
$driver string PDO driver name.

Returns: list<string>

SchemaInspector

final class β€” rafalmasiarek\DashboardKit\Schema\SchemaInspector Β· source

Reads the actual column list of an existing database table. Used by SchemaStateManager to detect columns missing from the live schema so that ALTER TABLE ADD COLUMN statements can be generated for them.

Method Visibility Returns Summary
columnNames() public list<string> Returns the column names that currently exist in the given table. Returns an empty array when the table does not exist yet.
mysqlColumnNames() private list<string> Reads column names from INFORMATION_SCHEMA for MySQL/MariaDB.
sqliteColumnNames() private list<string> Reads column names from PRAGMA table_info for SQLite.
columnNames()

SchemaInspector columnNames()

source

public function columnNames(string $table, PDO $pdo): array

Returns the column names that currently exist in the given table. Returns an empty array when the table does not exist yet.

Param Type Description
$table string Table name.
$pdo PDO Active database connection.

Returns: list<string>

mysqlColumnNames()

SchemaInspector mysqlColumnNames()

source

private function mysqlColumnNames(string $table, PDO $pdo): array

Reads column names from INFORMATION_SCHEMA for MySQL/MariaDB.

Param Type Description
$table string β€”
$pdo PDO β€”

Returns: list<string>

sqliteColumnNames()

SchemaInspector sqliteColumnNames()

source

private function sqliteColumnNames(string $table, PDO $pdo): array

Reads column names from PRAGMA table_info for SQLite.

Param Type Description
$table string β€”
$pdo PDO β€”

Returns: list<string>

SchemaStateManager

final class β€” rafalmasiarek\DashboardKit\Schema\SchemaStateManager Β· source

Manages module schema lifecycle: creation, column diffing, and state tracking. On every boot, SchemaStateManager compares a hash of each table's declared schema (folded together with the injected ModuleSchemaBuilder's own default flags, so a config-level default change invalidates every table that relies on it) against the hash stored in _schema_state. Tables whose hash has not changed are skipped entirely β€” no INFORMATION_SCHEMA queries, no ALTER TABLE. Only tables with a changed or missing hash go through the full sync cycle: 1. CREATE TABLE IF NOT EXISTS (idempotent, driver-specific DDL via ModuleSchemaBuilder) 2. Introspect actual columns (SchemaInspector β€” only on hash mismatch) 3. ALTER TABLE ADD COLUMN (only for columns declared but absent in DB) 4. Upsert _schema_state (new hash + column count + timestamp) Columns are never dropped or modified β€” only added. New NOT NULL columns added to tables with existing rows must declare a DEFAULT value.

Depends on: PDO, ModuleSchemaBuilder, SchemaInspector, ClockInterface

Method Visibility Returns Summary
__construct() public β€” β€”
sync() public void Syncs all module schemas against the live database.
forAlter() private string Adapts a column DDL fragment for use in ALTER TABLE ADD COLUMN. SQLite rejects a non-constant default (CURRENT_TIMESTAMP included) on ADD COLUMN, even though the exact same default is accepted on CREATE TABLE β€” "Cannot add a column with non-constant default". Substituted with a literal snapshot of now, so the backfill succeeds; the column's default for any future INSERT on SQLite is this same frozen literal, a known, narrower version of the "no ON UPDATE equivalent on SQLite" limitation already documented on ModuleSchemaBuilder. MySQL accepts CURRENT_TIMESTAMP on ADD COLUMN natively and is left untouched.
collectTables() private array<string, array{definition: array<string, mixed>, module: string}> Flattens all module schema definitions into a single table map.
loadStoredHashes() private array<string, string> Loads stored hashes for all given table names in a single query.
ensureSystemTables() private void Creates all system tables required by the dashboard infrastructure. Tables created (all prefixed with underscore to avoid collisions): _schema_state β€” hash + column count per module table; drives the schema sync fast path. _table_version β€” monotonic write counter per table; used by TableVersionTracker for version-keyed cache invalidation. _query_cache β€” serialized query results with TTL; used by QueryCacheStore.
upsertState() private void Inserts or updates the state record for one table.
__construct()

SchemaStateManager __construct()

source

public function __construct(PDO $pdo, ModuleSchemaBuilder $builder, SchemaInspector $inspector, string $tablePrefix, ?ClockInterface $clock)
Param Type Description
$pdo PDO Active database connection.
$builder ModuleSchemaBuilder Builds DDL statements from declarative arrays.
$inspector SchemaInspector Reads actual column lists from the live schema.
$tablePrefix string Optional prefix applied to every module table name. System tables (_schema_state, _table_version, _query_cache) are never prefixed.
$clock ClockInterface|null Clock for the SQLite ALTER-backfill literal below. Defaults to SystemClock.
sync()

SchemaStateManager sync()

source

public function sync(array $modules): void

Syncs all module schemas against the live database.

Param Type Description
$modules array<string, array<string, mixed>> Map of module slug β†’ module definition (only modules with an array 'schema' key are processed).
forAlter()

SchemaStateManager forAlter()

source

private function forAlter(string $colDdl, string $driver): string

Adapts a column DDL fragment for use in ALTER TABLE ADD COLUMN. SQLite rejects a non-constant default (CURRENT_TIMESTAMP included) on ADD COLUMN, even though the exact same default is accepted on CREATE TABLE β€” "Cannot add a column with non-constant default". Substituted with a literal snapshot of now, so the backfill succeeds; the column's default for any future INSERT on SQLite is this same frozen literal, a known, narrower version of the "no ON UPDATE equivalent on SQLite" limitation already documented on ModuleSchemaBuilder. MySQL accepts CURRENT_TIMESTAMP on ADD COLUMN natively and is left untouched.

Param Type Description
$colDdl string Column DDL fragment from declaredColumns().
$driver string PDO driver name.

Returns: string

collectTables()

SchemaStateManager collectTables()

source

private function collectTables(array $modules): array

Flattens all module schema definitions into a single table map.

Param Type Description
$modules array<string, array<string, mixed>> β€”

Returns: array<string, array{definition: array<string, mixed>, module: string}>

loadStoredHashes()

SchemaStateManager loadStoredHashes()

source

private function loadStoredHashes(array $tableNames): array

Loads stored hashes for all given table names in a single query.

Param Type Description
$tableNames list<string> β€”

Returns: array<string, string> β€” Map of table name β†’ stored hash.

ensureSystemTables()

SchemaStateManager ensureSystemTables()

source

private function ensureSystemTables(string $driver): void

Creates all system tables required by the dashboard infrastructure. Tables created (all prefixed with underscore to avoid collisions): _schema_state β€” hash + column count per module table; drives the schema sync fast path. _table_version β€” monotonic write counter per table; used by TableVersionTracker for version-keyed cache invalidation. _query_cache β€” serialized query results with TTL; used by QueryCacheStore.

Param Type Description
$driver string PDO driver name ('mysql' or 'sqlite').
upsertState()

SchemaStateManager upsertState()

source

private function upsertState(string $table, string $module, string $hash, int $count, string $driver): void

Inserts or updates the state record for one table.

Param Type Description
$table string Table name.
$module string Module slug that owns the table.
$hash string md5 hash of the serialized schema definition.
$count int Number of declared columns after auto-injection.
$driver string PDO driver name.

SeedRunner

final class β€” rafalmasiarek\DashboardKit\Schema\SeedRunner Β· source

Runs declarative seed definitions against the live database. Seeds are idempotent: each row is skipped when a matching record already exists (matched by the 'match' key). Only missing rows are inserted. ## References between seeds Seeds run in definition order. A row may declare a #ref alias that makes its resolved id available to later rows via @ref:alias.field placeholders. 'users' => [ 'rows' => [ ['email' => 'admin@example.com', ..., '#ref' => 'admin'], ], ], 'tibia_user_prefs' => [ 'rows' => [ ['user_id' => '@ref:admin.id', 'notify_daily' => 1], ], ], #ref is stripped before insertion. @ref:alias.field is resolved against the stored column map of the referenced row (including the generated id). If the ref alias is unknown the placeholder resolves to null. ## Format 'seed' => [ 'users' => [ 'match' => 'email', // unique column to check before inserting 'with_id' => true, // auto-generate UUID for id if absent (default: true) 'rows' => [ [ 'email' => 'admin@example.com', 'role' => 'admin', 'active' => 1, 'password_hash' => password_hash('secret', PASSWORD_BCRYPT), '#ref' => 'admin', ], ], ], 'api_scopes' => [ 'match' => 'name', 'with_id' => false, // table uses AUTO_INCREMENT β€” skip UUID injection 'rows' => [ ['name' => 'shorts:read', 'description' => 'Read short links'], ['name' => 'shorts:write', 'description' => 'Manage short links'], ], ], ], 'with_id' defaults to true. Set it to false for tables whose id column is AUTO_INCREMENT (i.e. tables that declare id explicitly in their schema columns instead of relying on the framework's UUID auto-injection). 'created_at' is never auto-injected: tables created by ModuleSchemaBuilder always have DEFAULT CURRENT_TIMESTAMP on that column, so it is optional in seed rows and the database fills it in automatically.

Depends on: PDO

Method Visibility Returns Summary
__construct() public β€” β€”
run() public void Execute all seed definitions in order. Seeds run in PHP array order. Rows tagged with '#ref' register their resolved id so that subsequent rows can use '@ref:alias.field' placeholders.
insertIfMissing() private string|null Insert a row only when no matching record exists. When $withId is true the existence check fetches the existing id so it can be registered as a ref. When $withId is false (AUTO_INCREMENT / no UUID id column) COUNT(*) is used and the method returns null β€” those tables have nothing to resolve via '@ref:'. When $matchKey is empty the check is skipped and the row is always inserted.
generateUuid() private string Generate a UUID v4 string.
__construct()

SeedRunner __construct()

source

public function __construct(PDO $pdo, string $tablePrefix)
Param Type Description
$pdo PDO Raw database connection (bypasses CachingPdo).
$tablePrefix string Optional prefix applied to every table name. Default: ''.
run()

SeedRunner run()

source

public function run(array $seeds): void

Execute all seed definitions in order. Seeds run in PHP array order. Rows tagged with '#ref' register their resolved id so that subsequent rows can use '@ref:alias.field' placeholders.

Param Type Description
$seeds array<string, array{match?: string, with_id?: bool, rows: list<array<string, mixed>>}> Map of table name β†’ seed definition.
insertIfMissing()

SeedRunner insertIfMissing()

source

private function insertIfMissing(string $table, array $row, string $matchKey, bool $withId, bool $ignoreDuplicates): string|null

Insert a row only when no matching record exists. When $withId is true the existence check fetches the existing id so it can be registered as a ref. When $withId is false (AUTO_INCREMENT / no UUID id column) COUNT(*) is used and the method returns null β€” those tables have nothing to resolve via '@ref:'. When $matchKey is empty the check is skipped and the row is always inserted.

Param Type Description
$table string Target table name.
$row array<string, mixed> Column β†’ value map.
$matchKey string Column name used for the existence check.
$withId bool Whether the table has a UUID id column.
$ignoreDuplicates bool β€”

Returns: string\|null β€” Resolved id of the row, or null when unavailable.

generateUuid()

SeedRunner generateUuid()

source

private function generateUuid(): string

Generate a UUID v4 string.

Returns: string β€” Formatted as xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx.

Throws When
\Random\RandomException On PRNG failure (PHP 8.2+).

UserFieldsSchemaProvider

final class β€” rafalmasiarek\DashboardKit\Schema\UserFieldsSchemaProvider Β· source

Declares ALTER TABLE statements for project-configured custom user fields. Pass to Auth::createSchema() so that extra profile columns are created alongside the core schema: $auth->createSchema(..., new UserFieldsSchemaProvider($userFields));

implements SchemaProviderInterface

Method Visibility Returns Summary
__construct() public β€” β€”
additionalSchema() public list<string> β€”
sqlType() private string Maps a user-field definition to a SQL column type for the given driver.
__construct()

UserFieldsSchemaProvider __construct()

source

public function __construct(array $fields)
Param Type Description
$fields array<string, array{label: string, type: string, max: int, required: bool}> β€”
additionalSchema()

UserFieldsSchemaProvider additionalSchema()

source

public function additionalSchema(string $driver): array
Param Type Description
$driver string PDO driver name.

Returns: list<string>

sqlType()

UserFieldsSchemaProvider sqlType()

source

private function sqlType(array $field, string $driver): string

Maps a user-field definition to a SQL column type for the given driver.

Param Type Description
$field array{label: string, type: string, max: int, required: bool} β€”
$driver string β€”

Returns: string

SecretRegistry

final class β€” rafalmasiarek\DashboardKit\Security\SecretRegistry Β· source

Central registry of sensitive values to be redacted from messages and stack traces.

Property Type Visibility Description
$values array<int, string> private static Registered secret values.
Method Visibility Returns Summary
__construct() private β€” β€”
addValue() public static void Register a single secret value. No-op when the value is null, empty, or shorter than MIN_LEN.
addValues() public static void Register multiple secret values at once.
primeFromConfig() public static void Recursively scan a config array and register values whose key path looks sensitive. Matched key path segments (case-insensitive): secret, password, passwd, pwd, token, api_key, api-key, smtp.*password, _key, _pass, _hash, _salt, _pem, _kek, credential
redactValues() public static string Replace all registered secret values in a string with "****". Returns the original string unchanged when no secrets are registered.
primeFromEnv() public static void Scan $_ENV and $_SERVER for keys that look sensitive and register their values. Uses the same key pattern as the Whoops error-page blacklist in Dashboard.
reset() public static void Clear all registered values (primarily useful in tests).
__construct()

SecretRegistry __construct()

source

private function __construct()
addValue()

SecretRegistry addValue()

source

public static function addValue(?string $value): void

Register a single secret value. No-op when the value is null, empty, or shorter than MIN_LEN.

Param Type Description
$value string|null β€”
addValues()

SecretRegistry addValues()

source

public static function addValues(iterable $values): void

Register multiple secret values at once.

Param Type Description
$values iterable<string> β€”
primeFromConfig()

SecretRegistry primeFromConfig()

source

public static function primeFromConfig(array $config): void

Recursively scan a config array and register values whose key path looks sensitive. Matched key path segments (case-insensitive): secret, password, passwd, pwd, token, api_key, api-key, smtp.*password, _key, _pass, _hash, _salt, _pem, _kek, credential

Param Type Description
$config array<string, mixed> β€”
redactValues()

SecretRegistry redactValues()

source

public static function redactValues(string $message): string

Replace all registered secret values in a string with "****". Returns the original string unchanged when no secrets are registered.

Param Type Description
$message string β€”

Returns: string

primeFromEnv()

SecretRegistry primeFromEnv()

source

public static function primeFromEnv(): void

Scan $_ENV and $_SERVER for keys that look sensitive and register their values. Uses the same key pattern as the Whoops error-page blacklist in Dashboard.

reset()

SecretRegistry reset()

source

public static function reset(): void

Clear all registered values (primarily useful in tests).

LazyPhpSessionTransport

final class β€” rafalmasiarek\DashboardKit\Transport\LazyPhpSessionTransport Β· source

Session transport that defers session_start() until the session is first accessed. The default PhpSessionTransport calls session_start() inside initialize(), which is invoked by Auth::__construct(). When Auth is resolved eagerly during container bootstrap β€” before any request middleware runs β€” any PHP notice or deprecation written to output by the DI container causes "headers already sent", making session_start() fail. This transport skips initialize() as a no-op. The session is started lazily on the first actual read or write, by which point the SessionMiddleware has already run and the session is active β€” making this a safe no-op itself.

implements TokenTransportInterface

Property Type Visibility Description
$key string private key used to store the auth token.
Method Visibility Returns Summary
__construct() public β€” β€”
initialize() public void No-op β€” session is started lazily on first access.
get() public string|null Returns the stored token, starting the session if not yet active.
set() public void Stores the token in the session, starting it if not yet active.
clear() public void Removes the token from the session, starting it if not yet active.
ensureSession() private void Starts the PHP session if not yet active.
__construct()

LazyPhpSessionTransport __construct()

source

public function __construct(string $key)
Param Type Description
$key string $_SESSION key (default: 'auth_token').
initialize()

LazyPhpSessionTransport initialize()

source

public function initialize(): void

No-op β€” session is started lazily on first access.

get()

LazyPhpSessionTransport get()

source

public function get(): ?string

Returns the stored token, starting the session if not yet active.

Returns: string\|null

set()

LazyPhpSessionTransport set()

source

public function set(string $token): void

Stores the token in the session, starting it if not yet active.

Param Type Description
$token string β€”
clear()

LazyPhpSessionTransport clear()

source

public function clear(): void

Removes the token from the session, starting it if not yet active.

ensureSession()

LazyPhpSessionTransport ensureSession()

source

private function ensureSession(): void

Starts the PHP session if not yet active.

CsrfExtension

class β€” rafalmasiarek\DashboardKit\Twig\CsrfExtension Β· source

Twig extension that exposes the csrf_field() function for use in templates. Usage in any form: {{ csrf_field('login') }} Renders via the package's own HtmlHelper::input(), which emits: (only when a session-bound proof is available) The container name isolates tokens per form β€” a token generated for 'login' cannot be replayed on 'register' or any module form.

extends AbstractExtension

Depends on: Csrf, RealIpResolver

Method Visibility Returns Summary
__construct() public β€” β€”
getFunctions() public list<TwigFunction> β€”
renderField() public string Renders the hidden CSRF inputs for a named container. $ip defaults to the resolved real client IP (see RealIpResolver above); $userAgent defaults to Csrf's own auto-detection. Both accept an explicit override for callers with a reason to bind the token to something other than the current request (e.g. issuing a token server-side, outside of a normal request/response cycle).
__construct()

CsrfExtension __construct()

source

public function __construct(Csrf $csrf, RealIpResolver $ipResolver)
Param Type Description
$csrf Csrf CSRF token service.
$ipResolver RealIpResolver Resolves the real client IP behind trusted proxies (e.g. Cloudflare), so tokens are issued bound to the same address CsrfMiddleware validates against.
getFunctions()

CsrfExtension getFunctions()

source

public function getFunctions(): array

Returns: list<TwigFunction>

renderField()

CsrfExtension renderField()

source

public function renderField(string $container, ?string $ip, ?string $userAgent): string

Renders the hidden CSRF inputs for a named container. $ip defaults to the resolved real client IP (see RealIpResolver above); $userAgent defaults to Csrf's own auto-detection. Both accept an explicit override for callers with a reason to bind the token to something other than the current request (e.g. issuing a token server-side, outside of a normal request/response cycle).

Param Type Description
$container string Unique form identifier (e.g. 'login', 'register', module slug).
$ip string|null Optional client IP override.
$userAgent string|null Optional User-Agent override.

Returns: string β€” HTML-safe hidden input markup.

DashboardExtension

class β€” rafalmasiarek\DashboardKit\Twig\DashboardExtension Β· source

General-purpose Twig functions for the dashboard layout.

extends AbstractExtension

Method Visibility Returns Summary
getFunctions() public list<TwigFunction> β€”
gravatarUrl() public string Returns the Gravatar URL for the given email address. Falls back to identicon when no Gravatar is registered.
getFunctions()

DashboardExtension getFunctions()

source

public function getFunctions(): array

Returns: list<TwigFunction>

gravatarUrl()

DashboardExtension gravatarUrl()

source

public function gravatarUrl(string $email, int $size): string

Returns the Gravatar URL for the given email address. Falls back to identicon when no Gravatar is registered.

Param Type Description
$email string User email address.
$size int Avatar size in pixels (1–2048). Default: 40.

Returns: string β€” HTTPS URL to the avatar image.

ClockInterface

interface β€” rafalmasiarek\DashboardKit\Utils\ClockInterface Β· source

Timezone-aware clock contract, extending PSR-20 with formatting/timezone helpers.

extends PsrClockInterface

Method Visibility Returns Summary
tzId() public string Resolves the effective timezone identifier.
tz() public DateTimeZone Returns the effective DateTimeZone instance.
nowUtc() public DateTimeImmutable Returns the current time in UTC.
at() public DateTimeImmutable Creates a DateTimeImmutable for the given time string in this clock's timezone.
fromInterface() public DateTimeImmutable Converts an arbitrary DateTimeInterface into an immutable instance in this clock's timezone.
formatAtomFromTimestamp() public string Formats a unix timestamp as DATE_ATOM in this clock's timezone.
formatAtom() public string Formats a DateTimeInterface as DATE_ATOM in this clock's timezone.
formatSqlUtc() public string Formats a DateTimeInterface as SQL DATETIME in UTC ("Y-m-d H:i:s").
formatMinuteKey() public string Returns a minute slot key (YmdHi) for a DateTimeInterface in this clock's timezone.
formatMinuteKeyFromTimestamp() public string Returns a minute slot key (YmdHi) for a unix timestamp in this clock's timezone.
tzId()

ClockInterface tzId()

source

public function tzId(): string

Resolves the effective timezone identifier.

Returns: string

tz()

ClockInterface tz()

source

public function tz(): DateTimeZone

Returns the effective DateTimeZone instance.

Returns: DateTimeZone

nowUtc()

ClockInterface nowUtc()

source

public function nowUtc(): DateTimeImmutable

Returns the current time in UTC.

Returns: DateTimeImmutable

at()

ClockInterface at()

source

public function at(string $timeStr): DateTimeImmutable

Creates a DateTimeImmutable for the given time string in this clock's timezone.

Param Type Description
$timeStr string β€”

Returns: DateTimeImmutable

fromInterface()

ClockInterface fromInterface()

source

public function fromInterface(DateTimeInterface $dt): DateTimeImmutable

Converts an arbitrary DateTimeInterface into an immutable instance in this clock's timezone.

Param Type Description
$dt DateTimeInterface β€”

Returns: DateTimeImmutable

formatAtomFromTimestamp()

ClockInterface formatAtomFromTimestamp()

source

public function formatAtomFromTimestamp(int $ts): string

Formats a unix timestamp as DATE_ATOM in this clock's timezone.

Param Type Description
$ts int Unix timestamp.

Returns: string

formatAtom()

ClockInterface formatAtom()

source

public function formatAtom(DateTimeInterface $dt): string

Formats a DateTimeInterface as DATE_ATOM in this clock's timezone.

Param Type Description
$dt DateTimeInterface β€”

Returns: string

formatSqlUtc()

ClockInterface formatSqlUtc()

source

public function formatSqlUtc(DateTimeInterface $dt): string

Formats a DateTimeInterface as SQL DATETIME in UTC ("Y-m-d H:i:s").

Param Type Description
$dt DateTimeInterface β€”

Returns: string

formatMinuteKey()

ClockInterface formatMinuteKey()

source

public function formatMinuteKey(DateTimeInterface $dt): string

Returns a minute slot key (YmdHi) for a DateTimeInterface in this clock's timezone.

Param Type Description
$dt DateTimeInterface β€”

Returns: string

formatMinuteKeyFromTimestamp()

ClockInterface formatMinuteKeyFromTimestamp()

source

public function formatMinuteKeyFromTimestamp(int $ts): string

Returns a minute slot key (YmdHi) for a unix timestamp in this clock's timezone.

Param Type Description
$ts int Unix timestamp.

Returns: string

PasswordStrength

class β€” rafalmasiarek\DashboardKit\Utils\PasswordStrength Β· source

Configurable password strength scorer returning a score in the range 0–4. Rules are named arrays merged recursively with DEFAULT_RULES. Pass only the keys you want to override β€” everything else inherits the default. Scoring pipeline: 1. Forbidden characters β†’ instant score 0 (no further evaluation). 2. Positive bonuses: min_length, diversity, digit_ratio, special_ratio. 3. Soft penalties: no_repeats, no_sequences (subtracted from bonus total). 4. final = max(0, earned βˆ’ penalties) / max_possible Γ— 5, clamped to 0–4. The companion JavaScript in register.twig mirrors this logic exactly using the resolved rule set serialised as JSON, so client-side and server-side always agree.

Method Visibility Returns Summary
score() public static int Returns the strength score for the given password.
hasSequence() private static bool Returns whether the password contains an ascending or descending character sequence of at least the given length (case-insensitive). Examples (length=3): "abc", "XYZ", "321", "cba" all match.
score()

PasswordStrength score()

source

public static function score(string $password, array $ruleOverrides): int

Returns the strength score for the given password.

Param Type Description
$password string Plain-text password.
$ruleOverrides array<string, array<string, mixed>> Partial overrides merged into DEFAULT_RULES.

Returns: int β€” Score 0–4.

hasSequence()

PasswordStrength hasSequence()

source

private static function hasSequence(string $password, int $length): bool

Returns whether the password contains an ascending or descending character sequence of at least the given length (case-insensitive). Examples (length=3): "abc", "XYZ", "321", "cba" all match.

Param Type Description
$password string β€”
$length int Minimum run length to flag.

Returns: bool

SystemClock

final class β€” rafalmasiarek\DashboardKit\Utils\SystemClock Β· source

Default ClockInterface β€” plain system time, no timezone awareness. Used when nothing else is bound to ClockInterface::class. An app with its own timezone-aware clock should override this binding after Dashboard::create() β€” the same pattern already used for MailerInterface, RealIpResolver, and GeoIpDriverInterface.

implements ClockInterface

Method Visibility Returns Summary
now() public DateTimeImmutable {@inheritdoc}
now()

SystemClock now()

source

public function now(): DateTimeImmutable

{@inheritdoc}

Returns: DateTimeImmutable

TimezoneClock

final class β€” rafalmasiarek\DashboardKit\Utils\TimezoneClock Β· source

Default implementation of the richer ClockInterface β€” defers entirely to PHP's own default timezone, no configuration of its own.

implements ClockInterface

Method Visibility Returns Summary
tzId() public string Resolves the effective timezone identifier.
tz() public DateTimeZone Returns the effective DateTimeZone instance.
now() public DateTimeImmutable {@inheritdoc}
nowUtc() public DateTimeImmutable Returns the current time in UTC.
at() public DateTimeImmutable Creates a DateTimeImmutable for the given time string in this clock's timezone.
fromInterface() public DateTimeImmutable Converts an arbitrary DateTimeInterface into an immutable instance in this clock's timezone.
formatAtomFromTimestamp() public string Formats a unix timestamp as DATE_ATOM in this clock's timezone.
formatAtom() public string Formats a DateTimeInterface as DATE_ATOM in this clock's timezone.
formatSqlUtc() public string Formats a DateTimeInterface as SQL DATETIME in UTC ("Y-m-d H:i:s").
formatMinuteKey() public string Returns a minute slot key (YmdHi) for a DateTimeInterface in this clock's timezone.
formatMinuteKeyFromTimestamp() public string Returns a minute slot key (YmdHi) for a unix timestamp in this clock's timezone.
tzId()

TimezoneClock tzId()

source

public function tzId(): string

Resolves the effective timezone identifier.

Returns: string

tz()

TimezoneClock tz()

source

public function tz(): DateTimeZone

Returns the effective DateTimeZone instance.

Returns: DateTimeZone

now()

TimezoneClock now()

source

public function now(): DateTimeImmutable

{@inheritdoc}

Returns: DateTimeImmutable

nowUtc()

TimezoneClock nowUtc()

source

public function nowUtc(): DateTimeImmutable

Returns the current time in UTC.

Returns: DateTimeImmutable

at()

TimezoneClock at()

source

public function at(string $timeStr): DateTimeImmutable

Creates a DateTimeImmutable for the given time string in this clock's timezone.

Param Type Description
$timeStr string β€”

Returns: DateTimeImmutable

fromInterface()

TimezoneClock fromInterface()

source

public function fromInterface(DateTimeInterface $dt): DateTimeImmutable

Converts an arbitrary DateTimeInterface into an immutable instance in this clock's timezone.

Param Type Description
$dt DateTimeInterface β€”

Returns: DateTimeImmutable

formatAtomFromTimestamp()

TimezoneClock formatAtomFromTimestamp()

source

public function formatAtomFromTimestamp(int $ts): string

Formats a unix timestamp as DATE_ATOM in this clock's timezone.

Param Type Description
$ts int Unix timestamp.

Returns: string

formatAtom()

TimezoneClock formatAtom()

source

public function formatAtom(DateTimeInterface $dt): string

Formats a DateTimeInterface as DATE_ATOM in this clock's timezone.

Param Type Description
$dt DateTimeInterface β€”

Returns: string

formatSqlUtc()

TimezoneClock formatSqlUtc()

source

public function formatSqlUtc(DateTimeInterface $dt): string

Formats a DateTimeInterface as SQL DATETIME in UTC ("Y-m-d H:i:s").

Param Type Description
$dt DateTimeInterface β€”

Returns: string

formatMinuteKey()

TimezoneClock formatMinuteKey()

source

public function formatMinuteKey(DateTimeInterface $dt): string

Returns a minute slot key (YmdHi) for a DateTimeInterface in this clock's timezone.

Param Type Description
$dt DateTimeInterface β€”

Returns: string

formatMinuteKeyFromTimestamp()

TimezoneClock formatMinuteKeyFromTimestamp()

source

public function formatMinuteKeyFromTimestamp(int $ts): string

Returns a minute slot key (YmdHi) for a unix timestamp in this clock's timezone.

Param Type Description
$ts int Unix timestamp.

Returns: string

Uuid

class β€” rafalmasiarek\DashboardKit\Utils\Uuid Β· source

Generates and validates UUID v4 identifiers.

Method Visibility Returns Summary
v4() public static string Generates a cryptographically random UUID v4.
isValid() public static bool Returns whether the given string is a valid UUID v4.
v4()

Uuid v4()

source

public static function v4(): string

Generates a cryptographically random UUID v4.

Returns: string β€” UUID in xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx format.

isValid()

Uuid isValid()

source

public static function isValid(string $uuid): bool

Returns whether the given string is a valid UUID v4.

Param Type Description
$uuid string β€”

Returns: bool

UuidUserIdPolicy

final class β€” rafalmasiarek\DashboardKit\Utils\UuidUserIdPolicy Β· source

Assigns a UUID v4 string as the user ID on creation. Use this policy when the users table should use a CHAR(36) primary key instead of an integer auto-increment column. Pass to PdoUserStorage: new PdoUserStorage($pdo, new UuidUserIdPolicy()) The schema is created automatically by Auth::createSchema() or PdoUserStorage::createSchema() using the column definitions below.

implements UserIdPolicyInterface

Method Visibility Returns Summary
generate() public string Generate a UUID v4 string to use as the new user's primary key.
idColumnDefinition() public string β€”
userIdForeignType() public string β€”
generate()

UuidUserIdPolicy generate()

source

public function generate(): string

Generate a UUID v4 string to use as the new user's primary key.

Returns: string β€” UUID v4 in xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx format.

idColumnDefinition()

UuidUserIdPolicy idColumnDefinition()

source

public function idColumnDefinition(string $driver): string
Param Type Description
$driver string β€”

Returns: string

userIdForeignType()

UuidUserIdPolicy userIdForeignType()

source

public function userIdForeignType(string $driver): string
Param Type Description
$driver string β€”

Returns: string