[cvs] [Wiki] created: Doc/Dev/RegistryUsageH4

[Michael Slusarz]

slusarz  Tue, 02 Feb 2010 19:32:31 -0500

Created page: http://wiki.horde.org/Doc/Dev/RegistryUsageH4

+ 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  
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  
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]  
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/GlobalsH4|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

getVersion()
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 at 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