Breadcrumbs

src/Breadcrumbs/Breadcrumb.php

@@ -0,0 +1,186 @@
+<?php
+
+namespace Bugsnag\Breadcrumbs;
+
+use InvalidArgumentException;
+
+class Breadcrumb
+{
+    /**
+     * The navigation type.
+     *
+     * @var string
+     */
+    const NAVIGATION_TYPE = 'navigation';
+
+    /**
+     * The request type.
+     *
+     * @var string
+     */
+    const REQUEST_TYPE = 'request';
+
+    /**
+     * The process type.
+     *
+     * @var string
+     */
+    const PROCESS_TYPE = 'process';
+
+    /**
+     * The log type.
+     *
+     * @var string
+     */
+    const LOG_TYPE = 'log';
+
+    /**
+     * The user type.
+     *
+     * @var string
+     */
+    const USER_TYPE = 'user';
+
+    /**
+     * The state type.
+     *
+     * @var string
+     */
+    const STATE_TYPE = 'state';
+
+    /**
+     * The error type.
+     *
+     * @var string
+     */
+    const ERROR_TYPE = 'error';
+
+    /**
+     * The manual type.
+     *
+     * @var string
+     */
+    const MANUAL_TYPE = 'manual';
+
+    /**
+     * The maximum length of the name.
+     *
+     * @var int
+     */
+    const MAX_LENGTH = 30;
+
+    /**
+     * The maximum size of the breadcrumb.
+     *
+     * @var int
+     */
+    const MAX_SIZE = 4096;
+
+    /**
+     * The timestamp of the breadcrumb.
+     *
+     * @var string
+     */
+    protected $timestamp;
+
+    /**
+     * The name of the breadcrumb.
+     *
+     * @var string
+     */
+    protected $name;
+
+    /**
+     * The type of the breadcrumb.
+     *
+     * @var string
+     */
+    protected $type;
+
+    /**
+     * The meta data of the breadcrumb.
+     *
+     * @var array
+     */
+    protected $metaData;
+
+    /**
+     * Create a new breadcrumb instance.
+     *
+     * @param string $name     the name of the breadcrumb
+     * @param string $type     the type of breadcrumb
+     * @param array  $metaData additional information about the breadcrumb
+     *
+     * @throws \InvalidArgumentException
+     *
+     * @return void
+     */
+    public function __construct($name, $type, array $metaData = [])
+    {
+        if (!is_string($name) || $name === '') {
+            throw new InvalidArgumentException('The breadcrumb name must be a non-empty string.');
+        }
+
+        if (strlen($name) > static::MAX_LENGTH) {
+            throw new InvalidArgumentException(sprintf('The breadcrumb name must be at most %d characters in length.', static::MAX_LENGTH));
+        }
+
+        $types = static::getTypes();
+
+        if (!in_array($type, $types, true)) {
+            throw new InvalidArgumentException(sprintf('The breadcrumb type must be one of the set of %d standard types.', count($types)));
+        }
+
+        $this->timestamp = gmdate('Y-m-d\TH:i:s\Z');
+        $this->name = $name;
+        $this->type = $type;
+        $this->metaData = $metaData;
+    }
+
+    /**
+     * Get the breadcrumb as an array.
+     *
+     * Note that this is without the meta data.
+     *
+     * @return array
+     */
+    public function toArray()
+    {
+        return [
+            'timestamp' => $this->timestamp,
+            'name' => $this->name,
+            'type' => $this->type,
+        ];
+    }
+
+    /**
+     * Get the breadcrumb meta data.
+     *
+     * Note that this still needs sanitizing before use.
+     *
+     * @return array
+     */
+    public function getMetaData()
+    {
+        return $this->metaData;
+    }
+
+    /**
+     * Get the set of valid breadrum types.
+     *
+     * @return array
+     */
+    public static function getTypes()
+    {
+        return [
+            static::NAVIGATION_TYPE,
+            static::REQUEST_TYPE,
+            static::PROCESS_TYPE,
+            static::LOG_TYPE,
+            static::USER_TYPE,
+            static::STATE_TYPE,
+            static::ERROR_TYPE,
+            static::MANUAL_TYPE,
+        ];
+    }
+}

src/Breadcrumbs/Recorder.php

@@ -0,0 +1,142 @@
+<?php
+
+namespace Bugsnag\Breadcrumbs;
+
+use Countable;
+use Iterator;
+
+class Recorder implements Countable, Iterator
+{
+    /**
+     * The maximum number of breadcrumbs to store.
+     *
+     * @var int
+     */
+    const MAX_ITEMS = 25;
+
+    /**
+     * The recorded breadcrumbs.
+     *
+     * @var \Bugsnag\Breadcrumbs\Breadcrumb[]
+     */
+    protected $breadcrumbs = [];
+
+    /**
+     * The head position.
+     *
+     * @var int
+     */
+    protected $head = 0;
+
+    /**
+     * The pointer position.
+     *
+     * @var int
+     */
+    protected $pointer = 0;
+
+    /**
+     * The iteration position.
+     *
+     * @var int
+     */
+    protected $position = 0;
+
+    /**
+     * Record a breadcrumb.
+     *
+     * We're recording a maximum of 25 breadcrumbs. Once we've recorded 25, we
+     * start wrapping back around and replacing the earlier ones. In order to
+     * indicate the start of the list, we advance a head pointer.
+     *
+     * @param \Bugsnag\Breadcrumbs\Breadcrumb $breadcrumb
+     *
+     * @return void
+     */
+    public function record(Breadcrumb $breadcrumb)
+    {
+        // advance the head by one if we've caught up
+        if ($this->breadcrumbs && $this->pointer === $this->head) {
+            $this->head = ($this->head + 1) % static::MAX_ITEMS;
+        }
+
+        // record the new breadcrumb
+        $this->breadcrumbs[$this->pointer] = $breadcrumb;
+
+        // advance the pointer so we set the next breadcrumb in the next slot
+        $this->pointer = ($this->pointer + 1) % static::MAX_ITEMS;
+    }
+
+    /**
+     * Clear all recorded breadcrumbs.
+     *
+     * @return void
+     */
+    public function clear()
+    {
+        $this->head = 0;
+        $this->pointer = 0;
+        $this->position = 0;
+        $this->breadcrumbs = [];
+    }
+
+    /**
+     * Get the number of stored breadcrumbs.
+     *
+     * @return int
+     */
+    public function count()
+    {
+        return count($this->breadcrumbs);
+    }
+
+    /**
+     * Get the current item.
+     *
+     * @return \Bugsnag\Breadcrumbs\Breadcrumb
+     */
+    public function current()
+    {
+        return $this->breadcrumbs[($this->head + $this->position) % static::MAX_ITEMS];
+    }
+
+    /**
+     * Get the current key.
+     *
+     * @return int
+     */
+    public function key()
+    {
+        return $this->position;
+    }
+
+    /**
+     * Advance the key position.
+     *
+     * @return void
+     */
+    public function next()
+    {
+        $this->position++;
+    }
+
+    /**
+     * Rewind the key position.
+     *
+     * @return void
+     */
+    public function rewind()
+    {
+        $this->position = 0;
+    }
+
+    /**
+     * Is the current key position set?
+     *
+     * @return int
+     */
+    public function valid()
+    {
+        return $this->position < $this->count();
+    }
+}