Laravel Segment is an opinionated, approach to integrating Segment into your Laravel application.

Overview

Laravel Segment

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status Total Downloads

Laravel Segment Logo Banner

Laravel Segment is an opinionated, approach to integrating Segment into your Laravel application.

Installation

You can install the package via composer:

composer require octohk/laravel-segment

You can publish the config file with:

php artisan vendor:publish --provider="Octohook\LaravelSegment\LaravelSegmentServiceProvider"

This is the contents of the published config file, which should be located at config/segment.php:

return [
    'enabled' => env('SEGMENT_ENABLED', true),

    /**
     * This is your Segment API write key. It can be
     * found under Source > Settings > Api Keys
     */
    'write_key' => env('SEGMENT_WRITE_KEY', null),

    /**
     * Should the Segment service defer all tracking
     * api calls until after the response, sending
     * everything using the bulk/batch api?
     */
    'defer' => env('SEGMENT_DEFER', false),

    /**
     * Should the Segment service be run in safe mode.
     * Safe mode will only report errors in sending
     * when safe mode is off exceptions are thrown
     */
    'safe_mode' => env('SEGMENT_SAFE_MODE', true),
];

Setting your write key

Your write key is the API key given to you by Segment which can be found under your PHP source settings; https://app.segment.com/{your-workspace-name}/sources/{your-source-name}/settings/keys in the Segment UI.

What is a Segment User

When we talk about a 'user' in the context of this package we mean any object that implements the Octohook\LaravelSegment\Contracts\CanBeIdentifiedForSegment contract the package comes with a trait (and the interface) you can attach to your default User model;

use Illuminate\Database\Eloquent\Model;
use Octohook\LaravelSegment\Traits\HasSegmentIdentityByKey;
use Octohook\LaravelSegment\Contracts\CanBeIdentifiedForSegment;

class User extends Model implements CanBeIdentifiedForSegment
{
    use HasSegmentIdentityByKey;
}

Using this trait will automagically use your users' primary key as the identifier that is sent to Segment. Alternatively, you can implement your own instance of the public function getSegmentIdentifier(): string; method on your User model and not use the trait.

Globally identifying users

If you are sending Segment events in multiple places through your application and through-out a request it might make sense to globally identify a user to make it more convenient when making tracking calls.

use Octohook\LaravelSegment\Facades\Segment;

Segment::setGlobalUser($user);

Globally setting context

Segment allows you to send (context)[https://segment.com/docs/connections/spec/common/#context] with your tracking events too, you can set a global context that applies to all tracking events.

use Octohook\LaravelSegment\Facades\Segment;

Segment::setGlobalContext([
    'ip' => '127.0.0.1',
    'locale' => 'en-US',
    'screen' => [
        'height' => 1080,
        'width' => 1920,
    ],
]);

Here have some convenience

Laravel Segment ships with a middleware that you can apply in your HTTP Kernal that will handle the setting of the global user and some sensible global context too. It should be simple to extend this middleware and adjust for your needs if you want to add to the default context provided.

    'api' => [
        // ... other middleware
        Octohook\LaravelSegment\Middleware\ApplySegmentGlobals::class
    ],

Usage

For tracking events

use Octohook\LaravelSegment\Facades\Segment;

Segment::forUser($user)->track('User Signed Up', [
    'source' => 'Product Hunt',
]);

// If you have set a global user you can
// use the simpler provided syntax.
Segment::track('User Signed Up', [
    'source' => 'Product Hunt',
]);

For identifying users

use Octohook\LaravelSegment\Facades\Segment;

Segment::forUser($user)->identify([
    'last_logged_in' => '2021-03-24 20:05:30',
    'latest_subscription_amount' => '$24.60',
]);

// If you have set a global user you can
// use the simpler provided syntax.
Segment::identify([
    'last_logged_in' => '2021-03-24 20:05:30',
    'latest_subscription_amount' => '$24.60',
]);

Misc

Deferring

When you start to fire many events in your application, even 2-3 per request it can be hyper-beneficial to turn on deferring (see config). When deferring is enabled, the service will store all of your tracking events triggered through-out the request or process and then send them in batch after your application has responded to your user. This happens during the Laravel termination.

Safe mode

By default safe-mode is turned on. When safe-mode is active it will swallow any exceptions thrown when making the HTTP request to Segmenta and report them automatically to the exception handler, allow your app to continue running. When disabled then the exception will be thrown.

Testing

./vendor/bin/pest

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.

Credits

License

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

You might also like...
Smeify is a Stable Automated Solution for Airtime and Data businesses in Nigeria, this package helps you integrate smeify easily into your laravel application.

Smeify is a Stable Automated Solution for Airtime and Data businesses in Nigeria, this package helps you integrate smeify easily into your laravel application.

Easily integrate single-database multi tenant features into your Laravel application
Easily integrate single-database multi tenant features into your Laravel application

Laravel Tenant Aware Easily integrate single-database multi tenant features into your Laravel application. Installation You can install the package vi

Integrate likes, bookmarks, favorites, reactions and custom made marks into your application
Integrate likes, bookmarks, favorites, reactions and custom made marks into your application

Laravel Markable This package allows you to easily add the markable feature to your application, as for example likes, bookmarks, favorites and so on.

Integrates libphonenumber into your Symfony application

PhoneNumberBundle This bundle is a fork of misd-service-development/phone-number-bundle. As this project doesn't look maintained anymore, we decided t

Take a look into your Laravel views
Take a look into your Laravel views

Xray - Take a look into your Laravel views When your Laravel project grows, so do the Laravel views. Sometimes it might be hard to figure out, which p

Laravel package to normalize your data before saving into the database.

This package helps you normalize your data in order to save them into the database. The Goal is to having separate classes that handle the data normalization, and thus can be tested independently.

Filament Plugin to help implement Cloudflare turnstile into your forms.
Filament Plugin to help implement Cloudflare turnstile into your forms.

Filament Turnstile Filament Turnstile, is a plugin to help you implement the Cloudflare turnstile. This plugin uses Laravel Turnstile Behind the scene

Automatically load your helpers in your laravel application.

Laravel AutoHelpers Automatically load your helpers in your laravel application. Installation You can install the package via composer: composer requi

Package to parse DNA kit files, and import them into Laravel

Package to parse DNA kit files, and import them into Laravel

Comments
  • Laravel 9 Support

    Laravel 9 Support

    This is a very well-written package, well done. I'm wondering if it's still actively being maintained as #4 has been merged but not yet released.

    If you are looking for maintainers I'm happy to help out.

    opened by patrickomeara 3
  • Update ApplySegmentGlobals to call $next

    Update ApplySegmentGlobals to call $next

    From the docs:

    To pass the request deeper into the application (allowing the middleware to "pass"), you should call the $next callback with the $request.

    The middleware currently does not call $next which makes it break with multiple middleware.

    opened by Daanra 1
  • Don't always use the `batch` API

    Don't always use the `batch` API

    Currently the service, regardless of whether defer is active or not, will always use the batch API. This is a bit of a lazy approach, instead we can determine whether we are deferring and decide which endpoint to use.

    So, when not deferring, we would use the specific track and identify endpoints to ensure we are doing things that make a little more sense and 'as expected' for the developer.

    enhancement 
    opened by slashequip 0
  • Provide a simple way to `fake` the facade for testing

    Provide a simple way to `fake` the facade for testing

    As the Segment facade already extends Laravel's facade system there is baked in support for shouldReceive and spy but due to the way forUser works it adds friction during testing.

    Based around the way core Laravel facades handle these situations it would be nice to follow suit and add a fake method to the facade that makes it simpler to perform assertions on events that have been pushed to the service. For example assertTrackPushed or assertIdentifyPushed (something like that at least). This would 10x the DX during testing.

    enhancement 
    opened by slashequip 0
Releases(v1.1.0)
  • v1.1.0(Oct 24, 2022)

  • v1.0.0(May 16, 2022)

    After a transfer of ownership from Octohook to SlashEquip (co-founder of Octohook), and some testing in production, the Laravel Segment package can be released as v1 🎉

    Source code(tar.gz)
    Source code(zip)
  • v1.0.0-beta.2(Mar 28, 2021)

  • v1.0.0-beta.1(Mar 27, 2021)

Owner
Octohook
We are a platform that helps you bring visibility to your web hooks.
Octohook
Laravel package integrating PHP Flasher into Livewire applications

A powerful and flexible flash notifications system for PHP, Laravel, Symfony ?? PHP Flasher helps you to add flash notifications to your PHP projects.

PHP Flasher 9 Jul 5, 2022
A package for integrating Lazerpay services with your laravel application

This is my package lazerpay-laravel This is where your description should go. Limit it to a paragraph or two. Consider adding a small example. Support

Abdulsalam Ishaq 5 Dec 22, 2022
An opinioned approach to extend the laravel seed classes.

Laravel Seed Extender A highly opinioned way to work with the laravel seeder. Installation Require the package using composer: composer require touhid

Touhidur Rahman 9 Jan 20, 2022
A simple and modern approach to stream filtering in PHP

clue/stream-filter A simple and modern approach to stream filtering in PHP Table of contents Why? Support us Usage append() prepend() fun() remove() I

Christian Lück 1.5k Dec 29, 2022
A simple to use opinionated ERP package to work with Laravel

Laravel ERP A simple to use opinionated ERP package to work with Laravel Installation You can install the package via composer: composer require justs

Steve McDougall 16 Nov 30, 2022
An opinionated blade template formatter for Laravel that respects readability

blade-formatter An opinionated blade template formatter for Laravel that respects readability Online Demo Features Automatically Indents markup inside

Shuhei Hayashibara 277 Dec 26, 2022
An opinionated support package for Laravel, that provides flexible and reusable helper methods and traits for commonly used functionality.

Support An opinionated support package for Laravel, that provides flexible and reusable helper methods and traits for commonly used functionality. Ins

Ian Olson 3 Apr 14, 2021
An opinionated feature flags package for Laravel

This package provides an opinionated API for implementing feature flags in your Laravel applications. It supports application-wide features as well as model specific feature flags.

Ryan Chandler 157 Nov 24, 2022
An opinionated package to create slugs for Eloquent models

Generate slugs when saving Eloquent models This package provides a trait that will generate a unique slug when saving any Eloquent model. $model = new

Spatie 1.1k Jan 4, 2023
Laravel package that converts your application into a static HTML website

phpReel Static Laravel Package phpReel Static is a simple Laravel Package created and used by phpReel that converts your Laravel application to a stat

phpReel 16 Jul 7, 2022