README

Server side analytics for your Laravel application or website. No cookies, no tracking :)

Vision

There are a lot of choices out there when it comes to analytics for your web project. With the progress of GDPR, a focus on privacy has emerged. Consumers are now learning that they can be tracked across the web, and are not appreciative of this.

As you develop your next website or project, you may wish to add analytics so you can see how many pageviews, etc you're getting. You may not care to track how a specific visitor got to your website, or the actions they took once they were there. You just want some basic metrics on the activity on your web project.

You've come to the right place.

Goals

Handled entirely by the backend: this means no client-side JS to add to your site, which means no impact on performance for your users
Write operations should not impact request performance
Customizable: we'll track the main aspects of a request (path, status, params, duration, user, etc), but also allow you to attach extra data to a request (such as which entity in your database was accessed or metadata)
Ships with a default dashboard to view your data: we'll give you a default dashboard (and seperate route) to view your data
Accessible API: in addition to a default dashboard, we'll expose an API you can use to pull custom metrics out of your data

Installation

You can install the package via composer:

composer require ohseesoftware/laravel-server-analytics

Publish the package (config, assets, etc):

php artisan vendor:publish --provider="OhSeeSoftware\LaravelServerAnalytics\LaravelServerAnalyticsServiceProvider"

Review the configuration file and make changes as necessary:

config/laravel-server-analytics.php

Run database migrations:

php artisan migrate

Usage

Basic Usage

For basic request tracking, there's no custom code you need to add to your application other than including the middleware:

// Kernel.php

protected $middleware = [
  // ... other middlware here
  \OhSeeSoftware\LaravelServerAnalytics\Http\Middleware\LogRequest::class,
];

If you want to only track a specific middleware group, add it to that group instead of the global $middleware variable.

Tracking authenticated user

v3.0.0+

By default, the package will automatically track the authenticated user who made the request. This is stored directly in the analytics table in the user_id column.

The default migration assumes you users are stored in a users table with a BIGINT field type for the primary key. If your users are not stored like that, you should write your own migration. The package also assumes your User model is located at App\User. If yours is located in a difference namespace, you can update the user_model key in the published config file.

When logging a request, the package will use this code to insert the user_id into the analytics table:

$userId = $request->user()?->id ?? null

Excluding Routes

If you'd like to exclude specific routes (or wildcards) from being tracked, you can do so via the addRouteExclusions() method:

// AppServiceProvider

use OhSeeSoftware\LaravelServerAnalytics\Facades\ServerAnalytics;

public function boot()
{
    // Do not track `/home` or `/admin/*` routes
    ServerAnalytics::addRouteExclusions([
      '/home',
      '/admin/*'
    ]);
}

Excluding Request Methods

If you'd like to exclude specific request methods from being tracked, you can do so via the addMethodExclusions() method:

// AppServiceProvider

use OhSeeSoftware\LaravelServerAnalytics\Facades\ServerAnalytics;

public function boot()
{
    // Do not track `POST` or `PUT` requests
    ServerAnalytics::addMethodExclusions(['POST', 'PUT']);
}

Excluding Requests From Bots

If you'd like to exclude requests from bots/crawlers, you can set the ignore_bot_requests configuration value to true.

We use the Crawl Detect package to detect bots/crawlers.

// config/laravel-server-analytics.php

return [
    'ignore_bot_requests' => true
];

Request hooks

We provide took optional hooks that you can use to automatically associate extra data with your analytics records: addMetaHook and addRelationHook. Both hooks return an array of data that should be associated to the analytics record. You can add as many of each as you'd like throughout your request's lifecycle.

addMetaHook example:

ServerAnalytics::addMetaHook(function (RequestDetails $requestDetails) {
    return [
        'key' => 'some-key',
        'value' => 'some-value'
    ];
});

addRelationHook example:

ServerAnalytics::addRelationHook(function (RequestDetails $requestDetails) use ($post) {
    return [
        'model' => $post,
        'reason' => 'Post that was deleted.'
    ];
});

There's also helper methods available which call the above hooks for you:

ServerAnalytics::addMeta('test', 'value');

ServerAnalytics::addRelation($post);

Providing Custom Request Details

We provide sensible defaults for pulling details for the request. However, if you need to pull the details in a different manner, you can provide a custom implementation of the RequestDetails class:

// CustomRequestDetails.php

use OhSeeSoftware\LaravelServerAnalytics\RequestDetails;

class CustomRequestDetails extends RequestDetails
{
    public function getMethod(): string
    {
        // Set the stored `method` as "TEST" for all requests
        return 'TEST';
    }
}

There's a config value, request_details_class, which you can set to the FQN of your request details class. We will attempt to resolve that class out of the container when logging requests.

Querying Analytics Records

You can use the AnalyticsRepository to query data out of the analytics tables. If you need to build a custom query, you can use the query() method on the repository instance.

use OhSeeSoftware\LaravelServerAnalytics\Repositories\AnalyticsRepository;

public function loadAnalytics(AnalyticsRepository $analytics)
{
    $records = $analytics->query()->where('method', 'GET')->get();
}

There's also a couple query scopes setup on the Analytics model.

Filter Analytics records that are related to the a given model:

use OhSeeSoftware\LaravelServerAnalytics\Models\Analytics;

$analytics = Analytics::relatedTo($user);

Filter Analytics records that have metadata with a given key:

use OhSeeSoftware\LaravelServerAnalytics\Models\Analytics;

$analytics = Analytics::hasMeta('foo');

Filter Analytics records that have a given metadata key/value pair:

use OhSeeSoftware\LaravelServerAnalytics\Models\Analytics;

$analytics = Analytics::withMetaValue('foo', 'bar');

Testing

./vendor/bin/phpunit

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email security@ohseesoftware.com instead of using the issue tracker.

ohseesoftware / laravel-server-analytics

Maintainers

Details