1: <?php
  2: 
  3: /**
  4:  * This file contains the log class.
  5:  *
  6:  * @package    Core
  7:  * @subpackage Log
  8:  * @author     Dominik Ziegler
  9:  * @copyright  four for business AG <www.4fb.de>
 10:  * @license    http://www.contenido.org/license/LIZENZ.txt
 11:  * @link       http://www.4fb.de
 12:  * @link       http://www.contenido.org
 13:  */
 14: 
 15: defined('CON_FRAMEWORK') || die('Illegal call: Missing framework initialization - request aborted.');
 16: 
 17: /**
 18:  * This class contains the main functionalities for the logging in CONTENIDO.
 19:  *
 20:  * Examples:
 21:  * $writer = cLogWriter::factory("File", array('destination' => 'contenido.log'));
 22:  * $log = new cLog($writer);
 23:  *
 24:  * $log->addPriority("CONTENIDO", 10);
 25:  * $log->log("CONTENIDO Log Message.", "CONTENIDO");
 26:  * $log->contenido("Same log entry in short notation.");
 27:  * $log->removePriority("CONTENIDO");
 28:  *
 29:  * $log->emerg("System down.");
 30:  *
 31:  * $log->log('Notice Log Message', cLog::NOTICE);
 32:  *
 33:  * $log->buffer('Buffered Log Message', cLog::WARN);
 34:  * $log->commit();
 35:  *
 36:  * @package    Core
 37:  * @subpackage Log
 38:  */
 39: class cLog {
 40: 
 41:     /**
 42:      * logging level
 43:      *
 44:      * @var int
 45:      */
 46:     const EMERG   = 0;
 47: 
 48:     /**
 49:      * logging level
 50:      *
 51:      * @var int
 52:      */
 53:     const ALERT   = 1;
 54: 
 55:     /**
 56:      * logging level
 57:      *
 58:      * @var int
 59:      */
 60:     const CRIT    = 2;
 61: 
 62:     /**
 63:      * logging level
 64:      *
 65:      * @var int
 66:      */
 67:     const ERR     = 3;
 68: 
 69:     /**
 70:      * logging level
 71:      *
 72:      * @var int
 73:      */
 74:     const WARN    = 4;
 75: 
 76:     /**
 77:      * logging level
 78:      *
 79:      * @var int
 80:      */
 81:     const NOTICE  = 5;
 82: 
 83:     /**
 84:      * logging level
 85:      *
 86:      * @var int
 87:      */
 88:     const INFO    = 6;
 89: 
 90:     /**
 91:      * logging level
 92:      *
 93:      * @var int
 94:      */
 95:     const DEBUG   = 7;
 96: 
 97:     /**
 98:      * Contains the local log writer instance.
 99:      *
100:      * @var cLogWriter
101:      */
102:     protected $_writer;
103: 
104:     /**
105:      * Contains all shortcut handlers.
106:      *
107:      * @var array
108:      */
109:     protected $_shortcutHandlers = array();
110: 
111:     /**
112:      * Contains all available priorities.
113:      *
114:      * @var array
115:      */
116:     protected $_priorities = array();
117: 
118:     /**
119:      * Contains all default priorities.
120:      *
121:      * @var array
122:      */
123:     protected $_defaultPriorities = array();
124: 
125:     /**
126:      * Contains all buffered messages.
127:      *
128:      * @var array
129:      */
130:     protected $_buffer = array();
131: 
132:     /**
133:      * Constructor to create an instance of this class.
134:      *
135:      * The log format interface of cLog is capable of being extended by
136:      * subclasses. See the note about the log shortcuts below.
137:      *
138:      *
139:      * About Log Shortcuts
140:      * -------------------
141:      * Log shortcuts are placeholders which are replaced when a log
142:      * entry is created. Placeholders start with a percentage sign (%)
143:      * and contain one or more characters. Each placeholder is handled
144:      * by an own function which decides what to do.
145:      *
146:      * @param mixed $writer [optional]
147:      *         Writer object (any subclass of cLogWriter), or false if
148:      *         cLog should handle the writer creation
149:      */
150:     public function __construct($writer = false) {
151:         global $cfg;
152: 
153:         $createWriter = false;
154: 
155:         if ($writer == false) {
156:             $createWriter = true;
157:         } else if (!is_object($writer) || ($writer instanceof cLogWriter) == false) {
158:             cWarning(__FILE__, __LINE__, "The passed class is not a subclass of cLogWriter. Creating new one.");
159:             $createWriter = true;
160:         }
161: 
162:         if ($createWriter == true) {
163:             $options = array('destination' => $cfg['path']['contenido_logs'] . 'data/contenido.log');
164:             $writer = cLogWriter::factory("File", $options);
165:         }
166: 
167:         $this->setWriter($writer);
168:         $this->setShortcutHandler("%date", array($this, "shDate"));
169:         $this->setShortcutHandler("%level", array($this, "shLevel"));
170:         $this->setShortcutHandler("%message", array($this, "shMessage"));
171: 
172:         $this->getWriter()->setOption('log_format', '[%date] [%level] %message', false);
173: 
174:         $reflection = new ReflectionClass($this);
175:         $this->_priorities = $this->_defaultPriorities = array_flip($reflection->getConstants());
176:     }
177: 
178:     /**
179:      * Returns the local writer instance.
180:      *
181:      * @return cLogWriter
182:      */
183:     public function getWriter() {
184:         return $this->_writer;
185:     }
186: 
187:     /**
188:      * Sets the local writer instance.
189:      *
190:      * @param cLogWriter $writer
191:      *         Writer instacne
192:      */
193:     public function setWriter(cLogWriter $writer) {
194:         $this->_writer = $writer;
195:     }
196: 
197:     /**
198:      * Defines a custom shortcut handler.
199:      *
200:      * Each shortcut handler receives an array with the message and the
201:      * priority of the entry.
202:      *
203:      * @param string $shortcut
204:      *         Shortcut name
205:      * @param string $handler
206:      *         Name of the function to call
207:      * @throws cInvalidArgumentException
208:      *         if the given shortcut is empty or already in use or if the
209:      *         handler is not callable
210:      * @return bool
211:      *         True if setting was successful
212:      */
213:     public function setShortcutHandler($shortcut, $handler) {
214:         if ($shortcut == '') {
215:             throw new cInvalidArgumentException('The shortcut name must not be empty.');
216:         }
217: 
218:         if (substr($shortcut, 0, 1) == "%") {
219:             $shortcut = substr($shortcut, 1);
220:         }
221: 
222:         if (is_callable($handler) == false) {
223:             throw new cInvalidArgumentException('The specified shortcut handler does not exist.');
224:         }
225: 
226:         if (array_key_exists($shortcut, $this->_shortcutHandlers)) {
227:             throw new cInvalidArgumentException('The shortcut ' . $shortcut . ' is already in use!');
228:         }
229: 
230:         $this->_shortcutHandlers[$shortcut] = $handler;
231: 
232:         return true;
233:     }
234: 
235:     /**
236:      * Unsets a specific shortcut handler.
237:      *
238:      * @param string $shortcut
239:      *         Name of the shortcut
240:      * @throws cInvalidArgumentException
241:      *         if the given shortcut handler does not exist
242:      * @return bool
243:      */
244:     public function unsetShortcutHandler($shortcut) {
245:         if (!in_array($shortcut, $this->_shortcutHandlers)) {
246:             throw new cInvalidArgumentException('The specified shortcut handler does not exist.');
247:         }
248: 
249:         unset($this->_shortcutHandlers[$shortcut]);
250:         return true;
251:     }
252: 
253:     /**
254:      * Buffers a log message for committing them on a later moment.
255:      *
256:      * @param string $message
257:      *         Message to buffer
258:      * @param mixed $priority [optional]
259:      *         Priority of the log entry (optional)
260:      */
261:     public function buffer($message, $priority = NULL) {
262:         $this->_buffer[] = array($message, $priority);
263:     }
264: 
265:     /**
266:      * Commits all buffered messages and empties the message buffer if
267:      * 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:      */
396:     public function __call($method, $arguments) {
397:         $priorityName = strtoupper($method);
398: 
399:         if (in_array($priorityName, $this->_priorities) == false) {
400:             throw new cInvalidArgumentException('The given priority ' . $priorityName . ' is not supported.');
401:         }
402: 
403:         $priorityIndex = array_search($priorityName, $this->_priorities);
404: 
405:         $this->log($arguments[0], $priorityIndex);
406:     }
407: 
408:     /**
409:      * Shortcut Handler Date.
410:      * Returns the current date.
411:      *
412:      * @return string
413:      *     The current date
414:      */
415:     public function shDate() {
416:         return date("Y-m-d H:i:s");
417:     }
418: 
419:     /**
420:      * Shortcut Handler Level.
421:      * Returns the canonical name of the priority.
422:      * The canonical name is padded to 10 characters to achieve a better
423:      * 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: