6.0.0-git
2019-11-11

Diff for Doc/Dev/RegistryUsage between 5 and 6

+ 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 [http://git.horde.org/co.php/skeleton/lib/Application.php?rt=horde-git[https://github.com/horde/skeleton/blob/master/lib/Application.php 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:

<code type="php">
require_once dirname(__FILE__) . '/lib/Application.php';
</code>

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 [http://dev.horde.org/api/framework/Core/Core/Horde_Registry.html#appInit[https://dev.horde.org/api/master/lib/Core/class-Horde_Registry.html#_appInit 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:

<code type="php">
$appOb = Horde_Registry::appInit('foo');
</code>

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 [http://dev.horde.org/api/framework/Core/Core/Horde_Registry.html#appInit[https://dev.horde.org/api/master/lib/Core/class-Horde_Registry.html#_appInit 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 ((Doc/Dev/Globals|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:

<code type="php">
require_once dirname(__FILE__) . '/lib/Application.php';
$appOb = Horde_Registry::appInit('foo');
</code>

++ Horde_Registry_Application

TODO

init()

++ Linking to another application

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

<code type="php">
// 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'));
</code>

++ Calling API methods

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

<code type="php">
// 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);
</code>

++ 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:

<code type="php">
$version = $registry->getVersion('foo');
</code>