Merge remote-tracking branch 'pablolb/master'

README.mdown

@@ -46,6 +46,7 @@ Handlers
 - _NativeMailHandler_: Sends emails using PHP's mail() function.
 - _SwiftMailerHandler_: Sends emails using a SwiftMailer instance.
 - _SyslogHandler_: Logs records to the syslog.
+- _SocketHandler_: Logs records to [sockets](http://php.net/fsockopen), use this for UNIX and TCP sockets. See an [example](https://github.com/Seldaek/monolog/blob/master/doc/sockets.md).
 
 Wrappers / Special Handlers
 ---------------------------

doc/sockets.md

@@ -0,0 +1,37 @@
+Sockets Handler
+===============
+
+This handler allows you to write your logs to sockets using [fsockopen](http://php.net/fsockopen)
+or [pfsockopen](http://php.net/pfsockopen).
+
+Persistent sockets are mainly useful in web environments where you gain some performance not closing/opening
+the connections between requests.
+
+Basic Example
+-------------
+
+```php
+<?php
+
+use Monolog\Logger;
+use Monolog\Handler\SocketHandler;
+
+// Create the logger
+$logger = new Logger('my_logger');
+
+// Create the handler
+$handler = new SocketHandler('unix:///var/log/httpd_app_log.socket');
+$handler->setPersistent(true);
+
+// Now add the handler
+$logger->pushHandler($handler, Logger::DEBUG);
+
+// You can now use your logger
+$logger->addInfo('My logger is now ready');
+
+```
+
+In this example, using syslog-ng, you should see the log on the log server:
+
+    cweb1 [2012-02-26 00:12:03] my_logger.INFO: My logger is now ready [] [] 
+

src/Monolog/Handler/SocketHandler.php

@@ -0,0 +1,274 @@
+<?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 Monolog\Logger;
+
+/**
+ * Stores to any socket - uses fsockopen() or pfsockopen().
+ * 
+ * @author Pablo de Leon Belloc <pablolb@gmail.com>
+ * @see    http://php.net/manual/en/function.fsockopen.php
+ */
+class SocketHandler extends AbstractProcessingHandler
+{
+
+    private $connectionString;
+    private $connectionTimeout;
+    private $resource;
+    private $timeout = 0;
+    private $persistent = false;
+    private $errno;
+    private $errstr;
+
+    /**
+     * @param string  $connectionString Socket connection string
+     * @param integer $level            The minimum logging level at which this handler will be triggered
+     * @param Boolean $bubble           Whether the messages that are handled can bubble up the stack or not
+     */
+    public function __construct($connectionString, $level = Logger::DEBUG, $bubble = true)
+    {
+        parent::__construct($level, $bubble);
+        $this->connectionString = $connectionString;
+        $this->connectionTimeout = (float) ini_get('default_socket_timeout');
+    }
+
+    /**
+     * Connect (if necessary) and write to the socket
+     * 
+     * @param array $record
+     * 
+     * @throws \UnexpectedValueException
+     * @throws \RuntimeException
+     */
+    public function write(array $record)
+    {
+        $this->connectIfNotConnected();
+        $this->writeToSocket((string) $record['formatted']);
+    }
+
+    /**
+     * We will not close a PersistentSocket instance so it can be reused in other requests.
+     */
+    public function close()
+    {
+        if ($this->isPersistent()) {
+            return;
+        }
+        $this->closeSocket();
+    }
+
+    /**
+     * Close socket, if open
+     */
+    public function closeSocket()
+    {
+        if (is_resource($this->resource)) {
+            fclose($this->resource);
+            $this->resource = null;
+        }
+    }
+
+    /**
+     * Set socket connection to nbe persistent. It only has effect before the connection is initiated.
+     * 
+     * @param type $boolean 
+     */
+    public function setPersistent($boolean)
+    {
+        $this->persistent = (boolean) $boolean;
+    }
+
+    /**
+     * Set connection timeout.  Only has effect before we connect.
+     * 
+     * @param integer $seconds 
+     * 
+     * @see http://php.net/manual/en/function.fsockopen.php
+     */
+    public function setConnectionTimeout($seconds)
+    {
+        $this->validateTimeout($seconds);
+        $this->connectionTimeout = (float) $seconds;
+    }
+
+    /**
+     * Set write timeout. Only has effect before we connect.
+     * 
+     * @param type $seconds 
+     * 
+     * @see http://php.net/manual/en/function.stream-set-timeout.php
+     */
+    public function setTimeout($seconds)
+    {
+        $this->validateTimeout($seconds);
+        $this->timeout = (int) $seconds;
+    }
+
+    /**
+     * Get current connection string
+     * 
+     * @return string
+     */
+    public function getConnectionString()
+    {
+        return $this->connectionString;
+    }
+
+    /**
+     * Get persistent setting
+     * 
+     * @return boolean
+     */
+    public function isPersistent()
+    {
+        return $this->persistent;
+    }
+
+    /**
+     * Get current connection timeout setting
+     * 
+     * @return float
+     */
+    public function getConnectionTimeout()
+    {
+        return $this->connectionTimeout;
+    }
+
+    /**
+     * Get current in-transfer timeout
+     * 
+     * @return float
+     */
+    public function getTimeout()
+    {
+        return $this->timeout;
+    }
+
+    /**
+     * Check to see if the socket is currently available.
+     * 
+     * UDP might appear to be connected but might fail when writing.  See http://php.net/fsockopen for details.
+     * 
+     * @return boolean
+     */
+    public function isConnected()
+    {
+        return is_resource($this->resource)
+                && !feof($this->resource);  // on TCP - other party can close connection. 
+    }
+    
+    /**
+     * Allow mock
+     */
+    protected function pfsockopen()
+    {
+        return @pfsockopen($this->connectionString, -1, $this->errno, $this->errstr, $this->connectionTimeout);
+    }
+
+    /**
+     * Allow mock
+     */
+    protected function fsockopen()
+    {
+        return @fsockopen($this->connectionString, -1, $this->errno, $this->errstr, $this->connectionTimeout);
+    }
+
+    /**
+     * Allow mock
+     */
+    protected function stream_set_timeout()
+    {
+        return stream_set_timeout($this->resource, $this->timeout);
+    }
+
+    /**
+     * Allow mock
+     */
+    protected function fwrite($data)
+    {
+        return @fwrite($this->resource, $data);
+    }
+
+    /**
+     * Allow mock
+     */
+    protected function stream_get_meta_data()
+    {
+        return stream_get_meta_data($this->resource);
+    }
+
+    private function validateTimeout($value)
+    {
+        $ok = filter_var($value, FILTER_VALIDATE_INT, array('options' => array(
+                'min_range' => 0,
+                )));
+        if ($ok === false) {
+            throw new \InvalidArgumentException("Timeout must be 0 or a positive integer (got $value)");
+        }
+    }
+
+    private function connectIfNotConnected()
+    {
+        if ($this->isConnected()) {
+            return;
+        }
+        $this->connect();
+    }
+
+    private function connect()
+    {
+        $this->createSocketResource();
+        $this->setSocketTimeout();
+    }
+
+    private function createSocketResource()
+    {
+        if ($this->isPersistent()) {
+            $resource = $this->pfsockopen();
+        } else {
+            $resource = $this->fsockopen();
+        }
+        if (!$resource) {
+            throw new \UnexpectedValueException("Failed connecting to $this->connectionString ($this->errno: $this->errstr)");
+        }
+        $this->resource = $resource;
+    }
+
+    private function setSocketTimeout()
+    {
+        if (!$this->stream_set_timeout()) {
+            throw new \UnexpectedValueException("Failed setting timeout with stream_set_timeout()");
+        }
+    }
+
+    private function writeToSocket($data)
+    {
+        $length = strlen($data);
+        $sent = 0;
+        while ($this->isConnected() && $sent < $length) {
+            $chunk = $this->fwrite(substr($data, $sent));
+            if ($chunk === false) {
+                throw new \RuntimeException("Could not write to socket");
+            }
+            $sent += $chunk;
+            $socketInfo = $this->stream_get_meta_data();
+            if ($socketInfo['timed_out']) {
+                throw new \RuntimeException("Write timed-out");
+            }
+        }
+        if (!$this->isConnected() && $sent < $length) {
+            throw new \RuntimeException("End-of-file reached, probably we got disconnected (sent $sent of $length)");
+        }
+    }
+
+}

tests/Monolog/Handler/SocketHandlerTest.php

@@ -0,0 +1,285 @@
+<?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 Monolog\TestCase;
+use Monolog\Logger;
+
+/**
+ * @author Pablo de Leon Belloc <pablolb@gmail.com>
+ */
+class SocketHandlerTest extends TestCase
+{
+
+    /**
+     * @var Monolog\Handler\SocketHandler
+     */
+    private $handler;
+
+    /**
+     * @var resource
+     */
+    private $res;
+
+    /**
+     * @expectedException UnexpectedValueException
+     */
+    public function testInvalidHostname()
+    {
+        $this->createHandler('garbage://here');
+        $this->writeRecord('data');
+    }
+
+    /**
+     * @expectedException \InvalidArgumentException
+     */
+    public function testBadConnectionTimeout()
+    {
+        $this->createHandler('localhost:1234');
+        $this->handler->setConnectionTimeout(-1);
+    }
+
+    public function testSetConnectionTimeout()
+    {
+        $this->createHandler('localhost:1234');
+        $this->handler->setConnectionTimeout(10);
+        $this->assertEquals(10, $this->handler->getConnectionTimeout());
+    }
+
+    /**
+     * @expectedException \InvalidArgumentException
+     */
+    public function testBadTimeout()
+    {
+        $this->createHandler('localhost:1234');
+        $this->handler->setTimeout(-1);
+    }
+
+    public function testSetTimeout()
+    {
+        $this->createHandler('localhost:1234');
+        $this->handler->setTimeout(10);
+        $this->assertEquals(10, $this->handler->getTimeout());
+    }
+
+    public function testSetConnectionString()
+    {
+        $this->createHandler('tcp://localhost:9090');
+        $this->assertEquals('tcp://localhost:9090', $this->handler->getConnectionString());
+    }
+
+    /**
+     * @expectedException UnexpectedValueException
+     */
+    public function testExceptionIsThrownOnFsockopenError()
+    {
+        $this->setMockHandler(array('fsockopen'));
+        $this->handler->expects($this->once())
+            ->method('fsockopen')
+            ->will($this->returnValue(false));
+        $this->writeRecord('Hello world');
+    }
+
+    /**
+     * @expectedException UnexpectedValueException
+     */
+    public function testExceptionIsThrownOnPfsockopenError()
+    {
+        $this->setMockHandler(array('pfsockopen'));
+        $this->handler->expects($this->once())
+            ->method('pfsockopen')
+            ->will($this->returnValue(false));
+        $this->handler->setPersistent(true);
+        $this->writeRecord('Hello world');
+    }
+
+    /**
+     * @expectedException UnexpectedValueException
+     */
+    public function testExceptionIsThrownIfCannotSetTimeout()
+    {
+        $this->setMockHandler(array('stream_set_timeout'));
+        $this->handler->expects($this->once())
+            ->method('stream_set_timeout')
+            ->will($this->returnValue(false));
+        $this->writeRecord('Hello world');
+    }
+
+    /**
+     * @expectedException RuntimeException
+     */
+    public function testWriteFailsOnIfFwriteReturnsFalse()
+    {
+        $this->setMockHandler(array('fwrite'));
+
+        $callback = function($arg)
+        {
+            $map = array(
+                'Hello world' => 6,
+                'world' => false,
+            );
+            return $map[$arg];
+        };
+
+        $this->handler->expects($this->exactly(2))
+            ->method('fwrite')
+            ->will($this->returnCallback($callback));
+
+        $this->writeRecord('Hello world');
+    }
+
+    /**
+     * @expectedException RuntimeException
+     */
+    public function testWriteFailsIfStreamTimesOut()
+    {
+        $this->setMockHandler(array('fwrite', 'stream_get_meta_data'));
+
+        $callback = function($arg)
+        {
+            $map = array(
+                'Hello world' => 6,
+                'world' => 5,
+            );
+            return $map[$arg];
+        };
+
+        $this->handler->expects($this->exactly(1))
+            ->method('fwrite')
+            ->will($this->returnCallback($callback));
+        $this->handler->expects($this->exactly(1))
+            ->method('stream_get_meta_data')
+            ->will($this->returnValue(array('timed_out' => true)));
+
+
+        $this->writeRecord('Hello world');
+    }
+
+    /**
+     * @expectedException RuntimeException
+     */
+    public function testWriteFailsOnIncompleteWrite()
+    {
+        $this->setMockHandler(array('fwrite', 'stream_get_meta_data'));
+
+        $res = $this->res;
+        $callback = function($string) use ($res)
+        {
+            fclose($res);
+            return strlen('Hello');
+        };
+
+        $this->handler->expects($this->exactly(1))
+            ->method('fwrite')
+            ->will($this->returnCallback($callback));
+        $this->handler->expects($this->exactly(1))
+            ->method('stream_get_meta_data')
+            ->will($this->returnValue(array('timed_out' => false)));
+
+        $this->writeRecord('Hello world');
+    }
+
+    public function testWriteWithMemoryFile()
+    {
+        $this->setMockHandler();
+        $this->writeRecord('test1');
+        $this->writeRecord('test2');
+        $this->writeRecord('test3');
+        fseek($this->res, 0);
+        $this->assertEquals('test1test2test3', fread($this->res, 1024));
+    }
+
+    public function testWriteWithMock()
+    {
+        $this->setMockHandler(array('fwrite'));
+
+        $callback = function($arg)
+        {
+            $map = array(
+                'Hello world' => 6,
+                'world' => 5,
+            );
+            return $map[$arg];
+        };
+
+        $this->handler->expects($this->exactly(2))
+            ->method('fwrite')
+            ->will($this->returnCallback($callback));
+
+        $this->writeRecord('Hello world');
+    }
+
+    public function testClose()
+    {
+        $this->setMockHandler();
+        $this->writeRecord('Hello world');
+        $this->assertInternalType('resource', $this->res);
+        $this->handler->close();
+        $this->assertFalse(is_resource($this->res), "Expected resource to be closed after closing handler");
+    }
+
+    public function testCloseDoesNotClosePersistentSocket()
+    {
+        $this->setMockHandler();
+        $this->handler->setPersistent(true);
+        $this->writeRecord('Hello world');
+        $this->assertTrue(is_resource($this->res));
+        $this->handler->close();
+        $this->assertTrue(is_resource($this->res));
+    }
+
+    private function createHandler($connectionString)
+    {
+        $this->handler = new SocketHandler($connectionString);
+        $this->handler->setFormatter($this->getIdentityFormatter());
+    }
+
+    private function writeRecord($string)
+    {
+        $this->handler->handle($this->getRecord(Logger::WARNING, $string));
+    }
+
+    private function setMockHandler(array $methods = array())
+    {
+        $this->res = fopen('php://memory', 'a');
+
+        $defaultMethods = array('fsockopen', 'pfsockopen', 'stream_set_timeout');
+        $newMethods = array_diff($methods, $defaultMethods);
+
+        $finalMethods = array_merge($defaultMethods, $newMethods);
+
+        $this->handler = $this->getMock(
+            '\Monolog\Handler\SocketHandler', $finalMethods, array('localhost:1234')
+        );
+
+        if (!in_array('fsockopen', $methods)) {
+            $this->handler->expects($this->any())
+                ->method('fsockopen')
+                ->will($this->returnValue($this->res));
+        }
+
+        if (!in_array('pfsockopen', $methods)) {
+            $this->handler->expects($this->any())
+                ->method('pfsockopen')
+                ->will($this->returnValue($this->res));
+        }
+
+        if (!in_array('stream_set_timeout', $methods)) {
+            $this->handler->expects($this->any())
+                ->method('stream_set_timeout')
+                ->will($this->returnValue(true));
+        }
+
+        $this->handler->setFormatter($this->getIdentityFormatter());
+    }
+
+}