README

Defer sending event data to Keen.io until after a request has been fulfilled–automatically and transparently.

This package provides a light wrapper around the Keen PHP client, as well as a middleware configured to defer sending event data to Keen until after each request has been fulfilled. That means that as the number of tracked events increase, the impact on request time remains virtually non-existent. For convenience, the middleware can also track every request automatically.

• Features
• Installation
• Configuration
• Getting started
• Automatic tracking of every request
  • Data enrichment
  • Using your own middleware
  • Skipping requests
• Type-hinting

Features

• Deferred event tracking 🙌
• Optional automatic tracking of every request
• Support data enrichment out of the box
  • IP to Geo
  • User Agent
  • Referrer
• Extensible middleware
• Option to ignore specific HTTP status codes (e.g. 100, 302, etc.)
  • Or any request based on custom logic
• More to come!

Installation

Install the Laravel + Keen package using Composer:

$ composer require frnkly/laravel-keen

This will also install the Keen PHP client as a dependency.

Configuration

Your Keen project ID and keys should be defined in the config/services.php configuration file, but will usually come from the environment configuration:

return [
    // Other 3rd-party Services
    // ...
    
    // Add your Keen information here
    'keen' => [
        'id'     => env('KEEN_PROJECT_ID'),
        'master' => env('KEEN_MASTER_KEY'),
        'write'  => env('KEEN_WRITE_KEY'),
    ],
];

And in your .env file, you might add something like:

KEEN_PROJECT_ID=your-project-id
KEEN_MASTER_KEY=your-master-key
KEEN_WRITE_KEY=your-write-key

Getting started

Register the middleware globally in app/Http/Kernel.php:

protected $middleware = [
    // Other Middleware
    // ...
    
    \Frnkly\LaravelKeen\Middleware::class,
];

Or within a middleware group:

protected $middlewareGroups = [
    'web' => [
        // Other "Web" Middleware
        // ...
        
        \Frnkly\LaravelKeen\Middleware::class,
    ],

    'api' => [
        // Other "API" Middleware
        // ...
        
        \Frnkly\LaravelKeen\Middleware::class,
    ],
];

Thanks to package discovery in Laravel 5.5, the service provider should already be available. It can also be manually registered through the config/app.php configuration file:

'providers' => [
    // Other Service Providers
    // ...

    Frnkly\LaravelKeen\ServiceProvider::class,
]

Automatic tracking of every request

Automatic tracking is enabled by default. You may disable this behaviour through the configuration file:

'keen' => [
    // Other Keen options
    // ...
    
    'track_requests' => false,
],

Data enrichment

To automatically add data enrichment to each request, use the following configuration options:

'keen' => [
    // Other Keen settings
    // ...
    
    'addons' => [
        'ip_to_geo'       => true,  // IP to Geo parser
        'ua_parser'       => true,  // User Agent parser
        'referrer_parser' => true,  // Referrer parser
    ],
],

Each data enrichment object will appear in your Keen stream under the same name as above (i.e. ip_to_geo and ua_parser).

Using your own middleware

The included middleware makes it simple to extend and gain more granular control over the data that gets sent to Keen. You can create your own middleware using Artisan, and then have it extend \Frnkly\LaravelKeen\Middleware:

$ php artisan make:middleware TracksRequests

Inside the new middleware, override the protected method buildRequestEventData:

<?php

namespace App\Http\Middleware;

class TracksRequests extends \Frnkly\LaravelKeen\Middleware
{
    /**
     * Data for "request" event.
     *
     * @param \Illuminate\Http\Request  $request
     * @param \Illuminate\Http\Response $response
     */
    protected function buildRequestEventData($request, $response)
    {
        parent::buildRequestEventData($request, $response);
        
        // Add or overwrite values.
        $host      = 'staging';
        $overwrite = true;
        $this->client->addRequestEventData('host', $host, $overwrite)
        
        // Add parameters to array values.
        ->addRequestEventParams([
            'user' => $request->user()->id
        ])
        ->addRequestEventParams([
            'mime' => $request->getMimeType('html')
        ], 'response')
        
        // Add data enrichment.
        ->addRequestEventData('target_url', 'https://example.com')
        ->enrichRequestEvent([
            'name'  => 'url_parser',
            'output'=> 'url_parser',
            'input' => ['url' => 'target_url']
        ]);
    }
}

Remember to update your app/Http/Kernel.php file to use your own middleware class instead of the pre-configured one.

Skipping requests

Some response codes do not need to be tracked, such as redirects. You can configure a list of response codes to ignore in your middleware:

/**
 * @var array
 */
protected $skipResponseCodes = [
    100,
    101,
    301,
    302,
    307,
    308,
];

You may also override the shouldRun method in the middleware:

/**
 * Determines if the middleware should run or not.
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  \Illuminate\Http\Response $response
 * @return bool
 */
protected function shouldRun($request, $response) : bool
{
    if (! parent::shouldRun($request, $response)) {
        return false;
    }
    
    // Define your own custom logic here.
    // ...

    return true;
}

Type-hinting

The LaravelKeen client can be type-hinted in the constructor of any class that is resolved by the container:

namespace App\Events;

use App\Events\OrderShipped;
use Frnkly\LaravelKeen\Client;

class OrderShipped
{
    private $client;
    
    public function __construct(Client $client)
    {
        // The client can now be accessed by all methods in this class.
        $this->client = $client;
    }
    
    public function handle(OrderShipped $event)
    {
        // By adding a deferred event, we can continue working on the request
        // without waiting on a reply back from Keen.io. The event will be
        // processed once the request is done–automatically and transparently.
        $this->client->addDeferredEvent('order-shipped', [
            // Event data...
        ]);
    }
}

Controllers can also take advantage of method injection:

use Frnkly\LaravelKeen\Client;

class UserController extends Controller
{
    public function store(Client $client)
    {
        $client->addDeferredEvent('new-user', [
            // Event data...
        ]);
    }
}

This project is licensed under the MIT license.

I'd love to hear your comments or questions about this project. If you have an idea on how to improve it, create an issue or get in touch.