The WebAbility® Network Developers - Documentation
WebAbility Site
\core\WADebug reference

I. Structure:


- namespace:
\core\

- Does not have superclass

- Direct known subclasses:
\core\WASHM
\core\WAObject

II. Description:


This is the basic class to debug any executable code. This class keeps a log of the attributes, events, number of the instances and classes or in your application.

You must extend all your classes directly or indirectly from WADebug.
By default, the debug functions are unactivated so it does not affect the code eficiency.

The debug functions must be activated with the defined constant WADEBUG at the beginning of your code.
WADEBUG should have true/false value and setDebug() takes the value of WADEBUG by default.
WADEBUG set to true will have the effect to activate all the debug code into the WADebug class when it is created.

To set WADEBUG to true or false, you need to use a define:

define('WADEBUG', true);

Then you can activate the debug logging at application level with the static method setDebug(true).
Just be carefull, this can throw thousands of lines of debugging.

If you need the debug logging at instance level, you can use the method setLocalDebug(true).

by default:
global debug takes the value of WADEBUG.
local debug is always false.
level is always USER.
filter is not set.
redirect is HTML on HTML API, and ASCII on command line API.

The class keeps a track when the instance is created.

The debug methods getCreated() gives the microtime of creation of the instance.


III. Reference:


3.1. Contructor:


\core\WADebug()
Creates the instance. If the WADEBUG constant is set to true, it will create the debug code and attributes, and assign an unique ID to the instance.

3.2. Constants:


VERSION
Contains the actual DomCore version.

SYSTEM = 1
Constant to notify to the debug system to show all messages in a global level. This level should be used with caution since it can throw thousands of log lines in a session. The programmer should not use this debug level unless for extreme debug.

INFO = 2
Constant to notify to the debug system to show only informative messages level. Those messages report the most important steps into the libraries.

USER = 3
Constant to notify to the debug system to show only the user programmed messages level. Those messages level are set by the programmer into its own code. The programmer should only use this level.

HTMLREDIR = 1
Constant to notify to the debug system to show all messages into an HTML log on the browser itself.

ASCIIREDIR = 2
Constant to notify to the debug system to show all messages into an ASCII text message on the browser itself.

FILEREDIR = 3
Constant to notify to the debug system to show all messages into a file.

WINDOWS = 1
Constant to notify that we are working on a Windows operating system, any version.

UNIX = 2
Constant to notify that we are working on a Unix type operating system, any version or brand.

MAC = 3
Constant to notify that we are working on a Mac operating system, any version.

3.3. Attributes:


protected string $classname
Is used to store the name of the main class of the instance.

protected static enum $ostype
Is used to store the type of operating system where the application is running.
values: WADebug::WINDOWS, WADebug::UNIX, WADebug::MAC

protected static boolean $htmlapi
Is used to store the type of API we are working on: HTML or TEXT (command line).
values: true if we are on HTML mode.

protected static boolean $debug
Is a flag to indicate if the global debug mode is set or not.
values: true if we are in debug mode.

protected boolean $localdebug
Is a flag to indicate the instance is in local debug mode.
values: true if the instance is in debug mode.

3.4. Methods:


public void static setDebug($flag)
This method is used to activate or desactivate the global debug.
  • $flag: boolean, true to activate the global debug, false to stop the global debug.

public boolean static getDebug()
returns the global debug flag, true or false.

public boolean static getHTMLAPI()
Returns true if the API is working on HTML output (through a web server), of false if not (command line more in TEXT only).

public enum static getOSType()
Returns the type of operating system where PHP is running.
It is important to know the type of operating system for the following (not exhaustive) reasons:
  • On Windows:
- The hard disks are referenced with a letter with a column: A:, B:, C: etc.
- The paths of any directory or file are build with \ character.
- The line breaks are build with 2 characters: \n\r
  • On Unix:
- The hard disks have no names.
- The paths start with / and the level separator is /.
- The line breaks are build only with 1 character: \n
  • On Mac:
- The hard disks have no names.
- The paths start with / and the level separator is /.
- The line breaks are build only with 1 character: \r

public void setLocalDebug($flag)
This method is used to activate or desactivate the local debug.
  • $flag: boolean, true to activate the local debug, false to stop the local debug.

public boolean getLocalDebug()
returns the local debug flag, true or false.

public void static setRedirect($redir, $filename)
This method is used to define where the output of the debug logging is redirected.
  • $redir: enum{WADebug::HTMLREDIR ; WADebug::ASCIIREDIR ; WADebug::FILEREDIR}. Type of logging redirect.
  • $filename: string with the name of the file where to log the messages in case of the type is WADebug::FILEREDIR.

public enum static getRedirect()
Returns the type of redirect of logging, is one value of enum{WADebug::HTMLREDIR ; WADebug::ASCIIREDIR ; WADebug::FILEREDIR}.

public string static getRedirectFile()
Returns the name of the file where the messages are logged if the type is WADebug::FILEREDIR.

public void static setLevel($level)
This method assign the level of debugging messages.
  • $level: enum{WADebug::SYSTEM ; WADebug::INFO ; WADebug::USER}. Debugging desired level.
Only the messages of the desired level or superior are shown. SYSTEM is level 1, INFO is level 2, USER is level 3.

public enum static getLevel()
Returns the level of the debugging selected, enum{WADebug::SYSTEM ; WADebug::INFO ; WADebug::USER}.

public void static setFilter($filter)
This method assign a filter on the logged messages. The filter is a single string. If the filter is set, only the messages containing the string will be displayed.
  • $filter: string, contains the filter to apply. If the filter is empty or null, it removes the filter.

public enum static getFilter()
Returns the assigned filter.

public string getCreated()
Returns the unix timestamp when the instance has been created.

public string getClassName()
Returns the name of the instance origin class.

protected string doDebug($message, $level, ...)
This method sends a message to the debug system. The debug mode must be activated or the message will be ignored.
  • $message: string with the message to log.
  • $level: enum{WADebug::SYSTEM ; WADebug::INFO ; WADebug::USER} level of this debugging message.
  • ...: Any quantity of variables used to build the message.
Starting v2.0.0: The message has a sprintf format type, the '%' symbol represents every extra variable passed as parameter, in order. The old format is still compatible.

public integer static getNumTotalInstances()
Returns the total quantity of instances in the application.

public array static getAllInstances()
Returns the array of all quantities of the instances in the application.

public integer getNumInstances()
Returns the quantity of instances of the class type.

public integer getUIDInstance()
Returns the unique ID of this instance.

public string explain()
This methods permits to scan the instance and returns all the metrics in a descriptive text. It shows the unique ID, quantity of instances and total instances. If the API is on a webserver, the result will be an HTML text, if not, an ASCII text.
The attributes are representated in UML box syntax:
+ public attributes = value
# protected attributes = value
- private attributes = value
:: static attributes = value
In the case of the attribute is private, the value will be shown only if there is an existing get[attributename] function.

public string __toString()
Returns a description of the instance. Then description is build with the class name and the unique ID of the instance separated with a @ character.
It is recommended to create the __toString function for your own objects.