Initialization

There are three possible methods to create a Log object. You can create a Log_ object directly or call either the &singleton() or the factory() method of the Log class.

// direct initialization of the 'file' container 
$log = new Log_file('log.txt', 'identity text');

// initialization of the 'file' container through factory() 
$log = &Log::factory('file', 'log.txt', 'identity text');

// initialization of the 'file' container through singleton()
$log = &Log::singleton('file', 'log.txt', 'identity text');

Directly initializing an instance of the Log is probably the easiest method to understand.

The second two approaches make use of software engineering design patterns (the "factory" and "singleton" metaphors).

Specifically, calling the factory() method will create a new instance of one of the Log_ subclasses. The type of subclass that is returned is specified by the first parameter (log_type) passed to the factory() method. This approach effectively hides the subclasses while still allowing the programmer to request a concrete instance of a certain subclass. This is useful in cases where the subclass type needs to be chosen at runtime.

The factory() method must always be called using PHP's static method notation - Log::factory.

The singleton() method is identical to the factory() method except that it guarantees that only a single instance of the requested Log_ subclass exists. The singleton() method bases each instance's uniqueness on the parameters used in the instance's creation. In other words, only one instance with a given set of creation parameters will ever be returned by the singleton() method. The second invocation will simply return a reference to the existing instance.

The singleton() method must also be called statically. In addition, it requires PHP's reference notation - &Log::singleton.