Hyperwave Functions

Hyperwave (http://www.hyperwave.com) is a document management system intended to store, handle, and retrieve very large sets of documents, maintaining information about them and hyperlinks between them.

To use Hyperwave functions in PHP, you simply supply the --with-hyperwave option to the configure script when building PHP; no other software is required (assuming that you have a Hyperwave server to which you can connect, of course).

A full discussion of the capabilities and usage of Hyperwave is beyond the scope of this book; to use these functions, you're expected to be familiar with Hyperwave and to have a copy of the documentation. However, the following information may prove useful, as it explains some of the terminology used in this section, especially as it relates to using Hyperwave under PHP.

Objects, for the purposes of this extension, should not be confused with PHP's object type. In Hyperwave, an object is any document, hyperlink, or collection stored in the system. Documents can comprise any kind of file-based data. Hyperlinks (more properly, anchors), which are removed from a document when the document is stored and replaced when it is retrieved, are also stored as objects and can therefore be updated without the necessity of altering the parent document. However, except when using hw_gettext() or hw_pipedocument() , you'll need to fetch both the document and its links and merge them before display.

Each object is described by its associated object record, which contains information about the object's attributes. The object record is a string of ATTRIBUTE_NAME=ATTRIBUTE_VALUE pairs, with one attribute per line. You can make up your own attribute names and values, and the names need not be unique. However, Hyperwave itself maintains a certain set of read-only attributes for each object. Typical attribute information includes the title, description, and so forth.

An object array is simply an associated array, possibly multidimensional, containing the information from one object record. The attribute names are the keys and the attribute values are the values. An object array is multidimensional only if there are multiple attributes with the same name. If the repeated attribute names have values using the colon specifier (for different languages), those attributes are placed into an associative subarray using the specifiers as key names. If no colon specifiers appear (for multiple keywords), the attribute values are placed into an indexed subarray.

Various functions accept a query string for searching through the contents of the database. The Hyperwave extension supports three different kinds of queries, each with its own syntax: key queries (used by the hw_getobjectbyquery*() functions), full-text queries (used by the hw_getobjectbyftquery*() functions), and object queries (used by hw_getobject() ). Full-text queries have different syntaxes, depending on whether the server is using the native database or Verity as the back-end database. Consult your Hyperwave documentation for query syntax explanations.

Some functions return extra statistical information about queries. This data is represented as an associative array with the following elements. All of these elements except Total represent the number of object records having a PresentationHints attribute set to the element name. Total represents the number of object records.