Contributing

IMPORTANT: I'm working on version 0.2 now, and API's will change. But if you come up with a good plugin for the 0.1 branch, I will probably do the work to adopt it for 0.2.

There are two ways of contributing: Either you really help me writing and extending the core of HLI, or you write new plugins. At the moment, only dump plugins are supported, but I will change that to have functionalities like today's object reflection or backtrace managed via a plugin-interface and also have plugins for the output format.

I have just started to make more parts of HLI extendable by plugins. Currently the Dumper, Output and Vartype components are plugin-enabled, but only for Dumper there are more than one plugin. Output defaults to text/xml now but always uses the text/html plugin; and Vartype is the “type”-string or the object reflection.

All plugins whatever component they extend use this interface and API, but should extend the components abstract plugin.

Interface

To write a new Dumper plugin you simply have to implement the plugin interface found in core/abstract/PluginInterface.php. However, you are strongly advised to extend the abstract HLI_Dumper_Plugin class and call its constructors. This will allow me to extend the Interface as needed without breaking old plugins.

HLI_PluginInterface __construct(HLI_PluginAPI $API)
If you do not have to provide your own constructor, you should let this be handled by the components abstract plugin class. If you do provide your own constructor, call parent::__construct($API) first. Then you can access the API via $this->API.
bool static canHandle(mixed $data)
$data will be the value to dump. You can test here if the value is something you can work on and return true or false.
string getScript()
This will be called only once after canHandle() returned true and before getDoc(). Put your javascript code in here that should be printed out only once per page. Your js-code should be in the namespace HLI.Plugin.<YourPluginName>.
XML-string|DOMDocument getDoc(mixed $data)
Here you do your dump. Return the dumped data as string. Feel free to call your own methods from here.

API

Plugins are encapsulated from the rest of HLI and see only the HLI_PluginAPI object that gives them controlled access to tools and configurations.

string mark(mixed $data [, string $type [, string $hideblockId [, string &$hideblock ]]])
This is your path to the highlighter. Ways to use it:
  • mark($data): Highlight $data according to its type. Note that arrays and objects will NOT be dumped but will be returned as “Array[count()]” or “get_class()”
  • mark($data, $type): Highlight $data according to the $type-string. If you have to output some message (i.e. “recursion”), use mark($message, 'MSG')
  • mark($data, $type, $hideblockId): Works like call with two parameters, but will mark the $data also as the closing mark of a hideblock. Clicking on it will highlight the opening mark.
  • mark($data, $type, $hideblockId, $hideblock): Works like called with two parameters, but will also surround $hideblock with a mark to let it be hidden/displayed by clicking on $data. $hideblock is passed by reference! For $hideblockId pass a value returned by getHideblockId().
This method will be removed in version 0.2 and will be replaced by a set of methods for each type of highlighting.
string getHideblockId()
Get a value to be passed to mark() as fourth parameter. Each time you call this method, you will get a new value.
string getId()
If you need a unique id (e.g. for scripting), call this one. You will get a different id each time.
mixed getParam(string $name)
For some component-plugins there may be additional parameters set. Get error-save access to them here. Returns NULL if the parameter is not set.
bool isMessageString(mixed $data)
Throw any value in here. Will return true if $data is a message created by mark($message, 'MSG'). If you do recursive dumping, you will like this method.
string clearCommonPath(string $path)
If you have paths to display, you are strongly encouraged to use this method on them. It cuts off the part of the path that is common to all files in a project. But you should NOT use it on dumped data as this could be confusing.
HLI_Config $Config
Get read-only access to all config options.
bool autoReplaceHTMLEntities(bool $switch)
This is just an ad-hoc solution I needed in some places. The PluginAPI::mark() method will run htmlspecialchars on all output strings to make them valid XML. If you already did that, you should set this to false.