Login   Register  
PHP Classes
elePHPant
Icontem

File: TUTORIAL.TXT

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  Classes of Marius Zadara  >  Logger  >  TUTORIAL.TXT  >  Download  
File: TUTORIAL.TXT
Role: Documentation
Content type: text/plain
Description: Tutorial on logger
Class: Logger
Filter and export data of application events
Author: By
Last change:
Date: 6 years ago
Size: 4,881 bytes
 

Contents

Class file image Download
Hello!

	I'm glad to present you a new package, called Logger, that I use in my programs. 
	
	Like the name says, it is a logger used to track the events that appears in the activity of the program. Seems a simple task, but 
as the program gets bigger, sofisticated, the simple event consisting only of a message is not enought anymore. Therefore, you need
to add extra fields to the event, and then the tracking becomes hard.
	
	Why? Because of the event structure. Like I said, because of the event's new structure, deciding which event is caught and saved 
is not as simple as  before. You need to decide, and this decision is very important. That's where the Logger comes to fill the need with
it's new concepts: HANDLERS and EXPORTERS.

HANDLERS
---------
	A handler is a structure that does a simple task: accepting or refusing an event. In other words, it does the FILTERING based on the
structure of the event - category, levels, timestamp, etc. A logger can have multiple handlers, meaning multiple choises of deciding 
whether or not to export the event - therefore, the same event can now be exported in many ways at the same time: to the console, 
external file, database, mail, etc.

EXPORTERS
---------	
	Exporters are also simple structures (classes) that exports the event to either a database, file, or to console. It is associated to
a handler, meaning that a handler can have only one exporter, but inside the exporter's function you can do more than one thing, like
saving the event to database and mailing it to the person responsable of the application. 


HOW TO GET THINGS DONE
----------------------
	First of all, look and understand the program - is not that hard, but understanting the concepts is very important. Feel free to ask
any questions and post any suggetions to the e-mail address specified. 

	Second, the steps to put the Logger at work are as follows:

- define you way of accepting events - this is done with the help of handlers. Define your handler in the _classes/_handlers directory 
and don't forget to update the addClasses.php file. In your handler class, implement the "isEventAccepted()" function that must return
true or false depending of event acceptance - this event is passed as argument. Use the function from Event class to define your rules.

- define your exporter - this is done with the exporters defined in _classes/_exporters. In your exporter class, implement the function
"doExport()" that is responsable of event exporting. In this function you can use the ExporterException to signal the exceptions.

- associate the previously defined exporter to your event handler. 

- instanciate the main logger - class Logger;

- add the handler to the logger

- add events to the logger. This is the final step, when the new event is accepted or rejected by each of the logger's handlers. When a
handler indicates that accepts the event, then it's exporter is activated and the function "doExport()" is called. And this is done with
all the handlers of the logger, making possible to have multiple event acceptance and exporting. 


EXAMPLE
-------

(A) HANDLER ACCEPTANCE (only the function)

// accept all the events, regardless definition
public function isEventAccepted($event)
{
	return true;
}
	
or

// accepts only high-importance events
public function isEventAccepted($event)
{
	return in_array($event->getLevel(), array(Levels::$ERROR, Levels::$SEVERE, Levels::$CRITICAL, Levels::$CRITICAL)
}

or

....



(B) EXPORTER (only the function)

// export the event to the console
public function doExport($event)
{
	// display the event
	echo $event;
	
	// do something else ... 
}

or 

// export the event to external file
public function doExport($event)
{
	if (file_put_contents("filename", $event) === false)
		throw new ExporterException("Could not save the event");
		
	// do something else ...
}

or 
...


NOTES:
------
- For event's category, field, level and source are already defined constant classes. For consistency, is better to use them
instead of placing the values inside the code. 
- To format the event, especially when exported to the client console (web page), there is a special class, call Translation, 
where all the fields are translated, like event's source, category, level, etc. You can modify these translations. 
- For various event levels (INFO, FINEST, CRASH, etc), there are already defined functions.


	Not in the end, remember to read the LICENSE.TXT file before you use this software. And please enjoy this program and send
any comments or suggestions you may have to the e-mail address specified in file or post a reply to the forum. Either way you
choose, I will reply as soon as I can. 

Have fun!
(C) Marius Zadara, 2008.