The Registry

Horde's Registry is the glue that holds different applications together

require_once HORDE_BASE . 'Horde/Registry.php';

// The Registry has a singleton method that should be used to ensure

// that there is only ever one instance of the Registry during a request.

$registry = &Registry::singleton();

// All applications should put themselves on the application stack when they start running

// This also takes care of reading the application's configuration file.

$registry->pushApp('curapp');

// When an app is finished, pop it off the application stack

// This also returns the global $conf variable to that of the previous application.

$registry->popApp();

// Routines can determine the current app:

$curapp = $registry->getApp();

// Find out if an application allows access for the current user (may be a guest user)

if ($registry->hasPermission('app')) {

    // access allowed

}

• The Registry system keeps track of Horde's application stack, and which app is currently running.
  • When you switch applications, the registry will take care of switching the gettext textdomain correctly.
  • It also lets you determine configuration information about installed applications.

The Registry lets you generate links to other apps

require_once HORDE_BASE . 'Horde/Registry.php';

$registry = &Registry::singleton();

// Check to see if the functionality we want is there

if (!$registry->hasMethod('mail/compose')) {

    echo 'no mail/compose method defined';

    exit;

}

// Generate the link

echo $registry->link('mail/compose', array('to' => 'foo@example.com', 'subject' => 'bar'));

• Links will be to the application that provides the functionality.
  • Any arguments that the target script needs (headers for an email, for instance) will be filled out of the second argument to link().

The Registry also lets you invoke methods in other applications

require_once HORDE_BASE . 'Horde/Registry.php';

$registry = &Registry::singleton();

// Check to see if the functionality we want is there

if (!$registry->hasMethod('contacts/search')) {

    echo 'no contacts/search method defined';

    exit;

}

// The contacts/search method takes two arrays; one of names, one of addressbooks

$args = array('sources' => array('myldap'),

                         'names' => array('Chuck'),

                          'fields' => array('name', 'email'));

$results = $registry->call('contacts/search', $args);

• The registry config file defines where to find the code necessary to execute the method, and what application implements it.
  • Any application can be integrated this way; all you need to do is map it to the registry interface.

registry.php

Here's an application's registry.php entry:

$this->applications['whups'] = array(

    'fileroot' => dirname(__FILE__) . '/../whups',

    'webroot' => $this->applications['horde']['webroot'] . '/whups',

    'name' => _("Tickets"),

    'status' => 'active',

    'provides' => 'tickets',

    'menu_parent' => 'devel',

);

fileroot

    'fileroot' => dirname(__FILE__) . '/../whups',

The fileroot setting tells Horde where the application - in this case Whups - lives on the filesystem. The FILE constant is the current file; dirname() strips off the filename and turns it into just a directory.

This means that the location is by default relative to registry.php - under the horde/ directory - which is almost always right. But it's configurable just in case.

webroot

    'webroot' => $this->applications['horde']['webroot'] . '/whups',

The webroot setting tells Horde where the application lives relative to the webserver's document root. Usually this is predictable as well, but you might want to give an application its own domain - for example, http://cvs.php.net/, which is powered by Horde and Chora.

name

    'name' => _("Tickets"),

The name setting surprisingly sets the human-readable name of the application. The _() is an alias for gettext(), which translates the name into other languages.

status

    'status' => 'active',

The status setting tells Horde what kind of application this is. Possible statuses are:

• inactive
  • hidden
  • notoolbar
  • heading
  • block
  • admin
  • active

provides

    'provides' => 'tickets',

The provides setting tells Horde if the application provides any APIs. In this case Whups provides the tickets API, which allows for adding and listing tickets. In turn, Horde knows that if it gets a request for a tickets/search method, it should pass it along to Whups.

menu_parent

    'menu_parent' => 'devel',

The menu_parent setting is just for the sidebar - it tells Horde what item to make the application of a child of. This lets you customize the menu to your heart's content. This can be left out or set to null for top-level items.