6.0.0-git
2024-03-19
Last Modified 2013-09-04 by Jan Schneider

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 separately in our CVS repository but are included with the Horde packages that can be downloaded from our FTP 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 PEAR packages.

Installation

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

pear channel-discover pear.horde.org

Installing everything from CVS

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

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 an install-packages.php script (or, if using Windows, an install-packages.bat script) in the framework/ directory that will automate the process for you. Simply run:

php install-packages.php

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

To create a symlinked framework installation automatically, you will first need to install the Horde devtools package:

pear install devtools/package.xml

If this succeeds you will now have some development tools in your PATH, including horde-fw-symlinks.php. This script accepts a framework directory and a target directory as options:

$ horde-fw-symlinks.php --help
Usage: horde-fw-symlinks.php [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.

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 CVS

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:

pear install Compress/package.xml

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:

pear install horde/Horde_Compress-alpha

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

ini_set('include_path', dirname(__FILE__) . PATH_SEPARATOR . ini_get('include_path'));

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

// Include PEAR's DB package.
require_once 'DB.php';
// Include PEAR's Text_Wiki package.
require_once 'Text/Wiki.php';
// Include Horde's VFS package.
require_once 'VFS.php';
// Include Horde's Horde_Tree package.
require_once 'Horde/Tree.php';
// Include Horde's Text_Flowed package.
require_once 'Text/Flowed.php';

Development

CVS organization

All libraries are managed in the framework CVS module. Each library has its own subdirectory inside the framework module. The directory names are unfortunately a bit inconsistent and match not always the library name exactly. The Util/ directory for example contains the Horde_Util package.

The following quote from the PEAR manual explains the package name format:
One of the most important tasks while contributing a new package to PEAR is finding an appropriate name for your package.The general syntax for package names is <Category>_<Name>. The value for <Category> should be chosen from a predefined list of categories that are available in PEAR (e.g. "HTTP", "Net", "HTML"). The second part is the name of the package (like "Upload", "Portscan", "Table").

Each package directory contains a package.xml file with package descriptions, file listings, dependencies, change logs etc. As all Horde Libraries are following the PEAR standard, they can be installed using the PEAR installer or may be symlinked to a subdirectory of the Horde installation. For further instructions, see the Installation Instructions located above.

Directory structure

The VFS package has the following structure in CVS:

framework/VFS/
    package.xml
    VFS.php
    VFS/
        file.php
        ftp.php
...

and is installed like so in the PEAR repository or the lib/ directory, which is exactly the same:

lib/
    VFS.php
    VFS/
        file.php
        ftp.php
...

But this is different with the Horde_Tree package. In CVS:

framework/Tree/
    package.xml
    Tree.php
    Tree/
        javascript.php
        html.php
...

After installation:

lib/
    Horde/
        Tree.php
        Tree/
            javascript.php
            html.php
...

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