1: <?php
  2: 
  3: /**
  4:  * This file contains the log class.
  5:  *
  6:  * @package    Core
  7:  * @subpackage Log
  8:  * @version    SVN Revision $Rev:$
  9:  *
 10:  * @author     Dominik Ziegler
 11:  * @copyright  four for business AG <www.4fb.de>
 12:  * @license    http://www.contenido.org/license/LIZENZ.txt
 13:  * @link       http://www.4fb.de
 14:  * @link       http://www.contenido.org
 15:  */
 16: 
 17: defined('CON_FRAMEWORK') || die('Illegal call: Missing framework initialization - request aborted.');
 18: 
 19: /**
 20:  * This class contains the main functionalities for the logging in CONTENIDO.
 21:  *
 22:  * Examples:
 23:  *
 24:  * $writer = cLogWriter::factory("File", array('destination' => 'contenido.log'));
 25:  * $log = new cLog($writer);
 26:  *
 27:  * $log->addPriority("CONTENIDO", 10);
 28:  * $log->log("Contenido Log Message.", "CONTENIDO");
 29:  * $log->contenido("Same log entry in short notation.");
 30:  * $log->removePriority("CONTENIDO");
 31:  *
 32:  * $log->emerg("System down.");
 33:  *
 34:  * $log->log('Notice Log Message', cLog::NOTICE);
 35:  *
 36:  * $log->buffer('Buffered Log Message', cLog::WARN);
 37:  * $log->commit();
 38:  *
 39:  * @package    Core
 40:  * @subpackage Log
 41:  */
 42: class cLog {
 43: 
 44:     /**
 45:      * logging level
 46:      *
 47:      * @var int
 48:      */
 49:     const EMERG   = 0;
 50: 
 51:     /**
 52:      * logging level
 53:      *
 54:      * @var int
 55:      */
 56:     const ALERT   = 1;
 57: 
 58:     /**
 59:      * logging level
 60:      *
 61:      * @var int
 62:      */
 63:     const CRIT    = 2;
 64: 
 65:     /**
 66:      * logging level
 67:      *
 68:      * @var int
 69:      */
 70:     const ERR     = 3;
 71: 
 72:     /**
 73:      * logging level
 74:      *
 75:      * @var int
 76:      */
 77:     const WARN    = 4;
 78: 
 79:     /**
 80:      * logging level
 81:      *
 82:      * @var int
 83:      */
 84:     const NOTICE  = 5;
 85: 
 86:     /**
 87:      * logging level
 88:      *
 89:      * @var int
 90:      */
 91:     const INFO    = 6;
 92: 
 93:     /**
 94:      * logging level
 95:      *
 96:      * @var int
 97:      */
 98:     const DEBUG   = 7;
 99: 
100:     /**
101:      * Contains the local log writer instance.
102:      *
103:      * @var cLogWriter
104:      */
105:     protected $_writer;
106: 
107:     /**
108:      * Contains all shortcut handlers
109:      *
110:      * @var array
111:      */
112:     protected $_shortcutHandlers = array();
113: 
114:     /**
115:      * Contains all available priorities
116:      *
117:      * @var array
118:      */
119:     protected $_priorities = array();
120: 
121:     /**
122:      * Contains all default priorities
123:      *
124:      * @var array
125:      */
126:     protected $_defaultPriorities = array();
127: 
128:     /**
129:      * Contains all buffered messages
130:      *
131:      * @var array
132:      */
133:     protected $_buffer = array();
134: 
135:     /**
136:      * Creates a new instance of the CONTENIDO Log mechanism.
137:      *
138:      * The log format interface of cLog is capable of being extended by subclasses. See the note about
139:      * the log shortcuts below.
140:      *
141:      *
142:      * About Log Shortcuts
143:      * -------------------
144:      * Log shortcuts are placeholders which are replaced when a log entry is created. Placeholders start with a
145:      * percentage sign (%) and contain one or more characters. Each placeholder is handled by an own function which
146:      * decides what to do.
147:      *
148:      * @param mixed $writer [optional]
149:      *         Writer object (any subclass of cLogWriter), or false if cLog
150:      *         should handle the writer creation
151:      */
152:     public function __construct($writer = false) {
153:         global $cfg;
154: 
155:         $createWriter = false;
156: 
157:         if ($writer == false) {
158:             $createWriter = true;
159:         } else if (!is_object($writer) || ($writer instanceof cLogWriter) == false) {
160:             cWarning(__FILE__, __LINE__, "The passed class is not a subclass of cLogWriter. Creating new one.");
161:             $createWriter = true;
162:         }
163: 
164:         if ($createWriter == true) {
165:             $options = array('destination' => $cfg['path']['contenido_logs'] . 'data/contenido.log');
166:             $writer = cLogWriter::factory("File", $options);
167:         }
168: 
169:         $this->setWriter($writer);
170:         $this->setShortcutHandler("%date", array($this, "shDate"));
171:         $this->setShortcutHandler("%level", array($this, "shLevel"));
172:         $this->setShortcutHandler("%message", array($this, "shMessage"));
173: 
174:         $this->getWriter()->setOption('log_format', '[%date] [%level] %message', false);
175: 
176:         $reflection = new ReflectionClass($this);
177:         $this->_priorities = $this->_defaultPriorities = array_flip($reflection->getConstants());
178:     }
179: 
180:     /**
181:      * Returns the local writer instance.
182:      * @return cLogWriter
183:      */
184:     public function getWriter() {
185:         return $this->_writer;
186:     }
187: 
188:     /**
189:      * Sets the local writer instance.
190:      *
191:      * @param cLogWriter $writer
192:      *         Writer instacne
193:      */
194:     public function setWriter(cLogWriter $writer) {
195:         $this->_writer = $writer;
196:     }
197: 
198:     /**
199:      * Defines a custom shortcut handler.
200:      *
201:      * Each shortcut handler receives an array with the
202:      * message and the priority of the entry.
203:      *
204:      * @param string $shortcut
205:      *         Shortcut name
206:      * @param string $handler
207:      *         Name of the function to call
208:      * @throws cInvalidArgumentException
209:      *         if the given shortcut is empty or already in use or if the
210:      *         handler is not callable
211:      * @return bool
212:      *         True if setting was successful
213:      */
214:     public function setShortcutHandler($shortcut, $handler) {
215:         if ($shortcut == '') {
216:             throw new cInvalidArgumentException('The shortcut name must not be empty.');
217:         }
218: 
219:         if (substr($shortcut, 0, 1) == "%") {
220:             $shortcut = substr($shortcut, 1);
221:         }
222: 
223:         if (is_callable($handler) == false) {
224:             throw new cInvalidArgumentException('The specified shortcut handler does not exist.');
225:         }
226: 
227:         if (array_key_exists($shortcut, $this->_shortcutHandlers)) {
228:             throw new cInvalidArgumentException('The shortcut ' . $shortcut . ' is already in use!');
229:         }
230: 
231:         $this->_shortcutHandlers[$shortcut] = $handler;
232: 
233:         return true;
234:     }
235: 
236:     /**
237:      * Unsets a specific shortcut handler.
238:      *
239:      * @param string $shortcut
240:      *         Name of the shortcut
241:      * @throws cInvalidArgumentException
242:      *         if the given shortcut handler does not exist
243:      * @return bool
244:      */
245:     public function unsetShortcutHandler($shortcut) {
246:         if (!in_array($shortcut, $this->_shortcutHandlers)) {
247:             throw new cInvalidArgumentException('The specified shortcut handler does not exist.');
248:         }
249: 
250:         unset($this->_shortcutHandlers[$shortcut]);
251:         return true;
252:     }
253: 
254:     /**
255:      * Buffers a log message for committing them on a later moment.
256:      *
257:      * @param string $message
258:      *         Message to buffer
259:      * @param mixed $priority [optional]
260:      *         Priority of the log entry (optional)
261:      */
262:     public function buffer($message, $priority = NULL) {
263:         $this->_buffer[] = array($message, $priority);
264:     }
265: 
266:     /**
267:      * Commits all buffered messages and empties the message buffer if parameter is not false.
268:      *
269:      * @param bool $revoke [optional]
270:      *         Flag, whether the buffer is cleared or not (optional, default: true)
271:      * @return bool|void
272:      */
273:     public function commit($revoke = true) {
274:         if (count($this->_buffer) == 0) {
275:             cWarning(__FILE__, __LINE__, "There are no buffered messages to commit.");
276:             return false;
277:         }
278: 
279:         foreach ($this->_buffer as $bufferInfo) {
280:             $this->log($bufferInfo[0], $bufferInfo[1]);
281:         }
282: 
283:         if ($revoke == true) {
284:             $this->revoke();
285:         }
286:     }
287: 
288:     /**
289:      * Empties the message buffer.
290:      */
291:     public function revoke() {
292:         $this->_buffer = array();
293:     }
294: 
295:     /**
296:      * Logs a message using the local writer instance
297:      *
298:      * @param string $message
299:      *         Message to log
300:      * @param mixed $priority [optional]
301:      *         Priority of the log entry (optional)
302:      */
303:     public function log($message, $priority = NULL) {
304:         if ($priority && is_int($priority) == false && in_array($priority, $this->_priorities)) {
305:             $priority = array_search($priority, $this->_priorities);
306:         }
307: 
308:         if ($priority === NULL || array_key_exists($priority, $this->_priorities) == false) {
309:             $priority = $this->getWriter()->getOption('default_priority');
310:         }
311: 
312:         $logMessage = $this->getWriter()->getOption('log_format');
313:         $lineEnding = $this->getWriter()->getOption('line_ending');
314: 
315:         foreach ($this->_shortcutHandlers as $shortcut => $handler) {
316:             if (substr($shortcut, 0, 1) != "%") {
317:                 $shortcut = "%" . $shortcut;
318:             }
319: 
320:             $info = array(
321:                 'message' => $message,
322:                 'priority' => $priority
323:             );
324: 
325:             $value = call_user_func($handler, $info);
326: 
327:             $logMessage = str_replace($shortcut, $value, $logMessage);
328:         }
329: 
330:         $this->getWriter()->write($logMessage . $lineEnding, $priority);
331:     }
332: 
333:     /**
334:      * Adds a new priority to the log.
335:      *
336:      * @param string $name
337:      *         Name of the log priority
338:      * @param int $value
339:      *         Index value of the log priority
340:      * @throws cInvalidArgumentException
341:      *         if the given name is empty, already exists or the value already exists
342:      */
343:     public function addPriority($name, $value) {
344:         if ($name == '') {
345:             throw new cInvalidArgumentException('Priority name must not be empty.');
346:         }
347: 
348:         if (in_array($name, $this->_priorities)) {
349:             throw new cInvalidArgumentException('The given priority name already exists.');
350:         }
351: 
352:         if (array_key_exists($value, $this->_priorities)) {
353:             throw new cInvalidArgumentException('The priority value already exists.');
354:         }
355: 
356:         $this->_priorities[$value] = $name;
357:     }
358: 
359:     /**
360:      * Removes a priority from log.
361:      * Default properties can not be removed.
362:      *
363:      * @param string $name
364:      *         Name of the log priority to remove
365:      * @throws cInvalidArgumentException
366:      *         if the given name is empty, does not exist or is a default priority
367:      */
368:     public function removePriority($name) {
369:         if ($name == '') {
370:             throw new cInvalidArgumentException('Priority name must not be empty.');
371:         }
372: 
373:         if (in_array($name, $this->_priorities) == false) {
374:             throw new cInvalidArgumentException('Priority name does not exist.');
375:         }
376: 
377:         if (in_array($name, $this->_defaultPriorities) == true) {
378:             throw new cInvalidArgumentException('Removing default priorities is not allowed.');
379:         }
380: 
381:         $priorityIndex = array_search($name, $this->_priorities);
382: 
383:         unset($this->_priorities[$priorityIndex]);
384:     }
385: 
386:     /**
387:      * Magic call method for direct priority named calls.
388:      *
389:      * @param string $method
390:      *         Name of the method
391:      * @param array $arguments
392:      *         Array with the method arguments
393:      * @throws cInvalidArgumentException
394:      *         if the given priority is not supported
395:      * @return void
396:      */
397:     public function __call($method, $arguments) {
398:         $priorityName = strtoupper($method);
399: 
400:         if (in_array($priorityName, $this->_priorities) == false) {
401:             throw new cInvalidArgumentException('The given priority ' . $priorityName . ' is not supported.');
402:         }
403: 
404:         $priorityIndex = array_search($priorityName, $this->_priorities);
405: 
406:         return $this->log($arguments[0], $priorityIndex);
407:     }
408: 
409:     /**
410:      * Shortcut Handler Date.
411:      * Returns the current date
412:      *
413:      * @return string
414:      *     The current date
415:      */
416:     public function shDate() {
417:         return date("Y-m-d H:i:s");
418:     }
419: 
420:     /**
421:      * Shortcut Handler Level.
422:      * Returns the canonical name of the priority.
423:      * The canonical name is padded to 10 characters to achieve a better formatting.
424:      *
425:      * @param array $info
426:      * @return string
427:      *         The canonical log level
428:      */
429:     public function shLevel($info) {
430:         $logLevel = $info['priority'];
431:         return str_pad($this->_priorities[$logLevel], 10, " ", STR_PAD_BOTH);
432:     }
433: 
434:     /**
435:      * Shortcut Handler Message.
436:      * Returns the log message.
437:      *
438:      * @param array $info
439:      * @return string
440:      *         The log message
441:      */
442:     public function shMessage($info) {
443:         return $info['message'];
444:     }
445: }
446: