rafalmasiarek / dashboard-kit-addon-mail-tracking
Open-tracking pixel addon for dashboard-kit outgoing email — listens on the mail_sending hook to append a pixel to every message, independent of which controller sends it.
Package info
github.com/rafalmasiarek/php-dashboard-kit-addon-mail-tracking
pkg:composer/rafalmasiarek/dashboard-kit-addon-mail-tracking
Requires
- php: >=8.2
- rafalmasiarek/dashboard-kit: >=6.1
- rafalmasiarek/real-ip-resolver: ^2.3
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 23:46:54 UTC
README
Open-tracking pixel addon for dashboard-kit
outgoing email — listens on the mail_sending hook to append a pixel to every message,
independent of which controller sends it.
License
Business Source License 1.1.
Source available; commercial use restricted until 2099-01-01.
See LICENSE for full details.
For alternative licensing, contact us.
Authors
MailTrackingAddon
final class — rafalmasiarek\DashboardKitMailTracking\MailTrackingAddon · source
Open-tracking pixel addon for dashboard-kit outgoing email.
Registers a HookRegistry::addListener('mail_sending', ...) listener, so every email sent through Mailer::send() — regardless of which controller calls it — gets a pixel appended before delivery. A failure in this listener (e.g. a DB insert error) is caught and logged by the hook dispatcher itself and never blocks the actual send; it previously replaced the whole MailerInterface binding with a decorator, which could break delivery entirely if the decorator itself failed. Entirely inert (no schema sync, no route, no listener) unless config['mail_tracking']['base_url'] is set.
Usage (app bootstrap, after Dashboard::create()): MailTrackingAddon::register($app, $container, $config);
Hooks emitted (via dashboard-kit's HookRegistry, no-op if unregistered): mail_opened (string $toEmail, string $mailType, string $token, string $ip, ?string $correlationId)
Register with: $dashboard->on('mail_opened', function (...) { ... });
| Method | Visibility | Returns | Summary |
|---|---|---|---|
register() |
public static | void |
— |
syncSchema() |
private static | void |
Creates/updates the mail_tracking table via ModuleSchemaBuilder, the same mechanism and config['schema_defaults'] convention core modules use. |
registerHook() |
private static | void |
Registers the pixel-appending listener on Mailer's 'mail_sending' hook. A thrown exception here is caught and logged by HookRegistry::emit() itself, so a failure (e.g. this INSERT) never blocks the actual delivery that follows. |
registerRoute() |
private static | void |
Registers the pixel endpoint. The response is identical (a 1x1 PNG) whether or not the token matched or was already opened — the HTTP response itself never discloses tracking state to the client. |
register()
MailTrackingAddon register()
public static function register(App $app, ContainerInterface $container, array $config): void
| Param | Type | Description |
|---|---|---|
$app |
App |
Slim application instance. |
$container |
ContainerInterface |
DI container. |
$config |
array<string, mixed> |
Application config. |
syncSchema()
MailTrackingAddon syncSchema()
private static function syncSchema(ContainerInterface $container, array $config): void
Creates/updates the mail_tracking table via ModuleSchemaBuilder, the same mechanism and config['schema_defaults'] convention core modules use.
| Param | Type | Description |
|---|---|---|
$container |
ContainerInterface |
— |
$config |
array<string, mixed> |
— |
registerHook()
MailTrackingAddon registerHook()
private static function registerHook(ContainerInterface $container, string $baseUrl): void
Registers the pixel-appending listener on Mailer's 'mail_sending' hook. A thrown exception here is caught and logged by HookRegistry::emit() itself, so a failure (e.g. this INSERT) never blocks the actual delivery that follows.
| Param | Type | Description |
|---|---|---|
$container |
ContainerInterface |
— |
$baseUrl |
string |
— |
registerRoute()
MailTrackingAddon registerRoute()
private static function registerRoute(App $app, ContainerInterface $container): void
Registers the pixel endpoint. The response is identical (a 1x1 PNG) whether or not the token matched or was already opened — the HTTP response itself never discloses tracking state to the client.
| Param | Type | Description |
|---|---|---|
$app |
App |
— |
$container |
ContainerInterface |
— |