Add PHPConsoleHandler to debug in Google Chrome

Integrates Monolog with very popular Google Chrome extension "PHP Console" https://chrome.google.com/webstore/detail/php-console/nfhmhhlpfleoednkpnnnkolmclajemef and server library https://github.com/barbushin/php-console. PHPConsoleHandler and "PHP Console" server library code are 100% covered by tests.

README.mdown

@@ -154,6 +154,8 @@ Handlers
   inline `console` messages within Chrome.
 - _BrowserConsoleHandler_: Handler to send logs to browser's Javascript `console` with
   no browser extension required. Most browsers supporting `console` API are supported.
+- _PHPConsoleHandler_: Handler for [PHP Console](https://chrome.google.com/webstore/detail/php-console/nfhmhhlpfleoednkpnnnkolmclajemef), providing
+  inline `console` and notification popup messages within Chrome.
 
 ### Log to databases
 

composer.json

@@ -24,7 +24,8 @@
         "doctrine/couchdb": "~1.0@dev",
         "aws/aws-sdk-php": "~2.4, >2.4.8",
         "videlalvaro/php-amqplib": "~2.4",
-        "swiftmailer/swiftmailer": "~5.3"
+        "swiftmailer/swiftmailer": "~5.3",
+        "php-console/php-console": "~3.1, >3.1.2"
     },
     "suggest": {
         "graylog2/gelf-php": "Allow sending log messages to a GrayLog2 server",
@@ -35,7 +36,8 @@
         "ext-amqp": "Allow sending log messages to an AMQP server (1.0+ required)",
         "ext-mongo": "Allow sending log messages to a MongoDB server",
         "aws/aws-sdk-php": "Allow sending log messages to AWS services like DynamoDB",
-        "rollbar/rollbar": "Allow sending log messages to Rollbar"
+        "rollbar/rollbar": "Allow sending log messages to Rollbar",
+        "php-console/php-console": "Allow sending log messages to Google Chrome"
     },
     "autoload": {
         "psr-4": {"Monolog\\": "src/Monolog"}

src/Monolog/Handler/PHPConsoleHandler.php

@@ -0,0 +1,239 @@
+<?php
+
+/*
+ * This file is part of the Monolog package.
+ *
+ * (c) Jordi Boggiano <j.boggiano@seld.be>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Monolog\Handler;
+
+use Exception;
+use Monolog\Formatter\LineFormatter;
+use Monolog\Logger;
+use PhpConsole\Connector;
+use PhpConsole\Handler;
+use PhpConsole\Helper;
+
+/**
+ * Monolog handler for Google Chrome extension "PHP Console"
+ *
+ * Display PHP error/debug log messages in Google Chrome console and notification popups, executes PHP code remotely
+ *
+ * Usage:
+ * 1. Install Google Chrome extension https://chrome.google.com/webstore/detail/php-console/nfhmhhlpfleoednkpnnnkolmclajemef
+ * 2. See overview https://github.com/barbushin/php-console#overview
+ * 3. Install PHP Console library https://github.com/barbushin/php-console#installation
+ * 4. Example (result will looks like http://i.hizliresim.com/vg3Pz4.png)
+ *
+ *      $logger = new \Monolog\Logger('all', array(new \Monolog\Handler\PHPConsoleHandler()));
+ *      \Monolog\ErrorHandler::register($logger);
+ *      echo $undefinedVar;
+ *      $logger->addDebug('SELECT * FROM users', array('db', 'time' => 0.012));
+ *      PC::debug($_SERVER); // PHP Console debugger for any type of vars
+ *
+ * @author Sergey Barbushin https://www.linkedin.com/in/barbushin
+ */
+class PHPConsoleHandler extends AbstractProcessingHandler
+{
+
+    protected $options = array(
+        'enabled' => true, // bool Is PHP Console server enabled
+        'classesPartialsTraceIgnore' => array('Monolog\\'), // array Hide calls of classes started with...
+        'debugTagsKeysInContext' => array(0, 'tag'), // bool Is PHP Console server enabled
+        'useOwnErrorsHandler' => false, // bool Enable errors handling
+        'useOwnExceptionsHandler' => false, // bool Enable exceptions handling
+        'sourcesBasePath' => null, // string Base path of all project sources to strip in errors source paths
+        'registerHelper' => true, // bool Register PhpConsole\Helper that allows short debug calls like PC::debug($var, 'ta.g.s')
+        'serverEncoding' => null, // string|null Server internal encoding
+        'headersLimit' => null, // int|null Set headers size limit for your web-server
+        'password' => null, // string|null Protect PHP Console connection by password
+        'enableSslOnlyMode' => false, // bool Force connection by SSL for clients with PHP Console installed
+        'ipMasks' => array(), // array Set IP masks of clients that will be allowed to connect to PHP Console: array('192.168.*.*', '127.0.0.1')
+        'enableEvalListener' => false, // bool Enable eval request to be handled by eval dispatcher(if enabled, 'password' option is also required)
+        'dumperDetectCallbacks' => false, // bool Convert callback items in dumper vars to (callback SomeClass::someMethod) strings
+        'dumperLevelLimit' => 5, // int Maximum dumped vars array or object nested dump level
+        'dumperItemsCountLimit' => 100, // int Maximum dumped var same level array items or object properties number
+        'dumperItemSizeLimit' => 5000, // int Maximum length of any string or dumped array item
+        'dumperDumpSizeLimit' => 500000, // int Maximum approximate size of dumped vars result formatted in JSON
+        'detectDumpTraceAndSource' => false, // bool Autodetect and append trace data to debug
+        'dataStorage' => null, // PhpConsole\Storage|null Fixes problem with custom $_SESSION handler(see http://goo.gl/Ne8juJ)
+    );
+
+    /** @var Connector */
+    protected $connector;
+
+    /**
+     * @param array $options See \Monolog\Handler\PHPConsoleHandler::$options for more details
+     * @param Connector|null $connector Instance of \PhpConsole\Connector class (optional)
+     * @param int $level
+     * @param bool $bubble
+     * @throws Exception
+     */
+    public function __construct(array $options = array(), Connector $connector = null, $level = Logger::DEBUG, $bubble = true)
+    {
+        if (!class_exists('PhpConsole\Connector')) {
+            throw new Exception('PHP Console library not found. See https://github.com/barbushin/php-console#installation');
+        }
+        parent::__construct($level, $bubble);
+        $this->options = $this->initOptions($options);
+        $this->connector = $this->initConnector($connector);
+    }
+
+    protected function initOptions(array $options)
+    {
+        $wrongOptions = array_diff(array_keys($options), array_keys($this->options));
+        if ($wrongOptions) {
+            throw new Exception('Unknown options: ' . implode(', ', $wrongOptions));
+        }
+
+        return array_replace($this->options, $options);
+    }
+
+    protected function initConnector(Connector $connector = null)
+    {
+        $options =& $this->options;
+
+        if (!$connector) {
+            if ($options['dataStorage']) {
+                Connector::setPostponeStorage($options['dataStorage']);
+            }
+            $connector = Connector::getInstance();
+        }
+
+        if ($options['registerHelper'] && !Helper::isRegistered()) {
+            Helper::register();
+        }
+
+        if ($options['enabled'] && $connector->isActiveClient()) {
+            if ($options['useOwnErrorsHandler'] || $options['useOwnExceptionsHandler']) {
+                $handler = Handler::getInstance();
+                $handler->setHandleErrors($options['useOwnErrorsHandler']);
+                $handler->setHandleExceptions($options['useOwnExceptionsHandler']);
+                $handler->start();
+            }
+            if ($options['sourcesBasePath']) {
+                $connector->setSourcesBasePath($options['sourcesBasePath']);
+            }
+            if ($options['serverEncoding']) {
+                $connector->setServerEncoding($options['serverEncoding']);
+            }
+            if ($options['password']) {
+                $connector->setPassword($options['password']);
+            }
+            if ($options['enableSslOnlyMode']) {
+                $connector->enableSslOnlyMode();
+            }
+            if ($options['ipMasks']) {
+                $connector->setAllowedIpMasks($options['ipMasks']);
+            }
+            if ($options['headersLimit']) {
+                $connector->setHeadersLimit($options['headersLimit']);
+            }
+            if ($options['detectDumpTraceAndSource']) {
+                $connector->getDebugDispatcher()->detectTraceAndSource = true;
+            }
+            $dumper = $connector->getDumper();
+            $dumper->levelLimit = $options['dumperLevelLimit'];
+            $dumper->itemsCountLimit = $options['dumperItemsCountLimit'];
+            $dumper->itemSizeLimit = $options['dumperItemSizeLimit'];
+            $dumper->dumpSizeLimit = $options['dumperDumpSizeLimit'];
+            $dumper->detectCallbacks = $options['dumperDetectCallbacks'];
+            if ($options['enableEvalListener']) {
+                $connector->startEvalRequestsListener();
+            }
+        }
+
+        return $connector;
+    }
+
+    public function getConnector()
+    {
+        return $this->connector;
+    }
+
+    public function getOptions()
+    {
+        return $this->options;
+    }
+
+    public function handle(array $record)
+    {
+        if ($this->options['enabled'] && $this->connector->isActiveClient()) {
+            return parent::handle($record);
+        }
+
+        return !$this->bubble;
+    }
+
+    /**
+     * Writes the record down to the log of the implementing handler
+     *
+     * @param  array $record
+     * @return void
+     */
+    protected function write(array $record)
+    {
+        if ($record['level'] < Logger::NOTICE) {
+            $this->handleDebugRecord($record);
+        } elseif (isset($record['context']['exception']) && $record['context']['exception'] instanceof Exception) {
+            $this->handleExceptionRecord($record);
+        } else {
+            $this->handleErrorRecord($record);
+        }
+    }
+
+    protected function handleDebugRecord(array $record)
+    {
+        $tags = $this->getRecordTags($record);
+        $message = $record['message'];
+        if ($record['context']) {
+            $message .= ' ' . json_encode($this->connector->getDumper()->dump(array_filter($record['context'])));
+        }
+        $this->connector->getDebugDispatcher()->dispatchDebug($message, $tags, $this->options['classesPartialsTraceIgnore']);
+    }
+
+    protected function handleExceptionRecord(array $record)
+    {
+        $this->connector->getErrorsDispatcher()->dispatchException($record['context']['exception']);
+    }
+
+    protected function handleErrorRecord(array $record)
+    {
+        $context = $record['context'];
+        $this->connector->getErrorsDispatcher()->dispatchError($context['code'], $context['message'], $context['file'], $context['line'], $this->options['classesPartialsTraceIgnore']);
+    }
+
+    protected function getRecordTags(array &$record)
+    {
+        $tags = null;
+        if (!empty($record['context'])) {
+            $context =& $record['context'];
+            foreach ($this->options['debugTagsKeysInContext'] as $key) {
+                if (!empty($context[$key])) {
+                    $tags = $context[$key];
+                    if ($key === 0) {
+                        array_shift($context);
+                    } else {
+                        unset($context[$key]);
+                    }
+                    break;
+                }
+            }
+        }
+
+        return $tags ?: strtolower($record['level_name']);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    protected function getDefaultFormatter()
+    {
+        return new LineFormatter('%message%');
+    }
+}
+

tests/Monolog/Handler/PHPConsoleHandlerTest.php

@@ -0,0 +1,271 @@
+<?php
+
+/*
+ * This file is part of the Monolog package.
+ *
+ * (c) Jordi Boggiano <j.boggiano@seld.be>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Monolog\Handler;
+
+use Exception;
+use Monolog\ErrorHandler;
+use Monolog\Logger;
+use Monolog\TestCase;
+use PhpConsole\Connector;
+use PhpConsole\Dispatcher\Debug as DebugDispatcher;
+use PhpConsole\Dispatcher\Errors as ErrorDispatcher;
+use PhpConsole\Handler;
+use PHPUnit_Framework_MockObject_MockObject;
+
+/**
+ * @covers Monolog\Handler\PHPConsoleHandler
+ * @author Sergey Barbushin https://www.linkedin.com/in/barbushin
+ */
+class PHPConsoleHandlerTest extends TestCase
+{
+
+    /** @var  Connector|PHPUnit_Framework_MockObject_MockObject */
+    protected $connector;
+    /** @var  DebugDispatcher|PHPUnit_Framework_MockObject_MockObject */
+    protected $debugDispatcher;
+    /** @var  ErrorDispatcher|PHPUnit_Framework_MockObject_MockObject */
+    protected $errorDispatcher;
+
+    protected function setUp()
+    {
+        if (!class_exists('PhpConsole\Connector')) {
+            $this->markTestSkipped('PHP Console library not found. See https://github.com/barbushin/php-console#installation');
+        }
+        $this->connector = $this->initConnectorMock();
+
+        $this->debugDispatcher = $this->initDebugDispatcherMock($this->connector);
+        $this->connector->setDebugDispatcher($this->debugDispatcher);
+
+        $this->errorDispatcher = $this->initErrorDispatcherMock($this->connector);
+        $this->connector->setErrorsDispatcher($this->errorDispatcher);
+    }
+
+    protected function initDebugDispatcherMock(Connector $connector)
+    {
+        return $this->getMockBuilder('PhpConsole\Dispatcher\Debug')
+            ->disableOriginalConstructor()
+            ->setMethods(array('dispatchDebug'))
+            ->setConstructorArgs(array($connector, $connector->getDumper()))
+            ->getMock();
+    }
+
+    protected function initErrorDispatcherMock(Connector $connector)
+    {
+        return $this->getMockBuilder('PhpConsole\Dispatcher\Errors')
+            ->disableOriginalConstructor()
+            ->setMethods(array('dispatchError', 'dispatchException'))
+            ->setConstructorArgs(array($connector, $connector->getDumper()))
+            ->getMock();
+    }
+
+    protected function initConnectorMock()
+    {
+        $connector = $this->getMockBuilder('PhpConsole\Connector')
+            ->disableOriginalConstructor()
+            ->setMethods(array(
+                'sendMessage',
+                'onShutDown',
+                'isActiveClient',
+                'setSourcesBasePath',
+                'setServerEncoding',
+                'setPassword',
+                'enableSslOnlyMode',
+                'setAllowedIpMasks',
+                'setHeadersLimit',
+                'startEvalRequestsListener',
+            ))
+            ->getMock();
+
+        $connector->expects($this->any())
+            ->method('isActiveClient')
+            ->will($this->returnValue(true));
+
+        return $connector;
+    }
+
+    protected function getHandlerDefaultOption($name)
+    {
+        $handler = new PHPConsoleHandler(array(), $this->connector);
+        $options = $handler->getOptions();
+
+        return $options[$name];
+    }
+
+    protected function initLogger($handlerOptions = array(), $level = Logger::DEBUG)
+    {
+        return new Logger('test', array(
+            new PHPConsoleHandler($handlerOptions, $this->connector, $level)
+        ));
+    }
+
+    public function testInitWithDefaultConnector()
+    {
+        $handler = new PHPConsoleHandler();
+        $this->assertEquals(spl_object_hash(Connector::getInstance()), spl_object_hash($handler->getConnector()));
+    }
+
+    public function testInitWithCustomConnector()
+    {
+        $handler = new PHPConsoleHandler(array(), $this->connector);
+        $this->assertEquals(spl_object_hash($this->connector), spl_object_hash($handler->getConnector()));
+    }
+
+    public function testDebug()
+    {
+        $this->debugDispatcher->expects($this->once())->method('dispatchDebug')->with($this->equalTo('test'));
+        $this->initLogger()->addDebug('test');
+    }
+
+    public function testDebugContextInMessage()
+    {
+        $message = 'test';
+        $tag = 'tag';
+        $context = array($tag, 'custom' => mt_rand());
+        $expectedMessage = $message . ' ' . json_encode(array_slice($context, 1));
+        $this->debugDispatcher->expects($this->once())->method('dispatchDebug')->with(
+            $this->equalTo($expectedMessage),
+            $this->equalTo($tag)
+        );
+        $this->initLogger()->addDebug($message, $context);
+    }
+
+    public function testDebugTags($tagsContextKeys = null)
+    {
+        $expectedTags = mt_rand();
+        $logger = $this->initLogger($tagsContextKeys ? array('debugTagsKeysInContext' => $tagsContextKeys) : array());
+        if (!$tagsContextKeys) {
+            $tagsContextKeys = $this->getHandlerDefaultOption('debugTagsKeysInContext');
+        }
+        foreach ($tagsContextKeys as $key) {
+            $debugDispatcher = $this->initDebugDispatcherMock($this->connector);
+            $debugDispatcher->expects($this->once())->method('dispatchDebug')->with(
+                $this->anything(),
+                $this->equalTo($expectedTags)
+            );
+            $this->connector->setDebugDispatcher($debugDispatcher);
+            $logger->addDebug('test', array($key => $expectedTags));
+        }
+    }
+
+    public function testError($classesPartialsTraceIgnore = null)
+    {
+        $code = E_USER_NOTICE;
+        $message = 'message';
+        $file = __FILE__;
+        $line = __LINE__;
+        $this->errorDispatcher->expects($this->once())->method('dispatchError')->with(
+            $this->equalTo($code),
+            $this->equalTo($message),
+            $this->equalTo($file),
+            $this->equalTo($line),
+            $classesPartialsTraceIgnore ?: $this->equalTo($this->getHandlerDefaultOption('classesPartialsTraceIgnore'))
+        );
+        $errorHandler = ErrorHandler::register($this->initLogger($classesPartialsTraceIgnore ? array('classesPartialsTraceIgnore' => $classesPartialsTraceIgnore) : array()), false);
+        $errorHandler->registerErrorHandler(array(), false, E_USER_WARNING);
+        $errorHandler->handleError($code, $message, $file, $line);
+    }
+
+    public function testException()
+    {
+        $exception = new Exception();
+        $this->errorDispatcher->expects($this->once())->method('dispatchException')->with(
+            $this->equalTo($exception)
+        );
+        $errorHandler = ErrorHandler::register($this->initLogger(), false, false);
+        $errorHandler->registerExceptionHandler(null, false);
+        $errorHandler->handleException($exception);
+    }
+
+    /**
+     * @expectedException Exception
+     */
+    public function testWrongOptionsThrowsException()
+    {
+        new PHPConsoleHandler(array('xxx' => 1));
+    }
+
+    public function testOptionEnabled()
+    {
+        $this->debugDispatcher->expects($this->never())->method('dispatchDebug');
+        $this->initLogger(array('enabled' => false))->addDebug('test');
+    }
+
+    public function testOptionClassesPartialsTraceIgnore()
+    {
+        $this->testError(array('Class', 'Namespace\\'));
+    }
+
+    public function testOptionDebugTagsKeysInContext()
+    {
+        $this->testDebugTags(array('key1', 'key2'));
+    }
+
+    public function testOptionUseOwnErrorsAndExceptionsHandler()
+    {
+        $this->initLogger(array('useOwnErrorsHandler' => true, 'useOwnExceptionsHandler' => true));
+        $this->assertEquals(array(Handler::getInstance(), 'handleError'), set_error_handler(function () {
+        }));
+        $this->assertEquals(array(Handler::getInstance(), 'handleException'), set_exception_handler(function () {
+        }));
+    }
+
+    public static function provideConnectorMethodsOptionsSets()
+    {
+        return array(
+            array('sourcesBasePath', 'setSourcesBasePath', __DIR__),
+            array('serverEncoding', 'setServerEncoding', 'cp1251'),
+            array('password', 'setPassword', '******'),
+            array('enableSslOnlyMode', 'enableSslOnlyMode', true, false),
+            array('ipMasks', 'setAllowedIpMasks', array('127.0.0.*')),
+            array('headersLimit', 'setHeadersLimit', 2500),
+            array('enableEvalListener', 'startEvalRequestsListener', true, false),
+        );
+    }
+
+    /**
+     * @dataProvider provideConnectorMethodsOptionsSets
+     */
+    public function testOptionCallsConnectorMethod($option, $method, $value, $isArgument = true)
+    {
+        $expectCall = $this->connector->expects($this->once())->method($method);
+        if ($isArgument) {
+            $expectCall->with($value);
+        }
+        new PHPConsoleHandler(array($option => $value), $this->connector);
+    }
+
+    public function testOptionDetectDumpTraceAndSource()
+    {
+        new PHPConsoleHandler(array('detectDumpTraceAndSource' => true), $this->connector);
+        $this->assertTrue($this->connector->getDebugDispatcher()->detectTraceAndSource);
+    }
+
+    public static function provideDumperOptionsValues()
+    {
+        return array(
+            array('dumperLevelLimit', 'levelLimit', 1001),
+            array('dumperItemsCountLimit', 'itemsCountLimit', 1002),
+            array('dumperItemSizeLimit', 'itemSizeLimit', 1003),
+            array('dumperDumpSizeLimit', 'dumpSizeLimit', 1004),
+            array('dumperDetectCallbacks', 'detectCallbacks', true),
+        );
+    }
+
+    /**
+     * @dataProvider provideDumperOptionsValues
+     */
+    public function testDumperOptions($option, $dumperProperty, $value)
+    {
+        new PHPConsoleHandler(array($option => $value), $this->connector);
+        $this->assertEquals($value, $this->connector->getDumper()->$dumperProperty);
+    }
+}