Add Damnit\Exception\Frame::(add|get)Comment(s)

src/Damnit/Exception/Frame.php

@@ -19,6 +19,11 @@ class Frame
      */
     protected $fileContentsCache;
 
+    /**
+     * @var array[]
+     */
+    protected $comments;
+
     /**
      * @param array[]
      */
@@ -81,6 +86,46 @@ class Frame
         return $this->fileContentsCache;
     }
 
+    /**
+     * Adds a comment to this frame, that can be received and
+     * used by other handlers. For example, the PrettyPage handler
+     * can attach these comments under the code for each frame.
+     *
+     * An interesting use for this would be, for example, code analysis
+     * & annotations.
+     *
+     * @param string $message
+     * @param string $context Optional string identifying the origin of the comment
+     */
+    public function addComment($comment, $context = 'global')
+    {
+        $this->comments[] = array(
+            'comment' => $comment,
+            'context' => $context
+        );
+    }
+
+    /**
+     * Returns all comments for this frame. Optionally allows
+     * a filter to only retrieve comments from a specific
+     * context.
+     *
+     * @param  string $filter
+     * @return array[]
+     */
+    public function getComments($filter = null)
+    {
+        $comments = $this->comments;
+
+        if($filter !== null) {
+            $comments = array_filter($comments, function($c) use($filter) {
+                return $c['context'] == $filter;
+            });
+        }
+
+        return $comments;
+    }
+
     /**
      * Returns the contents of the file for this frame as an
      * array of lines, and optionally as a clamped range of lines.
@@ -96,7 +141,7 @@ class Frame
      *
      * @param  int $start
      * @param  int $length
-     * @return array|null
+     * @return string[]|null
      */
     public function getFileLines($start = 0, $length = null)
     {

tests/Damnit/Exception/FrameTest.php

@@ -129,4 +129,54 @@ class FrameTest extends TestCase
         $this->assertEquals($lines[1], '// Line 2');
         $this->assertEquals($lines[2], '// Line 3');
     }
+
+    /**
+     * @covers Damnit\Exception\Frame::addComment
+     * @covers Damnit\Exception\Frame::getComments
+     */
+    public function testGetComments()
+    {
+        $frame    = $this->getFrameInstance();
+        $testComments = array(
+            'Dang, yo!',
+            'Errthangs broken!',
+            'Dayumm!'
+        );
+
+        $frame->addComment($testComments[0]);
+        $frame->addComment($testComments[1]);
+        $frame->addComment($testComments[2]);
+
+        $comments = $frame->getComments();
+
+        $this->assertCount(3, $comments);
+
+        $this->assertEquals($comments[0]['comment'], $testComments[0]);
+        $this->assertEquals($comments[1]['comment'], $testComments[1]);
+        $this->assertEquals($comments[2]['comment'], $testComments[2]);
+    }
+
+    /**
+     * @covers Damnit\Exception\Frame::addComment
+     * @covers Damnit\Exception\Frame::getComments
+     */
+    public function testGetFilteredComments()
+    {
+        $frame    = $this->getFrameInstance();
+        $testComments = array(
+            array('Dang, yo!', 'test'),
+            array('Errthangs broken!', 'test'),
+            'Dayumm!'
+        );
+
+        $frame->addComment($testComments[0][0], $testComments[0][1]);
+        $frame->addComment($testComments[1][0], $testComments[1][1]);
+        $frame->addComment($testComments[2][0], $testComments[2][1]);
+
+        $comments = $frame->getComments('test');
+
+        $this->assertCount(2, $comments);
+        $this->assertEquals($comments[0]['comment'], $testComments[0][0]);
+        $this->assertEquals($comments[1]['comment'], $testComments[1][0]);
+    }
 }