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:      * @throws cInvalidArgumentException
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:      *
183:      * @return cLogWriter
184:      */
185:     public function getWriter() {
186:         return $this->_writer;
187:     }
188: 
189:     /**
190:      * Sets the local writer instance.
191:      *
192:      * @param cLogWriter $writer
193:      *         Writer instacne
194:      */
195:     public function setWriter(cLogWriter $writer) {
196:         $this->_writer = $writer;
197:     }
198: 
199:     /**
200:      * Defines a custom shortcut handler.
201:      *
202:      * Each shortcut handler receives an array with the message and the
203:      * priority of the entry.
204:      *
205:      * @param string $shortcut
206:      *         Shortcut name
207:      * @param string $handler
208:      *         Name of the function to call
209:      * @throws cInvalidArgumentException
210:      *         if the given shortcut is empty or already in use or if the
211:      *         handler is not callable
212:      * @return bool
213:      *         True if setting was successful
214:      */
215:     public function setShortcutHandler($shortcut, $handler) {
216:         if ($shortcut == '') {
217:             throw new cInvalidArgumentException('The shortcut name must not be empty.');
218:         }
219: 
220:         if (cString::getPartOfString($shortcut, 0, 1) == "%") {
221:             $shortcut = cString::getPartOfString($shortcut, 1);
222:         }
223: 
224:         if (is_callable($handler) == false) {
225:             throw new cInvalidArgumentException('The specified shortcut handler does not exist.');
226:         }
227: 
228:         if (array_key_exists($shortcut, $this->_shortcutHandlers)) {
229:             throw new cInvalidArgumentException('The shortcut ' . $shortcut . ' is already in use!');
230:         }
231: 
232:         $this->_shortcutHandlers[$shortcut] = $handler;
233: 
234:         return true;
235:     }
236: 
237:     /**
238:      * Unsets a specific shortcut handler.
239:      *
240:      * @param string $shortcut
241:      *         Name of the shortcut
242:      * @throws cInvalidArgumentException
243:      *         if the given shortcut handler does not exist
244:      * @return bool
245:      */
246:     public function unsetShortcutHandler($shortcut) {
247:         if (!in_array($shortcut, $this->_shortcutHandlers)) {
248:             throw new cInvalidArgumentException('The specified shortcut handler does not exist.');
249:         }
250: 
251:         unset($this->_shortcutHandlers[$shortcut]);
252:         return true;
253:     }
254: 
255:     /**
256:      * Buffers a log message for committing them on a later moment.
257:      *
258:      * @param string $message
259:      *         Message to buffer
260:      * @param mixed $priority [optional]
261:      *         Priority of the log entry (optional)
262:      */
263:     public function buffer($message, $priority = NULL) {
264:         $this->_buffer[] = array($message, $priority);
265:     }
266: 
267:     /**
268:      * Commits all buffered messages and empties the message buffer if
269:      * parameter is not false.
270:      *
271:      * @param bool $revoke [optional]
272:      *         Flag, whether the buffer is cleared or not (optional, default: true)
273:      * @return bool|void
274:      */
275:     public function commit($revoke = true) {
276:         if (count($this->_buffer) == 0) {
277:             cWarning(__FILE__, __LINE__, "There are no buffered messages to commit.");
278:             return false;
279:         }
280: 
281:         foreach ($this->_buffer as $bufferInfo) {
282:             $this->log($bufferInfo[0], $bufferInfo[1]);
283:         }
284: 
285:         if ($revoke == true) {
286:             $this->revoke();
287:         }
288:     }
289: 
290:     /**
291:      * Empties the message buffer.
292:      */
293:     public function revoke() {
294:         $this->_buffer = array();
295:     }
296: 
297:     /**
298:      * Logs a message using the local writer instance.
299:      *
300:      * @param string $message
301:      *         Message to log
302:      * @param mixed $priority [optional]
303:      *         Priority of the log entry (optional)
304:      */
305:     public function log($message, $priority = NULL) {
306:         if ($priority && is_int($priority) == false && in_array($priority, $this->_priorities)) {
307:             $priority = array_search($priority, $this->_priorities);
308:         }
309: 
310:         if ($priority === NULL || array_key_exists($priority, $this->_priorities) == false) {
311:             $priority = $this->getWriter()->getOption('default_priority');
312:         }
313: 
314:         $logMessage = $this->getWriter()->getOption('log_format');
315:         $lineEnding = $this->getWriter()->getOption('line_ending');
316: 
317:         foreach ($this->_shortcutHandlers as $shortcut => $handler) {
318:             if (cString::getPartOfString($shortcut, 0, 1) != "%") {
319:                 $shortcut = "%" . $shortcut;
320:             }
321: 
322:             $info = array(
323:                 'message' => $message,
324:                 'priority' => $priority
325:             );
326: 
327:             $value = call_user_func($handler, $info);
328: 
329:             $logMessage = str_replace($shortcut, $value, $logMessage);
330:         }
331: 
332:         $this->getWriter()->write($logMessage . $lineEnding, $priority);
333:     }
334: 
335:     /**
336:      * Adds a new priority to the log.
337:      *
338:      * @param string $name
339:      *         Name of the log priority
340:      * @param int $value
341:      *         Index value of the log priority
342:      * @throws cInvalidArgumentException
343:      *         if the given name is empty, already exists or the value already exists
344:      */
345:     public function addPriority($name, $value) {
346:         if ($name == '') {
347:             throw new cInvalidArgumentException('Priority name must not be empty.');
348:         }
349: 
350:         if (in_array($name, $this->_priorities)) {
351:             throw new cInvalidArgumentException('The given priority name already exists.');
352:         }
353: 
354:         if (array_key_exists($value, $this->_priorities)) {
355:             throw new cInvalidArgumentException('The priority value already exists.');
356:         }
357: 
358:         $this->_priorities[$value] = $name;
359:     }
360: 
361:     /**
362:      * Removes a priority from log.
363:      * Default properties can not be removed.
364:      *
365:      * @param string $name
366:      *         Name of the log priority to remove
367:      * @throws cInvalidArgumentException
368:      *         if the given name is empty, does not exist or is a default priority
369:      */
370:     public function removePriority($name) {
371:         if ($name == '') {
372:             throw new cInvalidArgumentException('Priority name must not be empty.');
373:         }
374: 
375:         if (in_array($name, $this->_priorities) == false) {
376:             throw new cInvalidArgumentException('Priority name does not exist.');
377:         }
378: 
379:         if (in_array($name, $this->_defaultPriorities) == true) {
380:             throw new cInvalidArgumentException('Removing default priorities is not allowed.');
381:         }
382: 
383:         $priorityIndex = array_search($name, $this->_priorities);
384: 
385:         unset($this->_priorities[$priorityIndex]);
386:     }
387: 
388:     /**
389:      * Magic call method for direct priority named calls.
390:      *
391:      * @param string $method
392:      *         Name of the method
393:      * @param array $arguments
394:      *         Array with the method arguments
395:      * @throws cInvalidArgumentException
396:      *         if the given priority is not supported
397:      */
398:     public function __call($method, $arguments) {
399:         $priorityName = cString::toUpperCase($method);
400: 
401:         if (in_array($priorityName, $this->_priorities) == false) {
402:             throw new cInvalidArgumentException('The given priority ' . $priorityName . ' is not supported.');
403:         }
404: 
405:         $priorityIndex = array_search($priorityName, $this->_priorities);
406: 
407:         $this->log($arguments[0], $priorityIndex);
408:     }
409: 
410:     /**
411:      * Shortcut Handler Date.
412:      * Returns the current date.
413:      *
414:      * @return string
415:      *     The current date
416:      */
417:     public function shDate() {
418:         return date("Y-m-d H:i:s");
419:     }
420: 
421:     /**
422:      * Shortcut Handler Level.
423:      * Returns the canonical name of the priority.
424:      * The canonical name is padded to 10 characters to achieve a better
425:      * formatting.
426:      *
427:      * @param array $info
428:      * @return string
429:      *         The canonical log level
430:      */
431:     public function shLevel($info) {
432:         $logLevel = $info['priority'];
433:         return str_pad($this->_priorities[$logLevel], 10, " ", STR_PAD_BOTH);
434:     }
435: 
436:     /**
437:      * Shortcut Handler Message.
438:      * Returns the log message.
439:      *
440:      * @param array $info
441:      * @return string
442:      *         The log message
443:      */
444:     public function shMessage($info) {
445:         return $info['message'];
446:     }
447: }
448: