functions_essentials_logging

Functions in file essentials/logging.php

logging_init

Initializes the logging mechanism. Will use the ini_get('error_log') setting to ensure working logger functionality by default. You may configure multiple loggers of different classes, default is 'Logger'. Specify configuration in CONFIG variable as follows: $CONFIG['system']['logging'][<alias>] = array(<key> => <value>); <alias> is a meanful name for the logger (in fact it can be used to log to only one logger instead of logging to all). Rest is an array of key-value pairs. Following keys are supported: 'path' := absolute path in filesystem where to log 'filename_pattern' := pattern of filename. see logging_extend_logger for details 'log_severity' := true|false defines if severity shall we written to logs 'max_filesize' := maximum filesize of logs in bytes (will start rotation if hit) 'keep_for_days' := when rotated (max_filesize is set) specifies how many days rotated logs will be kept 'min_severity' := minimum severity. see Logger class for constants, but define as string like so: "WARNING" 'max_trace_depth' := maximum depth of stacktraces 'class' := Class to be used as logger (when other that 'Logger', see TraceLogger as example)

Definition: public function logging_init()

Returns: void

logging_add_logger

Add a logger.

Definition: public function logging_add_logger($alias, $conf)

Returns: void

Parameters:

• string $alias Name for the logger

• array $conf Configuration as described in <loggin_init>

logging_remove_logger

Remove a logger.

Definition: public function logging_remove_logger($alias)

Returns: void

Parameters:

• string $alias Name for the logger

logging_get_logger

Returns a logger.

Definition: public function logging_get_logger($alias)

Returns: Logger

Parameters:

• string $alias Name of the logger to get

register_request_logger

Registers a class to act as request logger.

Definition: public function register_request_logger($classname)

Returns: void

Parameters:

• string $classname Classname of the handler, must be subclass of RequestLogEntry

logging_mem_ok

Checks if there's enough memory.

Definition: public function logging_mem_ok()

Returns: bool true if ok, else false

global_error_handler

INTERNAL Global error handler. See set_error_handler

global_exception_handler

INTERNAL Global exception handler. See set_exception_handler

global_fatal_handler

INTERNAL Global shutdown handler. See

logging_extend_logger

Extends a logger with a named variable. You may use this to recreate the logfile name. Variables used here will match placeholders in the logfile name (see filename_pattern config key). Currently all classes derivered from Logger know about the SERVER variable, so all keys in there will work without the need to call logging_extend_logger.

Samples: 'error{REMOTE_ADDR}.log' will become 'error_192.168.1.123.log' 'error{REMOTE_ADDR}{username}.log' will become 'error_192.168.1.123.log' until you call logging_extend_logger(<alias>,'username','daniels') and the be 'error_192.168.1.123_daniels.log'.

Note that setting extensions is only supported on a per logger basis, so you'll need a valid alias as set in initial configuration.

Definition: public function logging_extend_logger($alias, $key, $value)

Returns: void

Parameters:

• string $alias The loggers alias name

• string $key Key to use

• string $value Value to use

logging_add_category

Adds a category to all loggers.

Definition: public function logging_add_category($name)

Returns: void

Parameters:

• string $name Category to add

logging_has_category

Checks if a category has been added.

Definition: public function logging_has_category($name)

Returns: bool Whether the category is present.

Parameters:

• string $name Category to check for

logging_remove_category

Removes a category from all loggers.

Definition: public function logging_remove_category($name)

Returns: void

Parameters:

• string $name Category to remove

logging_set_level

Sets the minimum severity to log.

Definition: public function logging_set_level($min_severity)

Returns: bool

Parameters:

• string $min_severity A valid severity string

logging_set_user

DEPRECATED Use logging_add_category instead Tries to set up a category for a logged in user. Checks the object store for an object with id $object_storage_id that contains a field $fieldname. Then adds content of that field as category to all loggers.

Note: This will NOT extend the logger with information as logging_extend_logger does!

log_write

SHORTCUT Logs to specified severity

log_trace

SHORTCUT Logs to severity TRACE

log_debug

SHORTCUT Logs to severity DEBUG

log_info

SHORTCUT Logs to severity INFO

log_warn

SHORTCUT Logs to severity WARN

log_error

SHORTCUT Logs to severity ERROR

log_fatal

SHORTCUT Logs to severity FATAL

log_return

Logs the $label and $value arguments and then returns the $value argument. Use case:

function x($a){ return log_return("this is a",$a); }	

Definition: public function log_return($label, $value)

Returns: mixed $value

Parameters:

• string $label Label to log

• mixed $value Value to log

log_if

Calls log_debug if the condition is TRUE and then returns the condition. Use case:

log_if( !isset($some_var), "Missing data");	

Definition: public function log_if($condition, $args)

Returns: bool Returns the $condition itself (true|false)

Parameters:

• bool $condition true or false

• mixed $args Values to be logged

log_if_not

Calls log_debug if the condition is FALSE and then returns the condition. Use case:

if( log_if_not( isset($some_var), "Missing data") )	
{	
do_something_with($some_var);	
}	

Definition: public function log_if_not($condition, $args)

Returns: bool

Parameters:

• bool $condition true or false

• mixed $args Values to be logged

log_start_report

Starts a report named $name Returns an object of type LogReport, see doc there. Use log_report to finally write the report to logs.

Definition: public function log_start_report($name)

Returns: LogReport The new report

Parameters:

• string $name Report name

log_report

Writes a log-report to the logs. Use log_start_report to generate a report.

Definition: public function log_report(LogReport $report, $severity)

Returns: void

Parameters:

• LogReport $report The report to log

• string $severity Severity to log to

logging_render_var

Renders a variable into a string representation. Feel free to use alias function render_var instead as it is shorter

Definition: public function logging_render_var($content, $stack, $indent)

Returns: string The content rendered as string

Parameters:

• mixed $content Content to be rendered

• array $stack IGNORE (just to detect circular references)

• string $indent IGNORE (just to have nice readable output)

render_var

SHORTCUT logging_render_var

start_timer

Starts a named timer.

Definition: public function start_timer($name, $label=false)

Returns: string Timer name (the $name parameter)

Parameters:

• string $name Name of the timer

• string $label Optional label, defaults to $name

hit_timer

Set a marker in a named timer.

Definition: public function hit_timer($name, $label)

Returns: void

Parameters:

• string $name Timer name

• string $label Label to be written

finish_timer

Finishes a timer and writes it to log.

Definition: public function finish_timer($name, $min_ms=false)

Returns: void

Parameters:

• string $name Timer name

• int $min_ms Minimum milliseconds that must be reached for the timer to be written to log