What is Ladybug ?[edit]

Ladybug is a bug handler for MediaWiki pages. I made it to match my own needs, on my own website, which uses many templates and requires many transclusions to display a single page. The code of these templates is complex, and very hard to debug because of the number of their interactions. Thus, I wrote Ladybug.

MediaWiki already handles its own internal errors. So this never meant to be Ladybug's job. However, templates (or any other includable page) are unable to report sysops in case of bug, error or warning. Neither can they produce detailed reports about variables' or parameters' values. Ladybug was written to achieve such a detailed tracking.

How does it work ?[edit]

Ladybug is not one of these extensions which do all the job by itself. Changes need to be applied to the pages of the wiki.

Ladybug adds two new parser functions to MediaWiki:

{{ #Ladybug: }} which sends neutral reports to Ladybug
{{ #Ladyugh: }} which sends error reports to Ladybug

These two parser functions have to be added into the text of any wiki page you wish Ladybug to watch. They are like beacons, which inform Ladybug about what's going on right now.

With the first one ({{ #Ladybug: }}), you can inform Ladybug about a variable value, a parameter value, the beginning of a new execution stage, the result of a control structure, etc.

With the second one ({{ #Ladyugh: }}), you can inform Ladybug about a missing parameter, an unavailable article, or an invalid parameter value.

During all the execution time, Ladybug collects data. Then, it generates a report to make it readable.

Ladybug's features[edit]

Ladybug is able to do the following few things:

Listen to any kind of article for event or error messages.
Generate a full report to make such information readable. This report features:
- A chronology section, which show exactly what happened, when, and in what order;
- An entities section, which groups events of the same type under subsections;
- An errors section, which displays all the errors encountered during execution.
Log any error on a dedicated log page.
Act in standby mode when not needed: event collection is disabled when Ladybug is not used, whereas error collection is always enabled.
Deny its use to unallowed users via a special user right.
Fit anybody's needs: the source code was written so that new error or event types can be added quickly to the default ones.
Sanitize inputs: Ladybug cannot be used to output evil code.
Report its own internal errors: a special section will tell you about errors during Ladybug execution, or even about wrongly-used parser functions.

Base concepts[edit]

Ladybug uses standard parser functions, which only accepts three parameters:

an instruction
a subject
a predicate

The order of these parameters never changes: the first one is always an instruction, the second one a subject, and the last one a predicate.

Role of each parameter[edit]

Instructions are the most important parameter of a Ladybug call. They allow to define the call's goal (e.g.: "parameter_value"). {{ #Ladybug: }} and {{ #Ladyugh: }} do not share the same instructions set.
Subjects mostly define the item the call applies to (e.g.: a parameter name).
A predicate is what the call says about a subject (e.g: a parameter value).

Example[edit]

The following call: {{ #ladybug: parameter_value | myParameter | 33 }} tells Ladybug that

We'll send a parameter value (instruction)
The name of the parameter is "myParameter" (subject)
The value of the parameter is "33" (predicate)

Group instructions[edit]

When using the parser function which is dedicated to events ({{ #Ladybug: }}), you'll have to deal with group instructions. Group instructions begin with an operator, whereas simple instructions begin directly with an instruction name. The "parameter_value" instruction (from the previous example) is a simple instruction.

For now, there is only two valid operators in Ladybug: new and end.

new marks the beginning of a group instruction.
end marks the end of a group instruction.

Group instructions are instructions which are meant to include other instructions. For example, "loop" is a group instruction, since it will include several other instructions inside a loop structure. The correct syntax for such a case would be:

{{ #ladybug: new loop | while | i < 10 }}					We inform Laybug about the beginning of a new loop, with type "while" and condition "i < 10"

	{{ #ladybug: new iteration | myCounter | 1 }}				We inform Ladybug about the beginning of a new iteration, with counter variable "myCounter" = "1"
		{{ #ladybug: variable_value | myVariable | 10 }}		We inform Ladybug about the value of the variable "myVariable", which is "10"
	{{ #ladybug: end iteration }}						We inform Ladybug about the end of an iteration

	{{ #ladybug: new iteration | myCounter | 2 }}				We inform Ladybug about the beginning of a new iteration, with counter variable "myCounter" = "2"
		{{ #ladybug: variable_value | myVariable | 100 }}		We inform Ladybug about the value of the variable "myVariable", which is "100"
	{{ #ladybug: end iteration }}						We inform Ladybug about the end of an iteration

	...

{{ #ladybug: end loop }}							We inform Ladybug about the end of the loop

Installation & configuration[edit]

Installation[edit]

Copy the extension's files to the "extensions" directory of you MediaWiki installation.
Add the following lines to LocalSettings.php:

	# LadyBug
		// Loads the extension
			require_once( "$IP/extensions/LadyBug/LadyBug.php" );
		// Allows sysops to use LadyBug
			$wgGroupPermissions['sysop']['useladybug'] = true;

Now, you may check whether LadyBug is correctly installed: it should appear in the installed extensions list, on the 'Special:Version' page of your wiki.

Configuration[edit]

LadyBug's base configuration does not require parameters. However, you may wish to use custom settings. Here is how it works: Any custom setting has to be stored in the '$wgLadyBugCustomize'global array. This array must be defined in LocalSettings.php before the extension is loaded. It has the following structure:

$wgLadyBugCustomize = array(
	"setting1Name" => array(
		"value1",
		"value2",
		...
	),

	"setting2Name" => "singleValue"
);

If you wish to add several values to a single key (like for setting1Name), you may use an array as a key value. Here is a list of custom parameters:

validInstructions allows to add new instructions to Ladybug. You may add several instructions at the same time using an array.
validErrorInstructions allows to add new error instructions to Ladybug. You may add several error instructions at the same time using an array.
validErrorSubjects allows to add new error subjects to Ladybug. You may add several error subjects at the same time using an array.
customDivClassNames allows to add custom class names to Ladybug report sections. You may add several class names at the same time using an array.

User preferences[edit]

Ladybug adds a fieldset into the miscellanous section of user preferences. A logged user may disable Ladybug, hide report sections, or turn off javascript. Note that these settings have no consequences for other users, or guest (i.e.: not logged-in) users.

Syntax[edit]

Here are the default syntax rules for each parser function:

{{ #ladybug: }}[edit]

Simple instructions[edit]

parameter_check allows to inform Ladybug about the result of a parameter check:
- {{ #ladybug: parameter_check | parameterName | checkResult }}
  - parameterName is the name of the checked parameter.
  - checkResult is the result of the parameter check (generally "success" or "failure").

parameter_value allows to inform Ladybug about the value of a parameter:
- {{ #ladybug: parameter_value | parameterName | parameterValue }}
  - parameterName is the name of the parameter.
  - parameterValue is the value of the parameter.

variable_value allows to inform Ladybug about the value of a variable:
- {{ #ladybug: variable_value | variableName | variableValue }}
  - variableName is the name of the variable.
  - variableValue is the value of the variable.

condition_notice allows to inform Ladybug about the result of an alternative control structure like "if" or "else":
- {{ #ladybug: condition_notice | condition | result }}
  - condition is the condition which was tested.
  - result is the result of the test (generally "true" or "false").

Group instructions[edit]

pagename allows to inform Ladybug about the name of the current page. This instruction should be the first Ladybug call of any page, since Ladybug won't process anything if it can't find it.
- {{ #ladybug: new pagename | pagename | pageDescription }}...{{ #ladybug: end pagename }}
  - pagename is a full pagename (including namespace).
  - pageDescription is a description of what this page aims to do.

stage allows to define execution stages within the code:
- {{ #ladybug: new stage | stageName | stageDescription }}...{{ #ladybug: end stage }}
  - stageName is a short name for the stage.
  - stageDescription is a longer description of the stage.

loop allows to mark the beginning and the end of a loop structure:
- {{ #ladybug: new loop | loopType | loopCondition }}...{{ #ladybug: end loop }}
  - loopType is a usual loop type ("for", "while"...).
  - loopCondition is the loop execution condition.

iteration allows to mark the beginning and the end of a loop iteration. It is only used within a loop:
- {{ #ladybug: new iteration | counterName | counterValue }}...{{ #ladybug: end iteration }}
  - counterName is the name of the counter variable for the current loop.
  - counterValue is the value of the counter for the current iteration.

{{ #ladyugh: }}[edit]

Error instructions[edit]

The {{ #ladyugh: }} parser function only uses simple instructions. These instructions are called error instructions; their role is to tell Laybug about the severity of the error you wish to emit. So far, three error instructions are available:

info allows to emit a new "notification" error:
- {{ #ladyugh: info | missing_parameter | parameterName }}

warning allows to emit a new "warning" error:
- {{ #ladyugh: warning | missing_parameter | parameterName }}

error allows to emit a new "error" error:
- {{ #ladyugh: error | missing_parameter | parameterName }}

Error subjects[edit]

Moreover, this parser function also uses pre-defined subjects. They are called error subjects, and might be used with any error instruction:

missing_parameter allows to inform Ladybug about a missing parameter:
- {{ #ladyugh: error | missing_parameter | parameterName }}
  - parameterName is the name of the missing parameter.

invalid_parameter allows to inform Ladybug about an invalid parameter:
- {{ #ladyugh: error | invalid_parameter | parameterName }}
  - parameterName is the name of the invalid parameter.

missing_resource allows to inform Ladybug about a missing resource:
- {{ #ladyugh: error | missing_resource | resourceName }}
  - resourceName is the name of the missing resource.

missing_article allows to inform Ladybug about a missing article:
- {{ #ladyugh: error | missing_article | articleName }}
  - resourceName is the full page name of the missing article (including namespace).

Modders' stuff[edit]

Ladybug's files[edit]

/LadyBug.php is Ladybug's main entry point. It registers the extension, loads translations, registers hooks and loads default & custom settings.
/LadyBug.i18n.php contains translations of Ladybug messages.
/LadyBug.i18n.magic.php contains magicwords for Ladybug parser functions.
/script contains Ladybug's scripts
- /script/LadyBug.css contains Ladybug default CSS.
- /script/LadyBug.js contains Ladybug's javascript functions.
The /includes directory contains class definitions. Each file has the same name as the class it defines.
- /includes/LadyBug.php defines the main LadyBug class. An instance of this class is created by the /LadyBug.php file. A singleton avoids creation of more than one instance of this class.
- /includes/LadyBugEvent.php defines the "LadyBugEvent" class. Each event is an instance of this class.
- /includes/LadyBugError.php defines the "LadyBugError" class. Each error is an instance of this class.
- /includes/LadyBugInternalError.php defines the "LadyBugInternalError" class. Ladybug records its own internal errors into instances of this class.
- /includes/LadyBugReportSection.php defines the "LadyBugReportSection" class. Each section of a LadyBug report is an instance of this class.
- /includes/LadybugGenerators.php defines the "LadyBugGenerators" abstract class. This class cannot be instantiated, and owns one method per type of report section. Its job is to populate a report section (i.e.: to generate the contents of a report section).
- /includes/LadybugFormaters.php defines the "LadyBugFormatters" abstract class. This class cannot be instantiated, and owns one method per report section and object type (i.e.: chronologyLadyBugEvent() or entitiesLadyBugError()). Its job is to make the HTML or Wikitext output of an item, so that it can be included in a report section.

Ladybug's class hierarchy[edit]

- LadyBug							LadyBug main class
	|					
	|- LadyBugEvent				--------|
	|						|
	|- LadyBugError					|
	|						|	LadyBug items. Items can be instantiated.
	|- LadyBugInternalError				|
	|						|
	|- LadyBugReportSection			--------|
		|				
		|- LadyBugGenerators		--------|
			|				|	LadyBug workers. Workers cannot be instantiated. They populate their father-item (here: LadyBugReportSection).
			|- LadyBugFormatters	--------|

Examples[edit]

If you wish to change the way LadyBug renders data, you'll have to look at the LadyBugFormatters class.
If you wish to change the contents of a report section, you'll have to look at the LadyBugReportSection class.
If you wish to add or remove a report section you'll have to look at:
- the LadyBug class, and more precisely at the report() method, which creates, sorts, and outputs report sections;
- the LadyBugReportSection class, which contains methods for populating report sections (one per section type). You may need to add or remove functions here.
- the LadyBugFormatters class, which contains methods to render the each item of a report section. You may also need to add or remove functions here.
If you wish to add details to events, you'll have to look at:
- the LadyBugEvent class, to add properties and modify the constructor;
- the LadyBugFormatters class, to add instructions to display the contents of the newly created properties;
- (possibly) the LadyBug class, to add security checks to the newEvent() method.