Promote Zend_Log_Writer_Syslog to trunk

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@16582 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_Log-Writers-Syslog.xml

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect2 id="zend.log.writers.syslog">
+    <title>Writing to the System Log</title>
+
+    <para>
+        <classname>Zend_Log_Writer_Syslog</classname> writes log entries to the
+        system log (syslog). Internally, it proxies to PHP's
+        <functionname>openlog()</functionname>,
+        <functionname>closelog()</functionname>, and
+        <functionname>syslog()</functionname> functions.
+    </para>
+
+    <para>
+        One useful case for <classname>Zend_Log_Writer_Syslog</classname>
+        is for aggregating logs from clustered machines via the system log
+        functionality. Many systems allow remote logging of system events, which
+        allows system adminstrators to monitor a cluster of machines from a
+        single log file.
+    </para>
+
+    <para>
+        By default, all syslog messages generated are prefixed with the string
+        "Zend_Log".  You may specify a different "application" name by which to
+        identify such log messages by either passing the application name to the
+        contructor or the application accessor:
+    </para>
+
+    <programlisting role="php"><![CDATA[
+// At instantiation, pass the "application" key in the options:
+$writer = new Zend_Log_Writer_Syslog(array('application' => 'FooBar'));
+
+// Any other time:
+$writer->setApplication('BarBaz');
+]]></programlisting>
+
+    <para>
+        The system log also allows you to identify the "facility," or
+        application type, logging the message; many system loggers will actually
+        generate different log files per facility, which again aids
+        administrators monitoring server activity.
+    </para>
+
+    <para>
+        You may specify the log facility either in the constructor or via an
+        accessor. It should be one of the <functionname>openlog()</functionname>
+        constants defined on the <ulink url="http://php.net/openlog">openlog()
+            manual page</ulink>.
+    </para>
+
+    <programlisting role="php"><![CDATA[
+// At instantiation, pass the "facility" key in the options:
+$writer = new Zend_Log_Writer_Syslog(array('facility' => LOG_AUTH));
+
+// Any other time:
+$writer->setFacility(LOG_USER);
+]]></programlisting>
+
+    <para>
+        When logging, you may continue to use the default
+        <classname>Zend_Log</classname> priority constants; internally, they are
+        mapped to the appropriate <functionname>syslog()</functionname> priority
+        constants.
+    </para>
+</sect2>

documentation/manual/en/module_specs/Zend_Log-Writers.xml

@@ -97,6 +97,7 @@ $logger->info('Informational message');
 
   <xi:include href="Zend_Log-Writers-Firebug.xml" />
   <xi:include href="Zend_Log-Writers-Mail.xml" />
+  <xi:include href="Zend_Log-Writers-Syslog.xml" />
 
   <sect2 id="zend.log.writers.null">
     <title>Stubbing Out the Writer</title>

library/Zend/Log/Writer/Syslog.php

@@ -0,0 +1,174 @@
+<?php
+/**
+ * Zend Framework
+ *
+ * LICENSE
+ *
+ * This source file is subject to the new BSD license that is bundled
+ * with this package in the file LICENSE.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://framework.zend.com/license/new-bsd
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to license@zend.com so we can send you a copy immediately.
+ *
+ * @category   Zend
+ * @package    Zend_Log
+ * @subpackage Writer
+ * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+
+/** Zend_Log_Writer_Abstract */
+require_once 'Zend/Log/Writer/Abstract.php';
+
+/**
+ * Writes log messages to syslog
+ *
+ * @category   Zend
+ * @package    Zend_Log
+ * @subpackage Writer
+ * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+class Zend_Log_Writer_Syslog extends Zend_Log_Writer_Abstract
+{
+    /**
+     * Maps Zend_Log priorities to PHP's syslog priorities
+     * @var array
+     */
+    protected $_priorities = array(
+        Zend_Log::EMERG  => LOG_EMERG,
+        Zend_Log::ALERT  => LOG_ALERT,
+        Zend_Log::CRIT   => LOG_CRIT,
+        Zend_Log::ERR    => LOG_ERR,
+        Zend_Log::WARN   => LOG_WARNING,
+        Zend_Log::NOTICE => LOG_NOTICE,
+        Zend_Log::INFO   => LOG_INFO,
+        Zend_Log::DEBUG  => LOG_DEBUG,
+    );
+
+    /**
+     * The default log priority - for unmapped custom priorities
+     * @var string
+     */
+    protected $_defaultPriority = LOG_NOTICE;
+
+    /**
+     * Last application name set by a syslog-writer instance
+     * @var string
+     */
+    protected static $_lastApplication;
+
+    /**
+     * Last facility name set by a syslog-writer instance
+     * @var string
+     */
+    protected static $_lastFacility;
+
+    /**
+     * Application name used by this syslog-writer instance
+     * @var string
+     */
+    protected $_application = 'Zend_Log';
+
+    /**
+     * Facility used by this syslog-writer instance
+     * @var string
+     */
+    protected $_facility = LOG_USER;
+
+    /**
+     * Class constructor
+     *
+     * @param  array $options Array of options; may include "application" and "facility" keys
+     * @return void
+     */
+    public function __construct(array $params = array())
+    {
+        if (isset($params['application'])) {
+            $this->_application = $params['application'];
+        }
+        if (isset($params['facility'])) {
+            $this->_facility = $params['facility'];
+        }
+        $this->_initializeSyslog();
+    }
+
+    /**
+     * Initialize syslog / set application name and facility
+     *
+     * @param  string $application Application name
+     * @param  string $facility Syslog facility
+     * @return void
+     */
+    protected function _initializeSyslog()
+    {
+        self::$_lastApplication = $this->_application;
+        self::$_lastFacility    = $this->_facility;
+        openlog($this->_application, LOG_PID, $this->_facility);
+    }
+
+    /**
+     * Set syslog facility
+     *
+     * @param  string $facility Syslog facility
+     * @return void
+     */
+    public function setFacility($facility)
+    {
+        if ($this->_facility === $facility) {
+            return;
+        }
+        $this->_facility = $facility;
+        $this->_initializeSyslog();
+    }
+
+    /**
+     * Set application name
+     *
+     * @param  string $application Application name
+     * @return void
+     */
+    public function setApplicationName($application)
+    {
+        if ($this->_application === $application) {
+            return;
+        }
+        $this->_application = $application;
+        $this->_initializeSyslog();
+    }
+
+    /**
+     * Close syslog.
+     *
+     * @return void
+     */
+    public function shutdown()
+    {
+        closelog();
+    }
+
+    /**
+     * Write a message to syslog.
+     *
+     * @param  array $event  event data
+     * @return void
+     */
+    protected function _write($event)
+    {
+        if (array_key_exists($event['priority'], $this->_priorities)) {
+            $priority = $this->_priorities[$event['priority']];
+        } else {
+            $priority = $this->_defaultPriority;
+        }
+
+        if ($this->_application !== self::$_lastApplication
+            || $this->_facility !== self::$_lastFacility)
+        {
+            $this->_initializeSyslog();
+        }
+
+        syslog($priority, $event['message']);
+    }
+}