Download the PHP package mafrasil/laravel-sonar without Composer

Laravel Sonar - Product Analytics

Laravel Sonar is a powerful product analytics package that makes it easy to track user interactions in your Laravel application. It provides automatic tracking for clicks, hovers, and impressions, with support for custom events.

Features

• 🚀 Automatic event tracking (clicks, hovers, impressions)
• 🎯 Custom event tracking
• ⚡ Efficient batch processing of events
• 🛠️ Optional React components and hooks for easy integration
• 📱 Responsive design support with screen size tracking
• 🔄 Compatible with Inertia.js
• ⚙️ Configurable tracking behavior

Installation

You can install the package via composer:

Then install the package and publish the assets:

This will publish the config file, assets and run the migrations.

You can also publish the config file, assets and run the migrations separately:

You can also publish the views of the dashboard:

Optional: Export React Components

If you're using React, you can export the React components and TypeScript types:

This will create React components and hooks in your application's JavaScript directory.

Usage

Data Attributes

The simplest way to track elements is using data attributes:

React Component (Optional)

If you've exported the React components, you can use the SonarTracker component:

Custom Events

Use the useSonar hook for custom event tracking and configuration:

Server-Side Tracking

You can also track events from your PHP code:

Event Types

The package supports the following event types out of the box:

• click: User clicks on tracked elements
• hover: User hovers over tracked elements (configurable for repeated tracking)
• impression: Element becomes visible in the viewport
• custom: Any custom event you want to track

Configuration

You can customize the package behavior in the config/sonar.php file:

JavaScript Configuration

You can configure the JavaScript behavior globally:

Analytics

Laravel Sonar provides several methods to analyze your collected data. You can use these methods to build dashboards or generate reports.

Available Methods

Dashboard & Analytics

CLI Analytics

The package includes a convenient command-line interface for quick analytics overview:

This is particularly useful for quick analytics checks or automated reporting scripts.

Access Control

By default, the Sonar dashboard is only accessible in the local environment.

You can enable it anytime by setting the SONAR_DASHBOARD_ENABLED environment variable to true.

To allow specific users in other environments, configure the allowed emails in your config/sonar.php:

You can also customize the authorization logic by overriding the viewSonar gate in your AuthServiceProvider:

Dashboard Access

The dashboard is available at /sonar and provides:

• Event type distribution
• Most active pages
• Click and hover rates
• User engagement metrics
• Browser and device statistics
• Screen size distribution
• Detailed element interaction analysis

Using the Facade

The LaravelSonar facade provides various methods for analyzing your tracking data. Here's a comprehensive example:

Available Analytics Methods

Basic Analytics

• getEventsByType(DateTime $startDate = null, DateTime $endDate = null): Get event counts grouped by type
• getTopLocations(int $limit = 10, DateTime $startDate = null): Get most active pages/routes
• getEventTimeline(string $interval = '1 day', DateTime $startDate = null): Get event distribution over time
• getTopEvents(int $limit = 10, string $type = null): Get most triggered events
• getUserEngagement(): Get overall engagement metrics

Detailed Analytics

• getElementStats(int $limit = 10): Get element-specific stats with conversion rates
• getBrowserStats(): Get browser and device usage statistics
• getScreenSizeStats(): Get screen size distribution
• getMetadataStats(string $name): Get detailed metadata analysis for specific elements
• getLocationStats(): Get detailed page interaction statistics

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Inspiration & Acknowledgments

Laravel Sonar was inspired by Pan, a lightweight and privacy-focused PHP product analytics library. While sharing similar core concepts for simple analytics tracking, Laravel Sonar extends the functionality with additional features including:

• Rich metadata support for events
• Built-in analytics dashboard UI
• Advanced analytics reporting capabilities
• Screen size and device tracking
• Detailed user engagement metrics
• React component integration
• And more...

Credits

• mafrasil
• All Contributors

License

The MIT License (MIT). Please see License File for more information.