[cvs] [Wiki] changed: Doc/Dev/Framework

[Chuck Hagenbuch]

chuck  Mon, 29 Jan 2007 15:35:16 -0800

Modified page: http://wiki.horde.org/Doc/Dev/Framework
New Revision:  1.4
Change log:  Start to reorganize this page to emphasize installation and use, while keeping important developer informatio. Is still a work in progress.

@@ -1,14 +1,50 @@
  [[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://cvs.horde.org/framework/ separately] in our [http://www.horde.org/source/ CVS 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 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.
+The //Horde Framework// modules, also known as //Horde Libraries//, are an integral part of the //Horde Application Framework//. These modules are managed [http://cvs.horde.org/framework/ separately] in our [http://www.horde.org/source/ CVS 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 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 [http://pear.php.net/ PEAR packages].
  
-The different modules are developed, packaged, and distributed similarly to the [http://pear.php.net/ PEAR packages]. They will even be downloadable and installable with the PEAR installer in the future, using a PEAR channel server.
+++ Installation
  
++++ Installing everything from CVS
  
-++ CVS management
++++ Installing individual libraries from CVS
+
++++ Installing from http://pear.horde.org/
+
++++ 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 favour 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 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';
+</code>
+
+
+++ Development
+
++++ CVS organization
  
  All libraries are managed in the {{framework}} [http://cvs.horde.org/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 [http://pear.php.net/manual/ PEAR manual] explains the package name format:
@@ -23,14 +59,11 @@
  </code>
  
  The {{framework}} CVS module contains two scripts, {{[http://cvs.horde.org/co.php/framework/install-packages.php install-packages.php]}} and {{[http://cvs.horde.org/co.php/framework/install-packages.bat install-packages.bat]}} (for Windows), that can be used to install all packages at once in your local PEAR repository. This is necessary if you install the Horde Application Framework from CVS. See the [http://www.horde.org/horde/docs/?f=INSTALL.html#installing-from-cvs-or-snaphots installation manual] for details.
  
-There is a different script in the {{horde}} CVS module, {{[http://cvs.horde.org/co.php/horde/scripts/create-symlinks.php scripts/create-symlinks.php]}}, that can be used to install the libraries without using the PEAR installer. This 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. And that leads us to ...
+There is a different script in the {{horde}} CVS module, {{[http://cvs.horde.org/co.php/horde/scripts/create-symlinks.php scripts/create-symlinks.php]}}, that can be used to install the libraries without using the PEAR installer. This 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.
  
-
-++ Distribution management
-
-To save administrators from installing all necessary libraries, the libraries come pre-installed with each officially released Horde package that is downloaded from our FTP server. They are installed inside Horde's {{lib/}} directory (which is almost empty if you download Horde from CVS), using the same filesystem structure like a PEAR repository. How this is working is best explained with a few examples:
++++ Directory structure
  
  The {{VFS}} package has the following structure in CVS:
  <code>
  framework/VFS/
@@ -73,31 +106,5 @@
              html.php
  ...
  </code>
  
-A rule of thumb is, that each underscore in a package name is translated to an additional directory after installation.
-
-
-++ Using the libraries
-
-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 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';
-</code>
-
-Some magic is applied to Horde when creating distribution packages. This is necessary because the libraries distributed with a Horde release are not installed inside the PEAR repository, but the administrators still shouldn't need to change their PHP's {{include_path}}. This magic happens in {{[http://cvs.horde.org/co.php/horde/lib/core.php horde/lib/core.php]}} and looks like this:
-
-<code type="php">
-ini_set('include_path', dirname(__FILE__) . PATH_SEPARATOR . ini_get('include_path'));
-</code>
-
-What this code does, is to prepend the existing {{include_path}} with the {{horde/lib/}} directory. If for example 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 without specifying a full path, are first searched 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 favour of the PEAR package.
+A rule of thumb is that each underscore in a package name is translated to an additional directory after installation.