6.0.0-git
2024-03-19
Last Modified 2017-10-03 by Jan Schneider

Horde_Registry

Horde_Registry is responsible for setting up the Horde environment and coordinating interaction between Horde, its libraries, and Horde applications. It must be initialized at the very beginning of any script that will be using the Horde framework.

The typical use pattern for a script will be as follows.

The first line of the script should be a require_once statement that points to the application's lib/Application.php file. (All applications REQUIRE the lib/Application.php file. See the skeleton module for a stub lib/Application.php that demonstrates what is required in that file). Requiring lib/Application.php will set up the base PHP environment and setup the proper autoloader paths for Horde libraries.

Since your script lives in a known location in the application layout, and autoloading is not yet setup at this point, the filepath needed to load lib/Application.php will be its full pathname. For example, in an application foo, for the script bar.php, the following is needed:

require_once dirname(__FILE__) . '/lib/Application.php';

At this point, autoloading is available, but the Registry has not yet been initialized. This is because we may want to configure various aspects of the Registry prior to loading. To facilitate this configuration, the static function Horde_Registry::appInit() is provided. This function has two parameters: the application being initialized (REQUIRED) and an array of configuration options (OPTIONAL). By default, appInit() will assume the script is being run from the web, that the user must be authenticated and have the necessary permissions to access the application, that output compression should be turned on, and that the session should be opened read-write. For example, to initialize the application 'foo' with the default arguments, the following is needed:

$appOb = Horde_Registry::appInit('foo');

On authentication success, $appOb will be set to the Horde_Registry_Application instance for the current application. On authentication failure the default action is to redirect the user to the login page.

Horde_Registry::appInit() has several configuration options that can be used to tweak environment initialization and authentication error handling. A full list of these configuration options can be found here.

Horde_Registry::appInit() should ONLY be called as the first lines in a script - it is simply a shortcut to bootstrap/initialize the Horde environment. It should NEVER be used otherwise (e.g. within a library) to initialize an application.

Once the Registry has been initialized, all Horde global variables/constants are available.

In conclusion, the following is the minimum needed to initialize the Horde environment at the beginning of the script:

require_once dirname(__FILE__) . '/lib/Application.php';
$appOb = Horde_Registry::appInit('foo');

Horde_Registry_Application

TODO

init()

Linking to another application

Here is example code on the code needed to create a link to another application:

// Check to see if the functionality we want is there
if (!$registry->hasMethod('mail/compose')) {
    exit('No mail/compose method defined');
}

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

Calling API methods

Calling an API method in another application can be done like this:

// Check to see if the functionality we want is there
if (!$registry->hasMethod('contacts/search')) {
    exit('No contacts/search method defined');
}

// 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')
);

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

// -or- "New" method
$results = $registry->contacts->search($args);

pushApp()/popApp()

TODO

getAuth()

This method returns the currently logged-in Horde user.

Application version

The version number of an application (in this example, application 'foo') can be obtained from Horde_Registry with the following code:

$version = $registry->getVersion('foo');