Updates for Laravel Usage

.gitignore

@@ -1,3 +1,4 @@
 composer.lock
 /vendor/
 /.php_cs.cache
+.idea

README.md

@@ -12,16 +12,112 @@ composer require userlist/userlist-laravel
 
 ## Configuration
 
+After installation, you can publish the configuration file for Userlist:
+
+```bash
+php artisan vendor:publish --provider Userlist\Laravel\UserlistServiceProvider
+```
+
+You can then edit the `config/userlist.php` file if needed.
+
+```php
+# Adjust if your User/Team models are found elsewhere
+return [
+    'user_model' => \App\Models\User::class,
+    'company_model' => \App\Models\Team::class,
+    'push_id' => env('USERLIST_PUSH_ID'),
+    'push_key' => env('USERLIST_PUSH_KEY'),
+];
+```
+
+Userlist will attempt to transform your `User` and `Team` (Company) models to data it can understand automatically (an associated array that can be encoded as JSON)..
+
+However, if you need or want to customize the User/Team (Company)/Event objects sent to Userlist, you can add a public `toUserList()` method to your Model or Event classes:
+
+```php
+class User extends Authenticatable
+{    
+    public function toUserlist()
+    {
+        return [
+            'identifier' => "user-$this->getKey()",
+            'email' => $user->email,
+            'signed_up_at' => $user->created_at,
+            'properties' => [
+                'name' => $user->name
+            ],
+            // Assuming allTeams() is a method of this class
+            'companies' => $this->allTeams()->map(function(Team $team) {
+                // Assuming the team also has a `toUserList()` method
+                return $team->toUserList();
+            })->toArray();
+        ];
+    }
+}
+```
 
 ## Usage
 
+### Importing Current Data
+
+This package includes some commands to help you load your current data (users and companies) into Userlist. After using these commands, you should also implement code
+to register users and companies to Userlist as they are created or updated.
+
+The `userlist:import` command imports all users and companies into Userlist. These uses the configuration for `user_model` 
+and `company_model` to decide which Eloquent models to include.
+
+```bash
+# This command calls the following under the hood
+#  userlist:import:companies
+#  userlist:import:users
+php artisan userlist:import
+```
+
+The `userlist:import:companies` command will use the Eloquent model defined by the `company_model` configuration to import all companies.
+
+In Laravel, this is often the `App\Models\Team` model.
+
+```bash
+php artisan userlist:import:companies
+```
+
+The `userlist:import:users` command will use the Eloquent model defined by the `user_model` configuration to import all users.
+
+In Laravel, this is often the `App\Models\User` model.
+
+```bash
+php artisan userlist:import:users
+```
+
+### Tracking Companies
+
+You can track companies (adding and updating) by "pushing" their records to Userlist.
+
+
+```php
+// In Laravel, Userlist companies are often "teams"
+$team = App\Models\Team::find(1);
+app(Userlist\Laravel\Contracts\Push::class)->company($team);
+```
+
+These will transform the model to a "jsonable" associated array using the model's `toUserList()` method (if defined), else fall back to its default transformation logic for the class.
 
 ### Tracking Users
 
+You can track users (adding and updating) by "pushing" their records to Userlist.
+
+
+```php
+$user = App\Models\User::find(1);
+app(Userlist\Laravel\Contracts\Push::class)->user($user);
+```
+
+These will transform the model to a "jsonable" associated array using the model's `toUserList()` method (if defined), else fall back to its default transformation logic for the class.
 
 ### Tracking Events
 
 
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/userlist/userlist-laravel. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

config/userlist.php

@@ -1,8 +1,8 @@
 <?php
 
 return [
-    'user_model' => \App\Model\User::class,
-    'company_model' => \App\Model\Company::class,
+    'user_model' => \App\Models\User::class,
+    'company_model' => \App\Models\Team::class,
     'push_id' => env('USERLIST_PUSH_ID'),
     'push_key' => env('USERLIST_PUSH_KEY')
 ];

src/Console/Commands/ImportBaseCommand.php

@@ -5,7 +5,7 @@
 use Illuminate\Console\Command;
 use Userlist\Laravel\Contracts\Push as Userlist;
 
-class ImportBaseCommand extends Command
+abstract class ImportBaseCommand extends Command
 {
     /**
      * The userlist client
@@ -31,4 +31,18 @@ public function handle(Userlist $userlist)
             $this->import($entity);
         }
     }
+
+    /**
+     * Import some data based on an Eloquent model
+     * @param $model
+     * @return null
+     */
+    abstract protected function import($model);
+
+    /**
+     * Return a full-qualified class name
+     * e.g. \App\Models\User
+     * @return string
+     */
+    abstract protected function modelClass();
 }

src/Console/Commands/ImportCompaniesCommand.php

@@ -18,8 +18,8 @@ class ImportCompaniesCommand extends ImportBaseCommand
      */
     protected $description = 'Imports all existing companies into Userlist';
 
-    protected function import($company) {
-      $this->userlist->company($company);
+    protected function import($model) {
+      $this->userlist->company($model);
     }
 
     protected function modelClass() {

src/Console/Commands/ImportUsersCommand.php

@@ -18,8 +18,8 @@ class ImportUsersCommand extends ImportBaseCommand
      */
     protected $description = 'Imports all existing users into Userlist';
 
-    protected function import($user) {
-      $this->userlist->user($user);
+    protected function import($model) {
+      $this->userlist->user($model);
     }
 
     protected function modelClass() {

src/Services/CompanyTransform.php

@@ -6,13 +6,22 @@
 use Illuminate\Support\Str;
 
 class CompanyTransform implements Transform {
-    public function transform($company) {
-        $modelName = Str::slug((class_basename(get_class($company))));
+
+    /**
+     * @param $entity
+     * @return array
+     */
+    public function transform($entity) {
+        if (method_exists($entity, 'toUserlist')) {
+            return $entity->toUserlist();
+        }
+
+        $modelName = Str::slug((class_basename(get_class($entity))));
 
         return [
-            'identifier' => "$modelName-$company->id",
-            'name' => $company->name,
-            'signed_up_at' => $company->created_at,
+            'identifier' => "$modelName-$entity->id",
+            'name' => $entity->name,
+            'signed_up_at' => $entity->created_at,
         ];
     }
 }

src/Services/EventTransform.php

@@ -2,6 +2,7 @@
 
 namespace Userlist\Laravel\Services;
 
+use Illuminate\Support\Str;
 use Userlist\Laravel\Contracts\EventTransform as Transform;
 use Userlist\Laravel\Contracts\UserTransform;
 use Userlist\Laravel\Contracts\CompanyTransform;
@@ -13,10 +14,32 @@ public function __construct(UserTransform $userTransform, CompanyTransform $comp
         $this->companyTransform = $companyTransform;
     }
 
-    public function transform($event) {
-        $event['user'] = $this->userTransform->transform($event['user']);
-        $event['company'] = $this->companyTransform->transform($event['company']);
+    public function transform($entity) {
+        if (method_exists($entity, 'toUserlist')) {
+            return $entity->toUserlist();
+        }
 
-        return $event;
+        if ($entity instanceof \Illuminate\Contracts\Support\Arrayable) {
+            return $entity->toArray();
+        }
+
+        // If the event doesn't have a way to give us data, we'll attempt to build it
+        // from the available information.
+        // The event ideally has a public property "user", "team", or "company"
+        $data = [];
+
+        // An event should only have a user OR a company identifier
+        if (property_exists($entity, 'user')) {
+            $data['user'] = $this->userTransform->transform($entity->user)['identifier'];
+        } elseif (property_exists($entity, 'company')) {
+            $data['company'] = $this->companyTransform->transform($entity->company)['identifier'];
+        } elseif (property_exists($entity, 'team')) {
+            $data['company'] = $this->companyTransform->transform($entity->team)['identifier'];
+        }
+
+        $modelName = Str::slug((class_basename(get_class($entity))));
+        $data['name'] = "event-$modelName";
+
+        return $data;
     }
 }

src/Services/UserTransform.php

@@ -6,15 +6,24 @@
 use Illuminate\Support\Str;
 
 class UserTransform implements Transform {
-    public function transform($user) {
-        $modelName = Str::slug((class_basename(get_class($user))));
+
+    /**
+     * @param $entity
+     * @return array
+     */
+    public function transform($entity) {
+        if (method_exists($entity, 'toUserlist')) {
+            return $entity->toUserlist();
+        }
+
+        $modelName = Str::slug((class_basename(get_class($entity))));
 
         return [
-            'identifier' => "$modelName-$user->id",
-            'email' => $user->email,
-            'signed_up_at' => $user->created_at,
+            'identifier' => "$modelName-$entity->id",
+            'email' => $entity->email,
+            'signed_up_at' => $entity->created_at,
             'properties' => [
-                'name' => $user->name
+                'name' => $entity->name
             ]
         ];
     }