06 – Creating and Importing KudzuPHP Libraries

The Library Manager:

In the previous tutorial Writing custom components for KudzuPHP we saw how easy it is to create custom tag handler components and install them into the template engine. In this tutorial I am going to introduce you to KudzuPHP library functionality and show you how easy it is to create entirely new libraries for the template engine and how to import them dynamically.

KudzuPHP has a library system where new libraries of tag handlers can be imported at run time. This feature allows you to extend the functionality of the template engine without requiring you to modify the PHP files that make up the core code. It also allows you to include only those libraries you need. If for example you are not planning to import and write an RSS feed out then you don’t need to have the WP_RSS code included.

The library manager is a class with a global instance: $KudzuLIB. This variable is globally scoped to insure that all instances of the template engine have access to the libraries that are imported that dynamic libraries are only imported once.

Library Files:

Individual libraries are stored in PHP code files that have a specific naming convention that corresponds to the name of the library. If we assume that we want to import a library named “MyLib” then the KudzuPHP library manager is going to require that file named “KudzuLib_MYLIB.php” resides on the file system within the current library folder – case is important here.

The library manager supports multiple code locations with a stack type functionality. This means that the last code location in wins in the event of a name conflict. The default library folder is initially set to the current folder (i.e. ‘.\’). You can change the default folder anytime by using the following call within PHP:

$KudzuLIB->setLibPath($myNewPath);

You can push and pop library paths off the stack using the following:

$KudzuLIB->libPushPath($myNewPath); $KudzuLIB->libPopPath();

At present there are no template tags that provide management of library pathing so it must be done in PHP.

An Example:

We’ve already see that the library files must be coded to a particular naming convention but what about the code inside the library files themselves? Like any PHP code file the format is up to you but there are a few basic requirements and suggestions. Let’s examine the example library that is included with KudzuPHP and see what it takes to make a code file a valid library file.

<?php
/*  
Module: KudzuLib_EXAMPLE.php
Description: An example on how to write a Kudzu Extension Library
Author: Andrew Friedl
Author URI: http://www.kazooplugin.com/
License: GPLv2 (see license.txt)
*/

// Library Class Definition
class CKudzuLibEXAMPLE {
	function tag_UCASE($node) {
		$eng = $node->getEngine();
		$node->stackPush();
		$node->evalNodes();
		$eng->setContent(strtoupper($eng->getContent()));
		$node->stackPop();
	}
	function tag_LCASE($node) {
		$eng = $node->getEngine();
		$node->stackPush();
		$node->evalNodes();
		$eng->setContent(strtolower($eng->getContent()));
		$node->stackPop();
	}
	function setTags($tagLib) {
		$tagLib->setTagFn('ucase','tag_UCASE',$this);
		$tagLib->setTagFn('lcase','tag_LCASE',$this);
	}
}

// Library Tag Installation
function KudzuLibImport_EXAMPLE($tagLib) {
	$obj = new CKudzuLibEXAMPLE();
	$obj->setTags($tagLib);
}
?>

The example library contains code for two tag handlers “lcase” and “ucase” that will be made available to template engines in your PHP page when the library is imported. If the import directive originated from a specific instance of a template engine either through PHP code or through the use of the “import” tag then the tag handlers will also be installed within that template engine. Other template engine instances including future instances would still need to import this library in order to use the tags within it. Regardless of the number of template engines running within a PHP page each library will only be imported by the library manager one time.

The PHP file containing the code resides in a path currently in the library manager and it must be named ‘KudzuLib_EXAMPLE.php’. The function “KudzuLibImport_EXAMPLE” at the bottom of the page is REQUIRED as it is this function that will be invoked to provide the library manager with new tag handlers. It is the duty of the individual library to install all tag handlers supplied by it.

Here’s a point to consider: Unlike the previous tutorial none of the tag handlers in the example are wrapped in their own class definition – they’re member functions of a single class object. Methods provided by the library manager make it easy to import global functions as well as class member functions like those above. Static functions are not supported at this time.

Naming conventions:

The naming convention of the files and the import function is non-negotiable. If the names are incorrect then your library import will fail. On the other hand you can name the tag handler functions and classes within your library anything you want but remember that your code will be imported dynamically. Pick reasonable names for your tag handler functions, classes and support code as you want to be able to include it without having to worry about name collisions with libraries created by others. I’ve found that the best methodology is to wrap as much code as possible within class definitions. One thing to watch for is to make sure that case of your actual functions exactly matches the case of the functions you provide to the library manager because PHP is case sensitive and you’ll get errors if there are mismatches.

Once you have your library built to specs (and debugged) you can simply drop it into the library folder with the other library files and it will be immediately available to the template engine. Your new library can be imported in two ways – either in PHP or by using the import tag. We’ve seen the PHP version of the import process above but there is also a custom tag handler that allows you to import one or more libraries during the processing of a template. It looks like this:

This tag directive requests the import of three library files: WP_RSS, MYLIB and EXAMPLE.