Attributes

Attributes are “extra” bits embedded in source code that doesn’t necessarily mean anything in the language. Common examples include the documentation annotations in many comment systems (such as the tags used in Javadoc comments), JVM annotations, and .Net attributes.

A testing framework, for example, might use a TestFunction attribute to identify which methods should be called.

@TestFunction
public function testValidation() {...}

[TestFunction]
public function testValidation() {...}

Use cases

In Java EE you have “beans” which encapsulate business logic. Each bean requires a bunch of wrappers for remote access, “home” access (whatever that means), XML files, etc. Keeping all this relatively “boiler-plate” code in synch is painful. Annotating the bean classes and methods with attributes makes it possible to generate most of this automatically. No more manual synching XML files.

Java, though, (as of Java 5) has built in support for annotations and is a compiled language. This makes it relatively simple to do this analysis and generation at build time. PHP, on the other hand, doesn’t have an annotation mechanism and doesn’t have a built time.

Instead, Peter’s approach is to use PHP comments to add the attributes. At load time, these comments are processed using the reflection API and this is used to build a data structure to use for access control. See the permissions example.

A more complex case

To take this a little further, Peter wrote a Zend extension that makes it possible to [sort of] do aspect oriented programming (on function points) in PHP. The add_function_hook() function allows you to register an attribute and a callback and the extension will call your callback before a function with that attribute is executed:

<?php
class RequiresLogging
{

	/**
	 * @log notice "Secret action performed by user [user]
	 */
	public function secretAction()
	{
		// perform secret action...
	}

}

// 
// The callback function
//
function performLog( $message )
{
	$parts = split( " ", $message, 2 );
	$level = $parts[0];
	$message = $parts[1];
	Logger::log( $level, $message );
}

// 
// Register the callback
// 
add_function_hook( "log", "performLog" );

// Now code like this will result in a log message being recorded
$object = new RequiresLogging();
$object->secretAction();

This type approach is flexible and extremely powerful. You can inject permission checking code and raise an exception before the real function is even called.

There are a bunch of memory leaks and possible bugs in the Zend extension, but it is working and in production use!

He started with a list of things that have been removed or altered in PHP6 and then described some of the new features. Some of the things from both lists are present in version 5.3.

Removals and changes

In PHP6 E_ALL will include E_STRICT which may cause errors to be reported in code that is OK in PHP5. A new E_DEPRECATED has been introduced and is also included in E_ALL. This new error is raised when you use any deprecated functions.

These deprecated functions and features include register globals, magic quotes, safe mode and ASP-style <% %> tags. Also going/gone are the $HTTP_POST_VARS and $HTTP_GET_VARS variables.

Other changes include assign-by-reference (using =&) and zend_compat raising E_STRICT. Class members defined without a visibility modifier will be public by default (and will also raise E_STRICT).

Dynamically loading extensions is now disabled by default on all SAPIs except the command-line interpreter. This needs to be enabled (in php.ini, I assume) if required.

In a rather acrobatic backflip, the formerly deprecated $str[1] is no-longer deprecated and its replacement $str{1} now is deprecated. You can also now use the subscript syntax to take a slice of a string – like $str[1,3] – as you in some other languages.

The wacky variable break feature (where one breaks out of a variable number of looping constructs: break $anint;) is deprecated. It’s disappearance make me wonder (again) why it was added in the first place. I can’t help but wonder if there was a use-case in mind, or if it was just “because”.

The microtime() function now returns the float value by default; you’ll no longer need to use microtime(TRUE) in every invocation.

The move to using the PCRE-based preg_* functions for regular expressions is finally complete. The ereg_* functions have been removed from core and stuck in a PECL extension. At the same time, mime_magic has also been moved to a PECL extension and its more useful and popular cousin fileinfo has replaced it in core.

Additions

The big ticket new item must be namespaces. The controversial choice to use backslash as the separator was due to the simple fact that it is the only single character available. This doesn’t make it any less silly, especially because of the way that function “references” in PHP are just strings:

$func = "\application\names\afunc";
$func();

All names refer to the current namespace, but prefixing a name with a backslash will make it relative to the “root” namespace.

You can import things from other name spaces with the use keyword and, if required – perhaps there is a clash – alias them by taking an as clause on the end:

use \MyCompany\Blog\User as BlogUser;
use \MyCompany\CMS\User as CMSUser;

Functions and classes both belong to namespaces and definitions are processed top-down. Thus the following code defines a foo() function and then a bundle\foo() function:

function foo() { echo "G"; }

namespace bundle;

function foo() { echo "NS"; }

bundle\foo(); // "NS"
foo(); // "G"

Another important change is the addition of late static binding. In previous versions of PHP self::foo in the code of a superclass method refers the foo member of that superclass, even if the subclass defines a foo member. This problem is ameliorated with the addition of a new static keyword. static::foo will do what you expect: look in subclass, then in the parent/s.

All in all, it looks like PHP6 is a great big leap forward in the evolution of PHP. A few more major versions and it might catch up to modern languages.

The problem, it seems, lies in SPIP’s use of locking to serialise access to a number of files containing cached data. In essence: SPIP seems to deadlock when attempting to lock certain files in the /tmp/ directory. This hangs the PHP process (FastCGI, in our case) which consumes resources and, eventually, prevents the web-servers from being able to serve requests for PHP. To make a bad problem even worse, we seem to be the only people to experience this problem. Literally no-one else in the SPIP community has ever encountered it!

As a first step in trying to diagnose and resolve the problem, I’ve instrumented the code that implement’s SPIP’s locking techniques to log all locking operations. Thankfully, this is relatively easy as SPIP wraps the actual flock calls with its own spip_fopen_lock() and spip_fclose_unlock() functions defined in /ecrire/inc/flock.php.

I can’t use the built in SPIP logging functions because they use the locking functions I’m trying to instrument to prevent interleaving of log messages. The obvious choice (and far superior to spip_log(), in my opinion) is using the syslog protocol supported by pretty much everything that matters (i.e. everything UNIX and lots of networking gear). Alas, PHP’s built-in syslog() function logs to the local syslog daemon. Instead, I’ve used a small class that implements a Pure PHP syslog client.

Rather than copy-‘n’-paste a bunch of code into the SPIP locking functions, I’ve created a function to figure out what the message should be¹ and then log it. logtrace() creates a PHP backtrace and inspects it to determine which function (lock or unlock) it is logging and which function (of the dozen or so alternatives) called it. Once it’s figured that out, it uses a static instance of the Syslog class to send the message to the log server. The code is simple:

<?php

require_once('syslog.php');

@define("_SYSLOG_SERVER", "192.168.1.1");

function logtrace() {
	// The syslog client
	static $log;
	if (! $log) {
		$pid = getmypid();
		$log = new Syslog();
		$log->SetProcess("PHP-$pid");
		$log->SetIpFrom($_SERVER['REMOTE_ADDR']);
	}

	// Get the functions from the backtrace
	$bt = debug_backtrace();
	$callee = $bt[1];
	$caller = $bt[2];
	
	// Build and log the message
	$func = $callee['function'].'('.$callee['args'][0] .')';
	$from = $caller['function'].'('. $caller['args'][0] .')';
	$log->Send(_SYSLOG_SERVER, "$func from $from");
}

With that defined, it’s just a matter of adding a call to logtrace() to spip_fopen_lock() and spip_fclose_unlock() in /ecrire/inc/flock.php and we get log messages something like this²:

Nov  3 13:54:07 server2.example.com WEBSERVER PHP-1234: www.example.com 10.10.10.10 spip_fopen_lock(../tmp/verifier_plugins.txt, ...) from lire_fichier(../tmp/verifier_plugins.txt, ...)
Nov  3 13:54:07 server2.example.com WEBSERVER PHP-1234: www.example.com 10.10.10.10 spip_fclose_unlock(Resource id #69, ...) from lire_fichier(../tmp/verifier_plugins.txt, ...)

Of course, this is not enough information to debug the locking problems – I’ll also need the IP address of the client and the PID of the PHP interpreter to distinguish interleaved messages from concurrent requests – but it’s a start.

More than just decoration

Using a decorator looks (in Python) like this:

@a_decorator
def a_function(an_arg):
    return "Functionate: %s!" % (an_arg)

Where a_decorator is some function or other which takes an argument (a_function, in this particular case) and returns a value. When Python loads a module containing this code it creates a new function a_function as normal, but then it calls a_decorator on it and binds the value it returns to the name a_function rather than the original function created from the definition. So how do we write these decorators? Just like a normal function!

def a_decorator(the_func):
    """
    Make another a function more beautiful.
    """
    def _decorated(*args, **kwargs):
        return the_func(*args, **kwargs)
    return _decorated

But what about parameterised decorators? It’s just a little more involved. Recall that you use a decorator like this: @the_decorator. It turns out that such decorator statements don’t just name a decorator to be called, but can also call a function to return a decorator to be called:

def wrap_in_a(tag):
    """
    Wrap the result of a function in a `tag` HTML tag.
    """
    def _dec(func):
        def _new_func(*args, **kwargs):
            return "<%s>%s</%s>" % (tag, func(*args, **kwargs), tag)
        return _new_func
    return _dec

@wrap_in_a('div')
@login_required
def my_name(request):
    return request.user.first_name

The first decorator statement @wrap_in_a('div') calls wrap_in_a('div') which returns a function (_dec). This function is then applied to the following definition (@login_required applied to my_name). Simple!

It’s probably a good idea to add a few more bits and pieces to the function returned by a decorator (copying __doc__ and __dict__, for instance), but that’s the core of it.

Using it in Django

So this is all pretty cool, but how do we use it in Django? We’ll here’s a anonymous_required decorator that you can use to redirect authenticated users to their home page if they try to login again:

def anonymous_required(function=None, home_url=None, redirect_field_name=None):
    """Check that the user is NOT logged in.

    This decorator ensures that the view functions it is called on can be 
    accessed only by anonymous users. When an authenticated user accesses
    such a protected view, they are redirected to the address specified in 
    the field named in `next_field` or, lacking such a value, the URL in 
    `home_url`, or the `USER_HOME_URL` setting.
    """
    if home_url is None:
        home_url = settings.USER_HOME_URL

    def _dec(view_func):
        def _view(request, *args, **kwargs):
            if request.user.is_authenticated():
                url = None
                if redirect_field_name and redirect_field_name in request.REQUEST:
                    url = request.REQUEST[redirect_field_name]
                if not url:
                    url = home_url
                if not url:
                    url = "/"
                return HttpResponseRedirect(url)
            else:
                return view_func(request, *args, **kwargs)

        _view.__name__ = view_func.__name__
        _view.__dict__ = view_func.__dict__
        _view.__doc__ = view_func.__doc__

        return _view

    if function is None:
        return _dec
    else:
        return _dec(function)

It’s probably not very Django-ish, but you get the impression. Just use it like Django’s built-in login_required decorator:

@anonynous_required
def a_view(request):
    return HttpResponse("We are anonymous! We are legion!")

Comments and suggestions welcome!

Update: Amended the example decorator above to work correctly as @anonymous_required, @anonymous_required(...) or foo = anonymous_required(foo).

Checking that a user if authorised to perform an action is a little more haphazard than I’d like in SPIP (“No authorisation check? No worries!” is not a particularly comforting approach), but it seems to get the job done even if it does depend on more developer discipline than seems warranted. Checking that a user is “authorised” to perform an action is done by calling the autoriser() function with arguments to describe the operation. If it returns true then the operation is authorised, it not, then it isn’t.

Like most of SPIP’s core functions, autoriser is implemented in a way that makes it easy to override and extend its functions: rather than make any decision itself, it simply delegates the decision to the first function it finds that can decide for that type of operation and object (or object, or operation).

First, though, lets look at autoriser’s arguments:

function autoriser_dist($faire, $type='', $id=0, $qui = NULL, $opt = NULL)

This first (and only required) argument is $faire (French, I’m told, for “to do”) which takes a string: the name of the operation. The second argument $type is another string: the type of object being operated on; and the third is an integer: the ID of the particular object, if there is one. The fourth, $qui (“who”) is an array of details of the current user; and the fifth, I assume, is an array of optional values if the previous four are not enough to make some decisions).

Only the first of these – the operation being performed – is required and only the first should need to be specified in the vast majority of situations (it’ll work out the user by itself and there are many operations without a $type or an $id). Once it’s been called, autoriser uses these values to look for a function that can make a decision for the given type and operations.

You can see the code of /ecrire/inc/autoriser.php (around line 87) for the particular functions that it will call, but the full list of alternatives that ‘’autoriser($faire, $type, $id, $qui, $opts)’’ is (in order of preference):

1. autoriser_$type_$faire()
2. autoriser_$type()
3. autoriser_$faire()
4. autoriser_default()
5. autoriser_$type_$faire_dist()
6. autoriser_$type_dist()
7. autoriser_$faire_dist()
8. autoriser_default_dist()

Adding authorisation checks to your plug-in is easy: just implement one of these checking functions (in a file that’ll be included by a <fonctons> entry in your plugin.xml file is probably best) and then get autoriser to call it when appropriate.

From aplugin_fonctions.php or some other file:

/**
 * Perform authorisation checks for "elephant" objects.
 */
function autoriser_elephant($faire, $type='elephant', $id=0, $qui=NULL, $opt=NULL) {
   if ( '0minirezo' == $qui['statut'] ) {
       return true;
   }
   return false;
}

With this code in place, only administrators will be able to perform actions (or, strictly speaking, perform actions checked with the autoriser function) on elephant objects. Any call specifying $type='elephant' will use the above function to determine if the operation should proceed.

In exec/anaction.php or similar, we might use code like this:

if ( autoriser('kill', 'elephant', $id_elephant) ) {
   launch_missiles_at('elephant', $id_elephant);
} else {
   echo _T('aplugin:cannot_shoot_elephant'), _T('aplugin:permission_denied');
}

Which will try the following functions, in order, to decide whether or not to launch_missiles_at() our poor elephant:

1. autoriser_elephant_kill()
2. autoriser_elephant()
3. autoriser_kill()
4. autoriser_default()
5. autoriser_elephant_kill_dist()
6. autoriser_elephant_dist()
7. autoriser_kill_dist()
8. autoriser_default_dist()

That’s about all there is to it. Of course, there’s a lot more you can do to make your authorisation decisions: per-user and per-object configurations you might like implement (similar to the way SPIP allows us to restrict administrators and editors “to a section”), time-based or geographic restrictions (editing during working hours only, or from an IP address in Africa), or restricting access to those within your organisation’s network.

The world of authorisation is your oyster!

As usual, you’ll need to know PHP, and the SPIP template language before this will make much sense, and I’d recommend reading my posts about creating static tags, dynamic tags, and faking tag arguments as well.

SPIP tags are just a specially named function that accepts an AST node as a parameter and returns that AST node modified so that the code generator will generate the PHP code to implement the function. With static tags this means filling the node with some PHP code that evaluates to a string (often just a string literal with, perhaps, some variable interpolation). The functions for dynamic tags, on the other hand, fill their AST node with PHP code that, when evaluated by the code generator, generates more PHP. This second piece of PHP will form part of the page template and will [potentially] be evaluated at each request.

Different but same

It’s sometimes desirable to make certain tags available under more than one name. The canonical example of this from SPIP’s built-in tags is #INCLURE/#INCLUDE. Rather than provide just the French #INCLURE tag or just the English (and PHP-ish) #INCLUDE, SPIP provides both. This can help make your API more user friendly and is easy enough to do: just define a second tag function that calls the first (notice that I check for an overriding version of my original tag implementation and call that instead):

    /* The original tag */
    function balise_FOO_dist($p) {
        $p->code = "'This is foo'";
        return $p;
    }

    /* The additional name */
    function balise_BAR_dist($p) {
        if ( function_exists('balise_FOO') ) {
             return balise_FOO($p);
        } else {
             return balise_FOO_dist($p);
        }
    }

Similar but different

If you’re looking for identical functionality under a different name (see #INCLURE and #INCLUDE), this is all you need, but imagine that you, like me, have a number of tags with related but slightly different functionality. You could implement each of them – copy-and-pasting the code and changing perhaps a single variable – or extract the common code into a set of library functions – slowing things down slightly – or you could implement a generic tag and a number of wrappers around it. SPIP does this in a number of places, but the best example is the #ENV, #CONFIG and #GET tags, each of which are actually implemented by the same piece of code (the balise_ENV_dist function, as it turns out).

This is easily accomplished by adding a second, optional, parameter to your main tag function and then passing different values from your stub tags. This is the approach that #ENV, #CONFIG, and #GET use: balise_ENV_dist check the environment by default, but if it’s passed a second parameter (the '$GLOBALS["meta"]' that #CONFIG passes it, for example), then it operates on that instead.

Mangling for fun and profit

A second, but rather more involved, option for passing values into other tags is described in my faking tag arguments post. This can be useful when you don’t control the code that you are wrapping. Perhaps you want to modify the #MODELE tag in such a way that it adds the name and line number of the tag to the environment of the model it calls. Rather than duplicating the code for balise_MODELE_dist and modifying it slightly, you could write a wrapper around it balise_MODELE and just add another two parameters (skeleton and line) to the AST before calling balise_MODELE_dist. As far as balise_MODEL_dist is concerned, it’s as though some conscientious web-master has gone through every template adding {skeleton=filename}{line=123} to every call.

The difficult bit is to modify the AST correctly, but that’s not too hard and you can read the post to find out how.

Conclusion

This is a powerful technique that can simplify the code for plug-ins with large numbers of similar tags immensely. Rather than producing large amounts of “boiler-plate” code, or defining large libraries of API functions, I can just reuse my existing generic code in ways that hide it’s complexity and power, thereby making the API much more simple and obvious to my users.

You should know about the SPIP, its template language, static tags, dynamic tags and be comfortable with PHP before reading this article.

Unlike static tags – which are implemented by a single function – dynamic tags are comprised of a set of three functions (in a magically named file) which are called by the SPIP engine as appropriate. This first of these three functions (identical to the single function of static tags) is called something like balise_FOO() and is responsible asking SPIP to call the other two functions: balise_FOO_stat() – which performs whatever static calculations are required – and balise_FOO_dyn() which performs the dynamic calculations and display the final content to the user.

An example might make this more clearer. Suppose I’m creating a #HITS tag to output the number of hits an article has received. My balise_HITS function arranges for SPIP to call the balise_HITS_* functions like so:

1. It calls balise_HITS_stat to determine the static parameters for the tag (e.g. “id_article=36”).

2. It arranges to call balise_HITS_dyn, passing it the static parameters as determined by balise_HITS_stat.

3. balise_HITS_dyn uses the static parameters to query the database, etc. and produces the appropriate output.

The code to implement the #HITS tag might look like this:

function balise_HITS($p, $nom='HITS') {
    $args = array('id_article');
    return calculer_balise_dynamique($p, $nom, $args);
}

function balise_HITS_stat($args, $filters) {
    return array($args[0]);
}

function balise_HITS_dyn($id_article) {
    $now = date('c');
    return "Article $id_article has had 1,000,000 hits as of $now!";
}

One way this can fall down is if I want to access details of, for example, the SPIP templates in determining my static parameters. By the time I’m determining the parameters, I no longer have access to the abstract-syntax tree node passed to balise_FOO. All I’ve got at this point, is an array of arguments to the tag and an array of filters applied to the tag.

The obvious solution

The obvious solution is to add the value to the “$args” array I pass to calculer_balise_dynamique(). Alas, this will not work as $args is not (in spite of its usual name) an array of arguments. It is, in fact, an array of the names of arguments which SPIP is to automatically fetch and pass on the the balise_*_stat() call. Appending the name of the template file ("squelettes/foo.html", for instance) to $args tells SPIP to look for a variable called squelettes/foo.html in the context the tag is being used and pass it through to the next function. Needless to say, this doesn’t work.

The correct solution

The correct solution to this problem is to arrange for SPIP to add the values you want to the $arguments array (or perhaps the $filters array, but this may not be a good idea). This array contains the values I requested in the call to calculer_balise_dynamique along with the values of the parameters passed into the tag in the template. If I can’t use the former route, then it’ll have to be the second – I’ll need to add a another “fake” parameter to the AST node before I call calculer_balise_dynamique. (Yes, I agree. This is a rather odd way to accomplish my goal, but that’s how it goes in SPIP-land).

There are two parts of the SPIP AST that are relevant here: the Champ nodes that represent tags, and the Texte nodes the represent “strings” (amongst other things). The $p that is passed to my balise_* functions is an instance of the Champ class and I’m going to add a new instance of the Texte class representing my new “fake” parameter. Creating the new object is pretty simple, just construct it and set it’s type and texte members. The following example adds a new parameter containing the name of the template file:

function balise_TEMPLATE($p, $nom='TEMPLATE') {
    $file = $p->descr['sourcefile'];

    // Create the new object
    $t = new Texte;
    $t->type = 'texte';
    $t->texte = $file;

    // Make sure that $p-param is an array (of the right dimensions)
    if (! is_array($p->param) ) {
        $p->param = array(array(0=>NULL));
    }

    // Append the object to the tag parameters
    $p->param[0][] = array($t);

    // Call SPIP's dynamic tags code
    $args = array();
    return calculer_balise_dynamique($p, $nom, $args);
}

First the previous code gets the name of the template file from the AST node for the tag being processed. Then it creates a new Texte object with the filename as its value. It ensures that the $p->param member of the Champ object is an array (and yes, it does seem to start with a NULL so that we can pretend that the arrays are 1-indexed) and then appends the new object to it. All that’s left is to call calculer_balise_dynamique as usual.

With this done, the value of the new “fake” parameter will be evaluated and passed to the balise_TEMPLATE_stat() call in the $args array and then (if I choose) passed on to the balise_TEMPLATE_dyn() call.

Conclusion

This technique still strikes me as a bit odd, but it’s the only way I can see to implement this effect without introducing global variables. In my opinion, calculer_balise_dynamique should take an array of argument values as an optional fourth argument, but needing to do this sort of thing is probably fairly rare (though I have seen it in the code for one or two built-in tags). Even if this technique is the “Right Way(TM)” to pass extra values around, then it really does need a helper function like interprete_argument_balise instead of mucking around with AST internals in every tag that need it.

Lots of SPIP tags and filters generate HTML mark-up as output (the #LOGO_* tags and |image_* filters are the most prominent) and we often need or want to modify this mark-up in our templates. There are several built-in filters to help with this (inserer_attribut to insert an attribute and extraire_attribut to extract the value of an attribute) but they are pretty long and tedious to type. Given that I uses these filters quite often when implementing such things as image galleries, and I still have to think quite hard to type the French words correctly the can be a bit annoying. Thankfully, a small wrapper (see below) can smooth these small annoyances away.

When it comes to accessing and modifying the values of attributes nothing, in my opinion, comes any where near to jQuery’s attributes API. The single jQuery attr method allows you to get and set the value for any attribute on any node: it takes one or two parameters, the name of the attribute and, optionally, the value. If only the name is specified, then attr simply extracts and returns the value of the attribute. If both a name and a value are specified, then attr modifies the object setting specified attribute to the specified value. This “polymorphic” style of interface – where a single method has two complementary behaviours which are distinguished by the number and/or types of the arguments – is everywhere in jQuery and is part of what makes it so concise and so productive. Seeing as it’s the best structure for such interfaces that I know (and also, one I use daily), I decided that my wrapper should mirror it. Thus the attr filter was born.

Like the jQuery attr method, the SPIP attr filter takes one or two parameters (and an implicit “object”, but we’ll ignore if for now). If only one, it passes the input on to extraire_attribut to get and return the value. If called with two parameters, it calls inserer_attribut instead to modify the tag. Like the idea, the code is reasonably straightforward; the only even slightly unusual but is the use of func_get_args to get an array of the arguments passed into the function call. With such an array, we can use count to check how many arguments the function was given and decide whether we should get or set the attribute. This is safer than specifying and checking a default value (FALSE or NULL, for example) because some user may genuinely want to use that value (perhaps NULL will mean delete the attribute in a future version?) and silently ignoring user input is never good.

<?php
include_spip("inc/filtres");

/**
 * The `attr` function allows the user to get and set the attributes of an
 * HTML tag. It is intended to be used as a SPIP filter and depends on 
 * existing SPIP functionality.
 *
 * @param $tag
 *     The HTML code.
 * @param $name
 *     The name of the attribute.
 * @param $val...
 *     The new value for the attribute $nom. Optional.
 * @return
 *     If $val was given, the code for tag with $name=$val
 *     Otherwise, the value for the $name attribute in $tag.
 */
function attr($tag, $name){
        $args = func_get_args();
 
        if (count($args) > 2) {
                // SET
                return  inserer_attribut($tag, $name, $args[2]);
        } else {
                // GET
                return extraire_attribut($tag, $name);
        }
}

Simply copy the code into the mes_fonctions.php file for your site (see “Adding your own filters” in SPIP’s Filters) and use attr in your SPIP templates:

<a href="[(#FICHIER|attr{src})]" class="lightbox" title="#TITRE">
    [(#FICHIER|image_reduire{100,100}|attr{alt,#TITRE})]
</a>

There are a few changes that could be made to this function: passing $args directly to inserer_attribut and extraire_attribut rather than the individual variables, adding a $value=FALSE parameter for the sake of documentation and then ignoring it (I’m not sure if this will work and don’t care enough to try it), deleting attributes when passed e.g. NULL as a value, etc. For the time being, however, it does the job.

A final note: you’ll probably need to be running PHP 5 for this to work – the func_get_args documentation (linked above) mentions version 5.3.0 – and the code above was modified after I last tested it, but should work anyway.

In this post, I’ll describe how to create your own static SPIP tags. In a future post, I’ll cover dynamic tags, and how to package your tags (and other code) as a plug-in. Before reading this post, you should be familiar with SPIP and it’s template language, and with programming in PHP.

SPIP tags are used to “output” a “value”. For many tags, this value is taken from the context in which it is called: the title of the “current” article, for example, or the logo the “current” news item. Others output global values like the name of the web-site, or the version of the software. Still more tags allow users to interact with the site (e.g. #LOGIN_PUBLIC which outputs a log-in form and processes the log-in request when the user submits it) and a few (like ’‘#SET’’ and ’‘#GET’’) implement the features of a general purpose programming language and producing output is only a side effect. All of these effects are achieved using the same relatively simple syntax and mechanism.

Tags can be divided into two groups based on their behaviour. Static tags are those that output some statically determined value – one that does not necessarily change from one evaluation to another. The title of an article, for example, will not necessarily change between one page view and another. It may, but not necessarily. Dynamic tags are those that generate dynamic output – values that necessarily change between invocations. The current date and time, for example. Implementing a static tag is significantly easier than a dynamic tag, so we’ll look at that first and leave dynamic tags to a later post.

Static tags

Static tags are those that output a “static” value. That is, a value that is not expected to change over any particular time period. This means that SPIP can evaluate a static tag once and then cache the result and reuse it in future requests.

Like many aspects of SPIP, a tag (for the rest of this section, you can assume that “tag” means “static tag”) is a function¹ with a special name – the name of the tag appended to “balise_”. For example a tag called #FOO will be implemented by a function called balise_FOO. Like much of SPIP, these functions can be overridden by plug-ins, or site-specific files. When it sees a #FOO tag, SPIP will first look for a function called balise_FOO, then one called balise_FOO_dist, and then decide that the tag doesn’t exist.

Rather than blather on, I’ll give you a trivial example: the #HELLO_WORLD tag. This tag simply outputs the string “Hello World!” (To use the code, simply copy the function into the file mes_fonctions.php in the root of your SPIP installation):

<?php
function balise_HELLO_WORLD($p) {
    $p->code = "'Hello World!'";
    return $p;
}

As you can see there are a few more details than just the name, namely, this $p thing. The parameter to the function implementing the tag is a reference to the abstract syntax tree node for that tag. This contains all of the information about the tag that SPIP has about the tag, the filters called on it, the brackets around it, the context, etc., etc., etc. All that is missing is the value itself, which is where our function comes into play. After SPIP has analysed the templates and handled everything it can, it calls the function responsible for each tag to fill in the gaps.

There a numerous fields in the Champ object (the class is defined in ecrire/public/interfaces.php but the definition isn’t particularly edifying), but most of them are best left alone and accessed by way of helper functions:

• type – a string describing the type of AST node. Should be "champ" for tags.

• nom_champ – the name of the tag without the #.

• nom_boucle – the name of the loop. Tags aren’t loops, so this will be empty.

• avant – a list of preceding nodes that are conditional on this one.

• apres – a list of succeeding nodes that are conditional on this one.

• etoile – “star”. The tag was called like #HELLO_WORLD* and, thus, should output raw, as opposed to HTML safe, values.

• param – a list of parameters and filters to the tag call. This is pretty complex.

• fonctions – similar to param but structured differently.

• id_boucle – the name of the loop within which this tag occurs.

• boucles – an array of AST nodes for the loops (“boulces”) in the template.

• type_requete – no idea.

• code – the PHP code which, when eval()d, produces the value of the tag.

• interdire_scripts – whether “scripts” will be interpreted. No idea.

• ramasser_miettes – whether to “collect the crumbs”. No idea.

• descr – an array of values describing the AST node, the file it came from, etc.

• ligne – the line number of the tag call in the template.

An example Replacing the contents of your dist/sommaire.html template with this:

[before (#HELLO_WORLD{arg1}|strtoupper) after]

might result in the following AST being passed to balise_HELLO_WORLD above (download the full SPIP AST):

type => "champ"
nom_champ => "HELLO_WORLD"
avant => the node/s for "before", ...
apres => the node/s for "after", ...
etoile => 
param => [
        0 => "arg1" is in here, ...
        1 => "strtoupper" is in here, ...
        ]
fonctions => [
        0 => "{arg1}" is also in here, ...
        1 => "strtoupper" is also in here, ...
        ]

Thankfully, you can ignore almost all of this and trust to the helpers. The function interprete_argument_balise (FR) is particularly useful: interprete_argument_balise(1, $p) returns the first argument in the AST node $p.

Using what I’ve described so far, it’s pretty to write a #HELLO tag which output’s a message “Hello name” when given a name, and “Hello World!” otherwise (again, this code goes in mes_fonctions.php):

<?php
function balise_HELLO($p) {
    $name = interprete_argument_balise(1, $p);
    if (! $name) {
        $name = "World!";
    }
    $p->code = "'Hello $name'";
    return $p;
}

There are a number of other issues involved in writing static templates. It’s good practice to make sure that your tags (and everything else, for that matter) supports translation, especially if you’re going to be distributing it to others. Doing so is reasonably easy using the _T (FR) function and “lang” files. Getting data from a loop (article titles, section IDs, etc.) is also reasonably straightforward with champ_sql (FR).

For more examples, you can have a look at the code for some of SPIP’s built-in tags in the code of ecrire/public/balises.php (FR) (I rather like balise_INTRODUTION_dist (FR)). If you do look to the SPIP source code for examples, you should be aware that a lot of the built-in tags are not implemented using this mechanism, but are magically drawn from database columns with the same name. If you extend the database this magic will work for you too, but that is beyond the scope of this post and will have to wait for my post/s about writing SPIP plug-ins.