Add support for anonymous users (slashequip#22)

slashequip · web-flow · commit 4dee39c90ed7 · 2025-02-20T21:05:12.000Z
* Add support for anonymous users

* clean

* start Cursor support.

* improve actions

* attempt to fix actions

* Update docs
diff --git a/.cursor/rules/cursor-rules-location.mdc b/.cursor/rules/cursor-rules-location.mdc
@@ -0,0 +1,75 @@
+---
+description: Rules for placing and organizing Cursor rule files in the repository.
+globs: *.mdc
+---
+# Cursor Rules Location
+
+Rules for placing and organizing Cursor rule files in the repository.
+
+<rule>
+name: cursor_rules_location
+description: Standards for placing Cursor rule files in the correct directory
+filters:
+  # Match any .mdc files
+  - type: file_extension
+    pattern: "\\.mdc$"
+  # Match files that look like Cursor rules
+  - type: content
+    pattern: "(?s)<rule>.*?</rule>"
+  # Match file creation events
+  - type: event
+    pattern: "file_create"
+
+actions:
+  - type: reject
+    conditions:
+      - pattern: "^(?!\\.\\/\\.cursor\\/rules\\/.*\\.mdc$)"
+        message: "Cursor rule files (.mdc) must be placed in the .cursor/rules directory"
+
+  - type: suggest
+    message: |
+      When creating Cursor rules:
+
+      1. Always place rule files in PROJECT_ROOT/.cursor/rules/:
+         ```
+         .cursor/rules/
+         ├── your-rule-name.mdc
+         ├── another-rule.mdc
+         └── ...
+         ```
+
+      2. Follow the naming convention:
+         - Use kebab-case for filenames
+         - Always use .mdc extension
+         - Make names descriptive of the rule's purpose
+
+      3. Directory structure:
+         ```
+         PROJECT_ROOT/
+         ├── .cursor/
+         │   └── rules/
+         │       ├── your-rule-name.mdc
+         │       └── ...
+         └── ...
+         ```
+
+      4. Never place rule files:
+         - In the project root
+         - In subdirectories outside .cursor/rules
+         - In any other location
+
+examples:
+  - input: |
+      # Bad: Rule file in wrong location
+      rules/my-rule.mdc
+      my-rule.mdc
+      .rules/my-rule.mdc
+
+      # Good: Rule file in correct location
+      .cursor/rules/my-rule.mdc
+    output: "Correctly placed Cursor rule file"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>
diff --git a/.github/workflows/code-style.yml b/.github/workflows/code-style.yml
@@ -1,6 +1,6 @@
 name: Code Style
 
-on: [push]
+on: [pull_request]
 
 jobs:
   code-style:
@@ -13,7 +13,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.1'
+          php-version: '8.2'
           extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo
           coverage: none
 
diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
@@ -1,6 +1,6 @@
 name: run-tests
 
-on: [push, pull_request]
+on: [pull_request]
 
 jobs:
   test:
@@ -9,9 +9,9 @@ jobs:
       fail-fast: true
       matrix:
         os: [ubuntu-latest]
-        php: [8.3]
+        php: ['8.2','8.3', '8.4']
         laravel: [11.*]
-        stability: [prefer-stable]
+        stability: ['prefer-stable']
         include:
           - laravel: 11.*
             testbench: 9.*
diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml
@@ -1,13 +1,9 @@
 name: Static Analysis
 
-on:
-  push:
-    paths:
-      - '**.php'
-      - 'phpstan.neon.dist'
+on: [pull_request]
 
 jobs:
-  psalm:
+  phpstan:
     name: static-analysis
     runs-on: ubuntu-latest
     steps:
@@ -16,7 +12,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.1'
+          php-version: '8.2'
           extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick
           coverage: none
 
diff --git a/.php_cs.dist b/.php_cs.dist
diff --git a/README.md b/README.md
@@ -170,6 +170,29 @@ Segment::identifyNow('User Signed Up', [
 ]);
 ```
 
+### Anonymous users
+
+Segment allows you to track events for users that are not yet users in your system, they call these anonymous users.
+
+To track events for anonymous users you can use apply the `ShouldBeAnonymouslyIdentified` interface to any `CanBeIdentifiedForSegment` implementation.
+
+```php
+use SlashEquip\LaravelSegment\Contracts\CanBeIdentifiedForSegment;
+use SlashEquip\LaravelSegment\Contracts\ShouldBeAnonymouslyIdentified;
+
+class SegmentAnonymousTestUser implements CanBeIdentifiedForSegment, ShouldBeAnonymouslyIdentified
+{
+}
+```
+
+For convenience, the package comes with a `SimpleSegmentAnonymousUser` class that implements the `ShouldBeAnonymouslyIdentified` interface.
+
+```php
+use SlashEquip\LaravelSegment\SimpleSegmentAnonymousUser;
+
+Segment::forUser(new SimpleSegmentAnonymousUser('123'))->track('Kitchen sink used');
+```
+
 ### 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;
diff --git a/composer.json b/composer.json
@@ -14,17 +14,16 @@
         }
     ],
     "require": {
-        "php": "^8.1",
+        "php": "^8.2",
         "guzzlehttp/guzzle": "^7.8",
-        "illuminate/contracts": "^9.0|^10.0|^11.0"
+        "illuminate/contracts": "^10.0|^11.0"
     },
     "require-dev": {
         "laravel/pint": "^1.18",
         "mockery/mockery": "^1.6",
         "nunomaduro/larastan": "^2.0",
-        "orchestra/testbench": "^7.25|^8.5|^9.0",
-        "pestphp/pest": "^2.36",
-        "vimeo/psalm": "^5.26"
+        "orchestra/testbench": "^8.5|^9.0",
+        "pestphp/pest": "^2.36"
     },
     "autoload": {
         "psr-4": {
diff --git a/psalm.xml.dist b/psalm.xml.dist
diff --git a/src/Contracts/SegmentServiceContract.php b/src/Contracts/SegmentServiceContract.php
@@ -33,7 +33,6 @@ public function identify(?array $identifyData = null): void;
      */
     public function identifyNow(?array $identifyData = null): void;
 
-
     public function forUser(CanBeIdentifiedForSegment $user): PendingUserSegment;
 
     public function push(CanBeSentToSegment $segment): void;
diff --git a/src/Contracts/ShouldBeAnonymouslyIdentified.php b/src/Contracts/ShouldBeAnonymouslyIdentified.php
@@ -0,0 +1,5 @@
+<?php
+
+namespace SlashEquip\LaravelSegment\Contracts;
+
+interface ShouldBeAnonymouslyIdentified {}
diff --git a/src/Facades/Segment.php b/src/Facades/Segment.php
@@ -29,7 +29,7 @@
  * @method static void assertEventTracked(string $event,Closure|int|null $callback = null)
  * @method static void assertNotTracked(Closure $callback = null)
  * @method static void assertNothingTracked()
-
+ *
  * @see \SlashEquip\LaravelSegment\SegmentService
  * @see SegmentFake
  */
@@ -42,7 +42,7 @@ protected static function getFacadeAccessor(): string
 
     public static function fake(): SegmentFake
     {
-        return tap(new SegmentFake(), function (SegmentFake $fake) {
+        return tap(new SegmentFake, function (SegmentFake $fake) {
             static::swap($fake);
         });
     }
diff --git a/src/Notifications/SegmentChannel.php b/src/Notifications/SegmentChannel.php
@@ -12,7 +12,7 @@ class SegmentChannel
     public function send(object $notifiable, CanNotifyViaSegment $notification): void
     {
         if (! $notifiable instanceof CanBeIdentifiedForSegment) {
-            throw new NotifiableCannotBeIdentifiedForSegmentException();
+            throw new NotifiableCannotBeIdentifiedForSegmentException;
         }
 
         Segment::push($notification->toSegment($notifiable));
diff --git a/src/PendingUserSegment.php b/src/PendingUserSegment.php
@@ -7,15 +7,10 @@
 
 class PendingUserSegment
 {
-    private SegmentServiceContract $service;
-
-    private CanBeIdentifiedForSegment $user;
-
-    public function __construct(SegmentServiceContract $service, CanBeIdentifiedForSegment $user)
-    {
-        $this->service = $service;
-        $this->user = $user;
-    }
+    public function __construct(
+        private SegmentServiceContract $service,
+        private CanBeIdentifiedForSegment $user
+    ) {}
 
     /**
      * @param  array<string, mixed>|null  $eventData
diff --git a/src/SegmentService.php b/src/SegmentService.php
@@ -7,6 +7,7 @@
 use SlashEquip\LaravelSegment\Contracts\CanBeIdentifiedForSegment;
 use SlashEquip\LaravelSegment\Contracts\CanBeSentToSegment;
 use SlashEquip\LaravelSegment\Contracts\SegmentServiceContract;
+use SlashEquip\LaravelSegment\Contracts\ShouldBeAnonymouslyIdentified;
 use SlashEquip\LaravelSegment\Enums\SegmentPayloadType;
 use SlashEquip\LaravelSegment\ValueObjects\SegmentPayload;
 use Throwable;
@@ -115,10 +116,8 @@ public function terminate(): void
         }
 
         // Send the batch request.
-        $response = Http::withHeaders([
-            'Authorization' => 'Bearer '.base64_encode($this->getWriteKey()),
-            'Content-Type' => 'application/json',
-        ])
+        $response = Http::asJson()
+            ->withToken(base64_encode($this->getWriteKey()))
             ->post(self::BATCH_URL, [
                 'batch' => $this->getBatchData(),
                 'context' => $this->globalContext,
@@ -137,9 +136,7 @@ public function terminate(): void
     protected function getBatchData(): array
     {
         return collect($this->payloads)
-            ->map(function (SegmentPayload $payload) {
-                return $this->getDataFromPayload($payload);
-            })
+            ->map(fn (SegmentPayload $payload) => $this->getDataFromPayload($payload))
             ->all();
     }
 
@@ -148,10 +145,12 @@ protected function getBatchData(): array
      */
     protected function getDataFromPayload(SegmentPayload $payload): array
     {
+        $key = $payload->user instanceof ShouldBeAnonymouslyIdentified ? 'anonymousId' : 'userId';
+
         // Initial data.
         $data = [
             'type' => $payload->type->value,
-            'userId' => $payload->user->getSegmentIdentifier(),
+            $key => $payload->user->getSegmentIdentifier(),
             'timestamp' => $payload->timestamp->format('Y-m-d\TH:i:s\Z'),
         ];
 
@@ -171,7 +170,7 @@ protected function getDataFromPayload(SegmentPayload $payload): array
 
     protected function handleResponseErrors(Response $response): void
     {
-        rescue(
+        \rescue(
             callback: function () use ($response) {
                 // If there was an error then it can be
                 // thrown here and we can process.
diff --git a/src/SimpleSegmentAnonymousUser.php b/src/SimpleSegmentAnonymousUser.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace SlashEquip\LaravelSegment;
+
+use SlashEquip\LaravelSegment\Contracts\ShouldBeAnonymouslyIdentified;
+
+class SimpleSegmentAnonymousUser extends SimpleSegmentUser implements ShouldBeAnonymouslyIdentified
+{
+    //
+}
diff --git a/src/SimpleSegmentUser.php b/src/SimpleSegmentUser.php
@@ -0,0 +1,17 @@
+<?php
+
+namespace SlashEquip\LaravelSegment;
+
+use SlashEquip\LaravelSegment\Contracts\CanBeIdentifiedForSegment;
+
+class SimpleSegmentUser implements CanBeIdentifiedForSegment
+{
+    public function __construct(
+        private string $id
+    ) {}
+
+    public function getSegmentIdentifier(): string
+    {
+        return $this->id;
+    }
+}
diff --git a/src/ValueObjects/SegmentPayload.php b/src/ValueObjects/SegmentPayload.php
diff --git a/tests/Stubs/SegmentAnonymousTestUser.php b/tests/Stubs/SegmentAnonymousTestUser.php
diff --git a/tests/Unit/SegmentFakeTest.php b/tests/Unit/SegmentFakeTest.php
diff --git a/tests/Unit/SegmentServiceTest.php b/tests/Unit/SegmentServiceTest.php

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +<?php
++
 +namespace SlashEquip\LaravelSegment\Contracts;
++
 +interface ShouldBeAnonymouslyIdentified {}