README

Laravel User Logger with Pennant-based experiment measurement.

Requirements

• Laravel
• laravel/pennant

Installation

Using Composer is currently the only supported way to install this package.

composer require topoff/laravel-user-logger

Getting started

Publish the package config:

php artisan vendor:publish --tag=config

If you want to, create a dedicated user-logger database connection in config/database.php:

        'user-logger' => [
            'driver' => 'mysql',
            'host' => env('DB_HOST', '127.0.0.1'),
            'port' => env('DB_PORT', '3306'),
            'database' => 'userlogger',
            'username' => env('DB_USERNAME', ''),
            'password' => env('DB_PASSWORD', ''),
            'unix_socket' => env('DB_SOCKET', ''),
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix' => '',
            'strict' => true,
            'engine' => null,
        ],

Run migrations:

php artisan migrate

Set up Pennant (required for experiment variant storage/resolution):

php artisan vendor:publish --provider="Laravel\Pennant\PennantServiceProvider"

Then set the Pennant DB connection to your user-logger connection in config/pennant.php:

'stores' => [
    'database' => [
        'driver' => 'database',
        'connection' => 'user-logger',
        'table' => 'features',
    ],
],

Run migrations again so the Pennant features table is created:

php artisan migrate

Experiments

Experiment measurement uses laravel/pennant. Configure tracked features in config/user-logger.php:

'experiments' => [
    'enabled' => true,
    'features' => [
        'landing-page-headline',
        'checkout-flow',
    ],
    'conversion_events' => [
        'conversion',
    ],
    'conversion_entity_types' => [],
    'nova' => [
        'enabled' => true,
    ],
    'pennant' => [
        'store' => 'user-logger',
        'connection' => 'user-logger',
        'table' => 'pennant_features',
        'auto_install' => true,
        'scope' => 'session',
    ],
],

Pennant storage is installed by this package via migrations on the user-logger connection (pennant_features table).
This makes feature resolutions shareable across multiple apps that point to the same user-logger database. With auto_install=true (default), the package also creates the Pennant table automatically at boot if it is missing.

Flush all measured experiment data:

php artisan user-logger:flush

Nova

When Nova is installed and experiments.nova.enabled is true, the package auto-registers the ExperimentMeasurement Nova resource.

If your app defines a fully custom Nova::mainMenu(...), you must also add the resource manually in that menu.

Testing

composer test

Performance Profiling

You can enable runtime profiling logs in config/user-logger.php:

'performance' => [
    'enabled' => true,
    'log_queries' => true,
    'slow_ms' => 500,
],

When enabled, the package logs:

• total request duration (request_duration_ms) - server-side time until response
• user-logger boot duration (boot_duration_ms)
• user-logger internal segment timings (user_logger.segments)
• optional query counters (queries_total, queries_user_logger)
• skip reason (skip_reason) when logging is bypassed

Slow request warnings can be emitted with slow_ms (set 0 to disable warnings).

User-Agent Parsing Performance

matomo/device-detector supports cache-backed parsing:

'user_agent' => [
    'cache' => true,
],

• cache: uses Laravel's default cache store to speed up parser internals.

The package automatically skips DeviceDetector bot matching when the request was already classified as a crawler via CrawlerDetect.

Update

This package uses https://github.com/snowplow-referer-parser/referer-parser. Use that repository to update the known referer list when needed.