Improve events, add tests/documentation

Author: rtconner

docs/events.md

@@ -12,7 +12,13 @@ Conner\Tagging\Events\TagRemoved;
 You can add listeners and track these events.
 
 ```php
-\Event::listen(Conner\Tagging\Events\TagAdded::class, function($article){
-	\Log::debug($article->title . ' was tagged');
+\Event::listen(TagAdded::class, function(TagAdded $event){
+	\Log::debug($event->model->title . ' was tagged');
+});
+```
+
+```php
+\Event::listen(TagRemoved::class, function(TagRemoved $event){
+	\Log::debug($event->tagSlug . ' was removed');
 });
 ```

src/Events/TagAdded.php

@@ -1,5 +1,6 @@
 <?php namespace Conner\Tagging\Events;
 
+use Conner\Tagging\Model\Tagged;
 use Conner\Tagging\Taggable;
 use Illuminate\Queue\SerializesModels;
 use Illuminate\Database\Eloquent\Model;
@@ -8,17 +9,26 @@ class TagAdded
 {
     use SerializesModels;
 
-    /** @var \Illuminate\Database\Eloquent\Model **/
+    /** @var Model **/
     public $model;
 
+    /** @var string */
+    public $tagSlug;
+
+    /** @var Tagged */
+    public $tagged;
+
     /**
      * Create a new event instance.
      *
      * @param Taggable|Model $model
-     * @return void
+     * @param string $tagSlug
+     * @param Tagged $tagged
      */
-    public function __construct($model)
+    public function __construct($model, string $tagSlug, Tagged $tagged)
     {
         $this->model = $model;
+        $this->tagSlug = $tagSlug;
+        $this->tagged = $tagged;
     }
 }

src/Events/TagRemoved.php

@@ -10,17 +10,21 @@ class TagRemoved
 {
     use SerializesModels;
 
-    /** @var \Conner\Tagging\Taggable **/
+    /** @var Taggable|Model **/
     public $model;
 
+    /*** @var string */
+    public $tagSlug;
+
     /**
      * Create a new event instance.
      *
      * @param Taggable|Model $model
-     * @return void
+     * @param string $tagSlug
      */
-    public function __construct($model)
+    public function __construct($model, string $tagSlug)
     {
         $this->model = $model;
+        $this->tagSlug = $tagSlug;
     }
 }

src/Taggable.php

@@ -255,7 +255,8 @@ private function addTag($tagName)
         TaggingUtility::incrementCount($tagName, $tagSlug, 1);
 
         unset($this->relations['tagged']);
-        event(new TagAdded($this));
+
+        event(new TagAdded($this, $tagSlug, $tagged));
     }
 
     /**
@@ -273,8 +274,9 @@ private function removeTag($tagName)
             TaggingUtility::decrementCount($tagName, $tagSlug, $count);
         }
 
-        unset($this->relations['tagged']);
-        event(new TagRemoved($this));
+        unset($this->relations['tagged']); // clear the "cache"
+
+        event(new TagRemoved($this, $tagSlug));
     }
 
     /**

tests/CommonUsageTest.php

@@ -3,8 +3,8 @@
 namespace Tests;
 
 use Conner\Tagging\Contracts\TaggableContract;
-use Illuminate\Database\Eloquent\Model as Eloquent;
 use Conner\Tagging\Taggable;
+use Illuminate\Database\Eloquent\Model as Eloquent;
 use Illuminate\Foundation\Testing\WithFaker;
 use Illuminate\Support\Collection;
 
@@ -74,7 +74,7 @@ public function test_retag()
 
     public function test_tag_names_attribute()
     {
-        $stub = $this->book(['tag_names'=>'foo, bar']);
+        $stub = $this->book(['tag_names' => 'foo, bar']);
 
         $stub->save();
 
@@ -118,7 +118,7 @@ public function test_get_tags()
 
     public function test_setting_tag_names_array()
     {
-        $stub = new Book();
+        $stub = $this->book();
         $stub->name = 'test';
         $stub->tag_names = ['foo', 'bar'];
         $stub->save();
@@ -190,8 +190,7 @@ function test_withoutTags()
         $this->assertEquals($three->id, $list[0]->id);
     }
 
-
-    private function book($attributes = []): Book
+    function book($attributes = []): Book
     {
         $attributes = array_merge(['name'=>$this->faker->name], $attributes);
 
@@ -208,6 +207,6 @@ class Book extends Eloquent implements TaggableContract
     use Taggable;
 
     protected $connection = 'testing';
-
+    protected static $unguarded = true;
     public $table = 'books';
 }

tests/EventTests.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace Tests;
+
+use Conner\Tagging\Contracts\TaggableContract;
+use Conner\Tagging\Events\TagAdded;
+use Conner\Tagging\Events\TagRemoved;
+use Conner\Tagging\Taggable;
+use Illuminate\Database\Eloquent\Model as Eloquent;
+use Illuminate\Foundation\Testing\WithFaker;
+
+class EventTests extends TestCase
+{
+    use WithFaker;
+
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        $this->setUpFaker();
+
+        \Schema::create('books', function ($table) {
+            $table->increments('id');
+            $table->string('name');
+            $table->timestamps();
+        });
+    }
+
+    function test_tag_added()
+    {
+        \Event::listen(TagAdded::class, function(TagAdded $event){
+            $this->assertNotEmpty($event->model);
+            $this->assertEquals('test', $event->tagSlug);
+            $this->assertEquals('Test', $event->tagged->tag_name);
+        });
+
+        $book = $this->book();
+        $book->tag('Test');
+    }
+
+    function test_tag_removed()
+    {
+        \Event::listen(TagRemoved::class, function(TagRemoved $event){
+            $this->assertNotEmpty($event->model);
+            $this->assertEquals('test', $event->tagSlug);
+        });
+
+        $book = $this->book();
+        $book->tag('Test');
+
+        $book->untag('Test');
+    }
+
+    function book($attributes = []): Book
+    {
+        $attributes = array_merge(['name'=>$this->faker->name], $attributes);
+
+        return Book::create($attributes);
+    }
+}
+
+/**
+ * @property string name
+ */
+class Book extends Eloquent implements TaggableContract
+{
+    use Taggable;
+
+    protected $connection = 'testing';
+    protected static $unguarded = true;
+    public $table = 'books';
+}