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

Tue Feb 2 19:33:50 UTC 2010

slusarz  Tue, 02 Feb 2010 14:33:50 -0500

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

[[toc]]

+ Horde Framework Module

The //Horde Framework// modules, also known as //Horde Libraries//,  
are an integral part of the //Horde Application Framework//. These  
modules are managed [http://git.horde.org/framework/?rt=horde-git  
separately] in our [http://www.horde.org/source/ Git repository] but  
are included with the [http://www.horde.org/horde/download/ Horde  
packages] that can be downloaded from our  
[http://www.horde.org/mirrors.php servers]. The modules are general  
purpose libraries that are being used by several Horde applications or  
the framework itself, but can also be utilized outside the Framework  
in custom PHP solutions. They are developed, packaged, and distributed  
similarly to the [http://pear.php.net/ PEAR packages].

++ Installation

Most of these methods require that you first tell your PEAR  
installation about the Horde PEAR channel:

<code>pear channel-discover pear.horde.org
</code>

+++ Installing everything from Git

You will need the entire Horde Framework module. You can either get a  
Git checkout of the {{framework}} module from Horde's Git server (see  
http://horde.org/source/ for instructions on using Git), or you can  
download a nightly snapshot from http://snaps.horde.org/. You'll want  
the latest framework-HEAD snapshot.

[[# InstallInstruct]] Once you have the full framework you have two  
options: symlinking, or installing with the PEAR installer. If you  
want to install with the PEAR installer, there is a  
{{pear_batch_install}} script (or, if using Windows, a  
{{pear_batch_install.bat}} script) in the framework/bin directory that  
will automate the process for you. Simply run:

<code>php bin/pear_batch_install
</code>

from the base of the framework directory. The major disadvantage of  
this method is that if you are using Git, you will need to re-run the  
script every time you update. If you are doing Horde development or  
update from Git frequently, then using symlinks is recommended.

Symlinked directories can be generated using the {{install_framework}}  
script in the framework/bin directory.  Usage is as follows:

<code>$ horde-fw-symlinks.php --help
Usage: install_framework [OPTION]

Possible options:
   --copy        Do not create symbolic links, but actually copy the libraries
                 (this is done automatically on Windows).
   --src DIR     The source directory for the framework libraries.
   --dest DIR    The destination directory for the framework libraries.
   --pkg DIR     Path to a single package to install.
</code>

The default is to run the script from your main Horde directory, with  
{{framework/}} as the source directory and a {{libs}} directory as the  
target (these values are assumed if you don't specify --src or  
--dest). You will see a processing message for each package, and then  
all you need to do is to add the {{libs/}} directory to your  
include_path.

Symlinking is useful for developers who develop on the framework  
libraries and want to see their changes in real-time without having to  
re-install the affected package. This script is also used to  
distribute the libraries with the Horde packages.

+++ Installing individual libraries from Git

You will still need a full checkout or a snapshot of the framework, as  
above. Then you can install individual packages. For example, to  
install the Horde_Compress package, in the {{framework/Compress}}  
directory, you would run:

<code>pear install Compress/package.xml
</code>

+++ Installing from http://pear.horde.org/

Installing from pear.horde.org is simple. Once you have "discovered"  
the channel as described above, you can install Horde packages just  
like other PEAR packages. For example to install the Compress package:

<code>pear install horde/Horde_Compress-alpha
</code>

(the -alpha is necessary if you have not configured PEAR to install  
alpha state packages by default. This will vary depending on the Horde  
package that you pick; some are stable, some are beta, and some are  
alpha.)

To view the available packages, their states (alpha, beta, stable),  
dependencies, and other information about them, visit  
http://pear.horde.org/index.php?category=framework.

+++ If you already have a Horde release

Horde releases come with all of the framework libraries bundled in the  
{{horde/lib/}} directory, and also include the necessary code to make  
everything in the {{horde/lib/}} directory available to Horde without  
any further installation or PHP configuration:

<code type="php">
ini_set('include_path', dirname(__FILE__) . PATH_SEPARATOR .  
ini_get('include_path'));
</code>

This code prepends the {{horde/lib/}} directory to the existing  
{{include_path}}. For example, if the {{include_path}} is set to  
{{.:/usr/share/php}} in {{php.ini}}, it will become  
{{/path/to/horde/lib:.:/usr/share/php}}. This means that library files  
included with {{include}}, {{include_once}}, {{require}}, or  
{{require_once}} statements are first looked for in Horde's {{lib/}}  
directory, then in the local directory ({{.}}), and finally in the  
PEAR repository. The side effect is that libraries that come with  
Horde and have the same name like a PEAR package, e.g. File_CSV, are  
used in favor of the PEAR package.

++ Use

If PHP has been set up properly, the local PEAR repository should be  
in PHP's {{[http://www.php.net/manual/en/ini.core.php#ini.include-path  
include_path]}}. If installing the Horde Libraries either separately  
with the PEAR installer or using {{install-packages.php}}, they are  
available alongside PEAR's packages, and can be included in your  
custom code the same way:

<code type="php">
// Include PEAR's DB package.
require_once 'DB.php';
// Include PEAR's Text_Wiki package.
require_once 'Text/Wiki.php';
// Include Horde's Horde_Tree package.
require_once 'Horde/Tree.php';
// Include Horde's Horde_Text_Flowed package.
require_once 'Horde/Text/Flowed.php';
</code>

If using the Horde environment, these require_once statements are not  
needed as the libraries will be autoloaded the first time they are used.

++ Development

+++ Git organization

All libraries are managed in  
[http://git.horde.org/framework/?rt=horde-git Git]. Each library has  
its own subdirectory inside the framework directory.  The library  
package names are ALWAYS {{Horde_<Name>}}, and the directory names are  
{{<Name>}}.

Each package directory contains a  
[http://pear.php.net/manual/en/developers.packagedef.php package.xml]  
file with package descriptions, file listings, dependencies, change  
logs etc. As all Horde Libraries are following the  
[http://pear.php.net PEAR] standard, they can be installed using the  
[http://pear.php.net/manual/en/installation.cli.php PEAR installer] or  
may be symlinked to a subdirectory of the Horde installation.  For  
further instructions, see the Installation Instructions located above.

+++ Directory structure

<code>
framework/Name/
     package.xml
     lib/
         Horde/
             Name.php
             Name/
                 foo.php
                 bar.php
...
</code>

After installation:
<code>
lib/
     Horde/
         Name.php
         Name/
             foo.php
             bar.php
...
</code>

A rule of thumb is that each underscore in a package name is  
translated to an additional directory after installation.