Add Notification channel (#13)

Author: slashequip

README.md

@@ -158,6 +158,51 @@ Segment::identify([
 ]);
 ```
 
+### Laravel Notifications
+This package includes an out-of-the-box notification channel, to allow you to use Laravel's built-in notification
+feature. To send Segment events to users as notifications, generate your notification as normal;
+
+```
+php artisan make:notification UserSubscribed
+```
+
+You must ensure your notification implements the `CanNotifyViaSegment` interface, and add the required `toSegment`
+method. Then you can configure the `via` method to include the `SegmentChannel` class.
+
+You can then adjust the `toSegment` method to return the event you'd like. 
+
+```
+use Illuminate\Notifications\Notification;
+use SlashEquip\LaravelSegment\Contracts\CanBeIdentifiedForSegment;
+use SlashEquip\LaravelSegment\Contracts\CanBeSentToSegment;
+use SlashEquip\LaravelSegment\Contracts\CanNotifyViaSegment;
+use SlashEquip\LaravelSegment\Notifications\SegmentChannel;
+use SlashEquip\LaravelSegment\SimpleSegmentEvent;
+
+class UserSubscribed extends Notification implements CanNotifyViaSegment
+{
+    use Notifiable;
+
+    public function __construct(
+    ) {
+    }
+
+    public function via(object $notifiable): array
+    {
+        return [SegmentChannel::class];
+    }
+
+    public function toSegment(CanBeIdentifiedForSegment $notifiable): CanBeSentToSegment
+    {
+        return new SimpleSegmentEvent(
+            $notifiable,
+            'User Subscribed',
+            ['some' => 'thing'],
+        );
+    }
+}
+```
+
 ## Misc
 
 ### Deferring
@@ -167,7 +212,7 @@ through-out the request or process and then send them in batch after your applic
 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
+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.
 

phpstan.neon.dist

@@ -8,3 +8,5 @@ parameters:
 
     # Level 9 is the highest level
     level: 6
+
+    checkGenericClassInNonGenericObjectType: false

src/Contracts/CanNotifyViaSegment.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace SlashEquip\LaravelSegment\Contracts;
+
+interface CanNotifyViaSegment
+{
+    public function toSegment(CanBeIdentifiedForSegment $notifiable): CanBeSentToSegment;
+}

src/Contracts/SegmentServiceContract.php

@@ -8,10 +8,19 @@ interface SegmentServiceContract
 {
     public function setGlobalUser(CanBeIdentifiedForSegment $globalUser): void;
 
+    /**
+     * @param  array<string, mixed>  $globalContext
+     */
     public function setGlobalContext(array $globalContext): void;
 
+    /**
+     * @param  array<string, mixed>  $eventData
+     */
     public function track(string $event, array $eventData = null): void;
 
+    /**
+     * @param  array<string, mixed>  $identifyData
+     */
     public function identify(array $identifyData = null): void;
 
     public function forUser(CanBeIdentifiedForSegment $user): PendingUserSegment;

src/Exceptions/NotifiableCannotBeIdentifiedForSegmentException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace SlashEquip\LaravelSegment\Exceptions;
+
+use RuntimeException;
+
+class NotifiableCannotBeIdentifiedForSegmentException extends RuntimeException
+{
+    //
+}

src/Facades/Fakes/SegmentFake.php

@@ -16,27 +16,39 @@ class SegmentFake implements SegmentServiceContract
 {
     private CanBeIdentifiedForSegment $user;
 
+    /** @var array<string, mixed> */
     private ?array $context = [];
 
+    /** @var array<int, SimpleSegmentEvent> */
     private array $events = [];
 
+    /** @var array<int, SimpleSegmentIdentify> */
     private array $identities = [];
 
     public function setGlobalUser(CanBeIdentifiedForSegment $globalUser): void
     {
         $this->user = $globalUser;
     }
 
+    /**
+     * @param  array<string, mixed>  $globalContext
+     */
     public function setGlobalContext(array $globalContext): void
     {
         $this->context = $globalContext;
     }
 
+    /**
+     * @param  array<string, mixed>  $identifyData
+     */
     public function identify(?array $identifyData = []): void
     {
         $this->identities[] = new SimpleSegmentIdentify($this->user, $identifyData);
     }
 
+    /**
+     * @param  array<string, mixed>  $eventData
+     */
     public function track(string $event, array $eventData = null): void
     {
         $this->events[] = new SimpleSegmentEvent($this->user, $event, $eventData);
@@ -158,6 +170,14 @@ public function assertNothingTracked(): void
         PHPUnit::assertEmpty($events, $events->count().' events were found unexpectedly.');
     }
 
+    /**
+     * @return array<string, mixed>
+     */
+    public function getContext(): ?array
+    {
+        return $this->context;
+    }
+
     private function identities(Closure $callback = null): Collection
     {
         $identities = collect($this->identities);

src/Notifications/SegmentChannel.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace SlashEquip\LaravelSegment\Notifications;
+
+use SlashEquip\LaravelSegment\Contracts\CanBeIdentifiedForSegment;
+use SlashEquip\LaravelSegment\Contracts\CanNotifyViaSegment;
+use SlashEquip\LaravelSegment\Exceptions\NotifiableCannotBeIdentifiedForSegmentException;
+use SlashEquip\LaravelSegment\Facades\Segment;
+
+class SegmentChannel
+{
+    public function send(object $notifiable, CanNotifyViaSegment $notification): void
+    {
+        if (! $notifiable instanceof CanBeIdentifiedForSegment) {
+            throw new NotifiableCannotBeIdentifiedForSegmentException();
+        }
+
+        Segment::push($notification->toSegment($notifiable));
+    }
+}

tests/Stubs/SegmentTestNotification.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace SlashEquip\LaravelSegment\Tests\Stubs;
+
+use Illuminate\Notifications\Notification;
+use Illuminate\Support\Str;
+use SlashEquip\LaravelSegment\Contracts\CanBeIdentifiedForSegment;
+use SlashEquip\LaravelSegment\Contracts\CanBeSentToSegment;
+use SlashEquip\LaravelSegment\Contracts\CanNotifyViaSegment;
+use SlashEquip\LaravelSegment\Notifications\SegmentChannel;
+use SlashEquip\LaravelSegment\SimpleSegmentEvent;
+
+class SegmentTestNotification extends Notification implements CanNotifyViaSegment
+{
+    public function __construct(
+        private int $number
+    ) {
+    }
+
+    public function via(object $notifiable): array
+    {
+        return [SegmentChannel::class];
+    }
+
+    public function toSegment(CanBeIdentifiedForSegment $notifiable): CanBeSentToSegment
+    {
+        return new SimpleSegmentEvent(
+            $notifiable,
+            Str::of(class_basename(static::class))
+                ->snake()
+                ->replace('_', ' ')
+                ->title(),
+            ['some' => 'thing'],
+        );
+    }
+}

tests/Stubs/SegmentTestUser.php

@@ -2,10 +2,13 @@
 
 namespace SlashEquip\LaravelSegment\Tests\Stubs;
 
+use Illuminate\Notifications\Notifiable;
 use SlashEquip\LaravelSegment\Contracts\CanBeIdentifiedForSegment;
 
 class SegmentTestUser implements CanBeIdentifiedForSegment
 {
+    use Notifiable;
+
     public function __construct(
         private string $id
     ) {

tests/Unit/SegmentNotificationTest.php

@@ -0,0 +1,33 @@
+<?php
+
+use SlashEquip\LaravelSegment\Contracts\SegmentServiceContract;
+use SlashEquip\LaravelSegment\SimpleSegmentEvent;
+use SlashEquip\LaravelSegment\Tests\Stubs\SegmentTestNotification;
+use SlashEquip\LaravelSegment\Tests\Stubs\SegmentTestUser;
+
+it('can send a notification to a notifiable entity', function () {
+    // Given we have a notifiable entity
+    $notifiable = new SegmentTestUser('123456');
+
+    // And we are spying on the service
+    $service = test()->spy(SegmentServiceContract::class);
+
+    // When we notify the entity
+    $notifiable->notify(new SegmentTestNotification(987654));
+
+    // Then the service was called appropriately
+    $service->shouldHaveReceived('push')
+        ->with(Mockery::on(function ($arg) {
+            if (! $arg instanceof SimpleSegmentEvent) {
+                return false;
+            }
+
+            $payload = $arg->toSegment();
+
+            return $payload->user->getSegmentIdentifier() === '123456'
+                && $payload->event === 'Segment Test Notification'
+                && count($payload->data) === 1
+                && $payload->data['some'] === 'thing';
+        }))
+        ->once();
+});