rafalmasiarek / dashboard-kit
Slim 4 dashboard boilerplate with module auto-discovery, dynamic navbar, auth, CSRF protection and built-in API routing.
Requires
- php: >=8.2
- filp/whoops: ^2.15
- monolog/monolog: ^3.0
- php-di/php-di: ^6.4 || ^7.0
- psr/clock: ^1.0
- psr/container: ^1.1 || ^2.0
- psr/log: ^3.0
- rafalmasiarek/authkit: ^2.1.2
- rafalmasiarek/csrf-token: ^1.7
- rafalmasiarek/dns-resolver: ^0.2.0
- rafalmasiarek/http-client: ^3.0
- rafalmasiarek/mailer: ^0.3.0
- rafalmasiarek/real-ip-resolver: ^2.3
- slim/psr7: ^1.5
- slim/slim: ^4.12
- slim/twig-view: ^3.3
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v6.1.0
- v6.0.0
- v5.4.2
- v5.4.1
- v5.4.0
- v5.3.1
- v5.3.0
- v5.2.0
- v5.1.0
- v5.0.0
- v4.8.0
- v4.7.0
- v4.6.1
- v4.6.0
- v4.5.0
- v4.4.0
- v4.3.1
- v4.3.0
- v4.2.0
- v4.1.1
- v4.1.0
- v4.0.1
- v4.0.0
- v3.0.0
- v2.4.0
- v2.3.0
- v2.2.0
- v2.1.0
- v2.0.0
- v1.4.0
- v1.3.0
- v1.2.0
- v1.1.0
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- dev-fix/footer-includes-key
- dev-docs/php-docs-readme-gen
- dev-feat/mail-sending-plugin-hook
- dev-chore/bump-csrf-token-1.7
- dev-fix/csrf-secret-env-var
- dev-shared-config/php-dashboard-kit
- dev-feat/async-http-client
- dev-feat/http-transport-debug-info
- dev-feat/sqlite-pragma-support
- dev-feat/retry-client-and-safe-resume
- dev-fix/head-request-nobody
- dev-feat/csrf-origin-proof-support
- dev-feat/flash-messages-for-auth-events
- dev-chore/require-real-ip-resolver-2.3
This package is auto-updated.
Last update: 2026-11-17 23:36:57 UTC
README
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
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">© {{ "now"|date("Y") }} {{ app_name }}</footer> {% endblock %}
See docs/templating.md for the full reference.
Index
Classes
CachingPdoβrafalmasiarek\DashboardKit\CacheCachingStatementβrafalmasiarek\DashboardKit\CacheArrayQueryCacheDriverβrafalmasiarek\DashboardKit\Cache\DriverNullQueryCacheDriverβrafalmasiarek\DashboardKit\Cache\DriverPdoQueryCacheDriverβrafalmasiarek\DashboardKit\Cache\DriverSqlTableExtractorβrafalmasiarek\DashboardKit\CacheTransactionStateβrafalmasiarek\DashboardKit\CacheAuthControllerβrafalmasiarek\DashboardKit\ControllersPasswordResetControllerβrafalmasiarek\DashboardKit\ControllersSettingsControllerβrafalmasiarek\DashboardKit\ControllersUserControllerβrafalmasiarek\DashboardKit\ControllersDashboardβrafalmasiarek\DashboardKitActiveUserExtensionβrafalmasiarek\DashboardKit\ExtensionFormSlotRegistryβrafalmasiarek\DashboardKit\ExtensionSettingsSectionRegistryβrafalmasiarek\DashboardKit\ExtensionSuspendedUserExtensionβrafalmasiarek\DashboardKit\ExtensionUserActionRegistryβrafalmasiarek\DashboardKit\ExtensionFlashβrafalmasiarek\DashboardKitFlashAuthHookβrafalmasiarek\DashboardKit\HookHookRegistryβrafalmasiarek\DashboardKit\HookHttpMessagePickerβrafalmasiarek\DashboardKit\HttpRequestTimingMiddlewareβrafalmasiarek\DashboardKit\HttpSafeErrorHandlerβrafalmasiarek\DashboardKit\HttpAuditLogβrafalmasiarek\DashboardKit\LogKvLineFormatterβrafalmasiarek\DashboardKit\LogLoggerFactoryβrafalmasiarek\DashboardKit\LogRequestHeadersProcessorβrafalmasiarek\DashboardKit\LogRequestLogSanitizerβrafalmasiarek\DashboardKit\LogSecretRedactionProcessorβrafalmasiarek\DashboardKit\LogStderrLoggerβrafalmasiarek\DashboardKit\LogNullDriverβrafalmasiarek\DashboardKit\Mail\DriverOutboundMailβrafalmasiarek\DashboardKit\Mail\DriverSmtpDriverβrafalmasiarek\DashboardKit\Mail\DriverMailExceptionβrafalmasiarek\DashboardKit\Mail\ExceptionMailMessageβrafalmasiarek\DashboardKit\MailMailerβrafalmasiarek\DashboardKit\MailAuthMiddlewareβrafalmasiarek\DashboardKit\MiddlewareCsrfMiddlewareβrafalmasiarek\DashboardKit\MiddlewareRequestHeadersMiddlewareβrafalmasiarek\DashboardKit\MiddlewareRoleMiddlewareβrafalmasiarek\DashboardKit\MiddlewareSessionMiddlewareβrafalmasiarek\DashboardKit\MiddlewareCollectionβrafalmasiarek\DashboardKit\ModelModelβrafalmasiarek\DashboardKit\ModelQueryBuilderβrafalmasiarek\DashboardKit\ModelRawβrafalmasiarek\DashboardKit\ModelModuleRegistryβrafalmasiarek\DashboardKit\ModuleDashboardUserColumnsProviderβrafalmasiarek\DashboardKit\SchemaModuleSchemaBuilderβrafalmasiarek\DashboardKit\SchemaPasswordResetSchemaProviderβrafalmasiarek\DashboardKit\SchemaSchemaInspectorβrafalmasiarek\DashboardKit\SchemaSchemaStateManagerβrafalmasiarek\DashboardKit\SchemaSeedRunnerβrafalmasiarek\DashboardKit\SchemaUserFieldsSchemaProviderβrafalmasiarek\DashboardKit\SchemaSecretRegistryβrafalmasiarek\DashboardKit\SecurityLazyPhpSessionTransportβrafalmasiarek\DashboardKit\TransportCsrfExtensionβrafalmasiarek\DashboardKit\TwigDashboardExtensionβrafalmasiarek\DashboardKit\TwigPasswordStrengthβrafalmasiarek\DashboardKit\UtilsSystemClockβrafalmasiarek\DashboardKit\UtilsTimezoneClockβrafalmasiarek\DashboardKit\UtilsUuidβrafalmasiarek\DashboardKit\UtilsUuidUserIdPolicyβrafalmasiarek\DashboardKit\Utils
Interfaces
QueryCacheDriverInterfaceβrafalmasiarek\DashboardKit\CacheMailDriverInterfaceβrafalmasiarek\DashboardKit\Mail\DriverMailerInterfaceβrafalmasiarek\DashboardKit\MailClockInterfaceβrafalmasiarek\DashboardKit\Utils
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function invalidate(string $tags): void
No-op invalidation.
| Param | Type | Description |
|---|---|---|
$tags |
string |
β |
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()
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()
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()
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()
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()
public function flush(): void
Removes all entries from the cache table unconditionally.
prune()
PdoQueryCacheDriver prune()
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()
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()
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()
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()
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()
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()
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()
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()
private function stripComments(string $sql): string
Remove SQL line comments (--) and block comments (/* β¦ * /).
| Param | Type | Description |
|---|---|---|
$sql |
string |
β |
Returns: string
tokenize()
SqlTableExtractor tokenize()
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()
private function unquote(string $token): string
Strip surrounding backticks from a token.
| Param | Type | Description |
|---|---|---|
$token |
string |
β |
Returns: string
isIdentifier()
SqlTableExtractor isIdentifier()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function index(Request $request, Response $response): Response
Renders the settings page.
| Param | Type | Description |
|---|---|---|
$request |
Request |
β |
$response |
Response |
β |
Returns: Response
changePassword()
SettingsController changePassword()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function run(): void
Runs the application. Call this as the last statement in public/index.php.
getApp()
Dashboard getApp()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function __construct(Flash $flash)
| Param | Type | Description |
|---|---|---|
$flash |
Flash |
β |
onLogoutExpired()
FlashAuthHook onLogoutExpired()
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()
public function __construct(?LoggerInterface $logger)
| Param | Type | Description |
|---|---|---|
$logger |
?LoggerInterface |
β |
on()
HookRegistry on()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
private function statusFromException(Throwable $e): int
Map an exception to an HTTP status code.
| Param | Type | Description |
|---|---|---|
$e |
Throwable |
β |
Returns: int
wantsJson()
SafeErrorHandler wantsJson()
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()
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()
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()
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()
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()
public function __construct(LoggerInterface $logger)
| Param | Type | Description |
|---|---|---|
$logger |
LoggerInterface |
PSR-3 logger receiving audit entries. |
register()
AuditLog register()
public function register(User $user): void
Logs a successful user registration.
| Param | Type | Description |
|---|---|---|
$user |
User |
Newly registered user. |
login()
AuditLog login()
public function login(User $user): void
Logs a successful login.
| Param | Type | Description |
|---|---|---|
$user |
User |
Authenticated user. |
logout()
AuditLog logout()
public function logout(User $user): void
Logs a logout.
| Param | Type | Description |
|---|---|---|
$user |
User |
User who logged out. |
passwordChanged()
AuditLog passwordChanged()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function formatBatch(array $records): string
Formats a batch of log records.
| Param | Type | Description |
|---|---|---|
$records |
LogRecord[] |
β |
Returns: string
escapeValue()
KvLineFormatter escapeValue()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function __invoke(LogRecord $record): LogRecord
| Param | Type | Description |
|---|---|---|
$record |
LogRecord |
β |
Returns: LogRecord
redact()
SecretRedactionProcessor redact()
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()
public function __construct(string $minLevel)
| Param | Type | Description |
|---|---|---|
$minLevel |
string |
Minimum log level to output (PSR-3 level constant). |
log()
StderrLogger log()
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()
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()
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()
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()
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()
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()
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()
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()
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()
private function __construct(string $toEmail)
| Param | Type | Description |
|---|---|---|
$toEmail |
string |
Recipient address. |
to()
MailMessage to()
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()
public function subject(string $subject): self
Sets the email subject line.
| Param | Type | Description |
|---|---|---|
$subject |
string |
β |
Returns: self
template()
MailMessage template()
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()
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()
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()
public function html(string $html): self
Sets an explicit HTML body, bypassing Twig rendering.
| Param | Type | Description |
|---|---|---|
$html |
string |
β |
Returns: self
text()
MailMessage text()
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()
public function replyTo(string $email): self
Sets the Reply-To address.
| Param | Type | Description |
|---|---|---|
$email |
string |
β |
Returns: self
attach()
MailMessage attach()
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()
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()
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()
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()
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()
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()
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()
public function references(array $messageIds): self
Sets the References header.
| Param | Type | Description |
|---|---|---|
$messageIds |
list<string> |
Without angle brackets. |
Returns: self
envelopeFrom()
MailMessage envelopeFrom()
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()
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()
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()
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
getTemplate()
MailMessage getTemplate()
public function getTemplate(): ?string
Returns: string\|null
getVariables()
MailMessage getVariables()
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()
public function getHtmlBody(): ?string
Returns: string\|null
getTextBody()
MailMessage getTextBody()
public function getTextBody(): ?string
Returns: string\|null
getAttachments()
MailMessage getAttachments()
public function getAttachments(): array
Returns: list<array{path: string, name?: string, mimeType?: string}>
getRawBody()
MailMessage getRawBody()
public function getRawBody(): ?RawMimeBody
Returns: RawMimeBody\|null
getCc()
MailMessage getCc()
public function getCc(): array
Returns: list<array{email: string, name?: string}>
getBcc()
MailMessage getBcc()
public function getBcc(): array
Returns: list<array{email: string, name?: string}>
getEmbeds()
MailMessage getEmbeds()
public function getEmbeds(): array
Returns: list<array{path: string, cid: string, name?: string, mimeType?: string}>
getCustomHeaders()
MailMessage getCustomHeaders()
public function getCustomHeaders(): array
Returns: array<string, string>
getMessageId()
MailMessage getMessageId()
public function getMessageId(): ?string
Returns: string\|null
getInReplyTo()
MailMessage getInReplyTo()
public function getInReplyTo(): ?string
Returns: string\|null
getReferences()
MailMessage getReferences()
public function getReferences(): array
Returns: list<string>
getEnvelopeFrom()
MailMessage getEnvelopeFrom()
public function getEnvelopeFrom(): ?string
Returns: string\|null
getDebugLineCallback()
MailMessage getDebugLineCallback()
public function getDebugLineCallback(): ?\Closure
Returns: \Closure(string): β void|null
getCorrelationId()
MailMessage getCorrelationId()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function __construct(RequestHeadersProcessor $processors)
| Param | Type | Description |
|---|---|---|
$processors |
RequestHeadersProcessor |
β |
process()
RequestHeadersMiddleware process()
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()
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()
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()
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()
public function __construct(array $items)
| Param | Type | Description |
|---|---|---|
$items |
list<T> |
Items in this collection. |
count()
Collection count()
public function count(): int
Returns the number of items in the collection.
Returns: int
getIterator()
Collection getIterator()
public function getIterator(): \ArrayIterator
Returns an iterator over the items.
Returns: \ArrayIterator<int, T>
offsetExists()
Collection offsetExists()
public function offsetExists(mixed $offset): bool
| Param | Type | Description |
|---|---|---|
$offset |
int |
β |
Returns: bool
offsetGet()
Collection offsetGet()
public function offsetGet(mixed $offset): mixed
| Param | Type | Description |
|---|---|---|
$offset |
int |
β |
Returns: T
offsetSet()
Collection offsetSet()
public function offsetSet(mixed $offset, mixed $value): void
| Param | Type | Description |
|---|---|---|
$offset |
int|null |
β |
$value |
T |
β |
offsetUnset()
Collection offsetUnset()
public function offsetUnset(mixed $offset): void
| Param | Type | Description |
|---|---|---|
$offset |
int |
β |
first()
Collection first()
public function first(): mixed
Returns the first item, or null when the collection is empty.
Returns: T\|null
last()
Collection last()
public function last(): mixed
Returns the last item, or null when the collection is empty.
Returns: T\|null
isEmpty()
Collection isEmpty()
public function isEmpty(): bool
Returns true when the collection contains no items.
Returns: bool
toArray()
Collection toArray()
public function toArray(): array
Converts every Model item to an associative array; passes other values through.
Returns: list<mixed>
filter()
Collection filter()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public static function all(): Collection
Returns all non-trashed rows in the table as a Collection of model instances.
Returns: Collection
where()
Model where()
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()
public static function withTrashed(): QueryBuilder
Starts a query that also matches soft-deleted rows.
Returns: QueryBuilder
onlyTrashed()
Model onlyTrashed()
public static function onlyTrashed(): QueryBuilder
Starts a query that matches only soft-deleted rows.
Returns: QueryBuilder
usesSoftDeletes()
Model usesSoftDeletes()
public static function usesSoftDeletes(): bool
Whether this model soft-deletes instead of removing rows outright.
Returns: bool
getDeletedAtColumn()
Model getDeletedAtColumn()
public static function getDeletedAtColumn(): string
Column name soft-deletes are written to.
Returns: string
newQuery()
Model newQuery()
protected static function newQuery(): QueryBuilder
Builds a fresh, unconditioned query for this model's table.
Returns: QueryBuilder
on()
Model on()
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()
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()
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()
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()
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()
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()
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()
protected static function now(): string
Current timestamp in the format written to created_at/updated_at columns.
Returns: string
create()
Model create()
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()
public function __get(string $name): mixed
Reads an attribute value with type casting applied.
| Param | Type | Description |
|---|---|---|
$name |
string |
β |
Returns: mixed
__set()
Model __set()
public function __set(string $name, mixed $value): void
Sets an attribute value.
| Param | Type | Description |
|---|---|---|
$name |
string |
β |
$value |
mixed |
β |
__isset()
Model __isset()
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()
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()
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()
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()
public function toArray(): array
Returns all attributes as an associative array with casts applied.
Returns: array<string, mixed>
save()
Model save()
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()
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()
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()
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()
public function trashed(): bool
Whether this instance is currently soft-deleted.
Returns: bool
prunable()
Model prunable()
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()
protected function pruning(): void
Called on each row before prune() force-deletes it. Override to clean up owned resources (files, cache, ...).
prune()
Model prune()
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()
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()
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()
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()
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()
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()
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()
public function withTrashed(): static
Includes soft-deleted rows in the result, alongside normal ones.
Returns: static
onlyTrashed()
QueryBuilder onlyTrashed()
public function onlyTrashed(): static
Restricts the result to soft-deleted rows only.
Returns: static
where()
QueryBuilder where()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function limit(int $limit): static
Sets the maximum number of rows to return.
| Param | Type | Description |
|---|---|---|
$limit |
int |
β |
Returns: static
offset()
QueryBuilder offset()
public function offset(int $offset): static
Sets the row offset for pagination.
| Param | Type | Description |
|---|---|---|
$offset |
int |
β |
Returns: static
orderBy()
QueryBuilder orderBy()
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()
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()
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()
public function count(): int
Returns the total number of matching rows.
Returns: int
max()
QueryBuilder max()
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()
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()
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()
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()
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()
public function forceDelete(): int
Deletes every matching row outright in one statement, bypassing soft deletes.
Returns: int β Number of rows affected.
update()
QueryBuilder update()
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()
private function buildSelect(): array
Builds the full SELECT SQL string and parameter list.
Returns: array{sql: string, params: list<mixed>}
joinSql()
QueryBuilder joinSql()
private function joinSql(): string
Joins accumulated join()/leftJoin() clauses into one SQL fragment.
Returns: string
buildWhere()
QueryBuilder buildWhere()
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()
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()
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()
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()
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()
public function all(): array
Returns all registered modules sorted by order.
Returns: array<string, array<string, mixed>>
find()
ModuleRegistry find()
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()
public function navbarItems(): array
Returns modules that should appear in the navigation bar.
Returns: array<string, array<string, mixed>>
resolvePath()
ModuleRegistry resolvePath()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function __construct(array $fields)
| Param | Type | Description |
|---|---|---|
$fields |
array<string, array{label: string, type: string, max: int, required: bool}> |
β |
additionalSchema()
UserFieldsSchemaProvider additionalSchema()
public function additionalSchema(string $driver): array
| Param | Type | Description |
|---|---|---|
$driver |
string |
PDO driver name. |
Returns: list<string>
sqlType()
UserFieldsSchemaProvider sqlType()
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). |
addValue()
SecretRegistry addValue()
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()
public static function addValues(iterable $values): void
Register multiple secret values at once.
| Param | Type | Description |
|---|---|---|
$values |
iterable<string> |
β |
primeFromConfig()
SecretRegistry primeFromConfig()
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()
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()
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()
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()
public function __construct(string $key)
| Param | Type | Description |
|---|---|---|
$key |
string |
$_SESSION key (default: 'auth_token'). |
initialize()
LazyPhpSessionTransport initialize()
public function initialize(): void
No-op β session is started lazily on first access.
get()
LazyPhpSessionTransport get()
public function get(): ?string
Returns the stored token, starting the session if not yet active.
Returns: string\|null
set()
LazyPhpSessionTransport set()
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()
public function clear(): void
Removes the token from the session, starting it if not yet active.
ensureSession()
LazyPhpSessionTransport ensureSession()
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()
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()
public function getFunctions(): array
Returns: list<TwigFunction>
renderField()
CsrfExtension renderField()
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()
public function getFunctions(): array
Returns: list<TwigFunction>
gravatarUrl()
DashboardExtension gravatarUrl()
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()
public function tzId(): string
Resolves the effective timezone identifier.
Returns: string
tz()
ClockInterface tz()
public function tz(): DateTimeZone
Returns the effective DateTimeZone instance.
Returns: DateTimeZone
nowUtc()
ClockInterface nowUtc()
public function nowUtc(): DateTimeImmutable
Returns the current time in UTC.
Returns: DateTimeImmutable
at()
ClockInterface at()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function tzId(): string
Resolves the effective timezone identifier.
Returns: string
tz()
TimezoneClock tz()
public function tz(): DateTimeZone
Returns the effective DateTimeZone instance.
Returns: DateTimeZone
now()
TimezoneClock now()
public function now(): DateTimeImmutable
{@inheritdoc}
Returns: DateTimeImmutable
nowUtc()
TimezoneClock nowUtc()
public function nowUtc(): DateTimeImmutable
Returns the current time in UTC.
Returns: DateTimeImmutable
at()
TimezoneClock at()
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()
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()
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()
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()
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()
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()
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()
public static function v4(): string
Generates a cryptographically random UUID v4.
Returns: string β UUID in xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx format.
isValid()
Uuid isValid()
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()
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()
public function idColumnDefinition(string $driver): string
| Param | Type | Description |
|---|---|---|
$driver |
string |
β |
Returns: string