DBLIB.txt

   1 This is a description of the database interface for PhpWiki. Regardless
   2 of what kind of data store is used (RDBMS, DBM files, flat text files)
   3 you should be able to write a library that supports that data store.
   4
   5 A few notes:
   6
   7 * While most functions specify a "db reference" as the first value
   8   passed in, this can be any kind of data type that your functions
   9   know about. For example, in the DBM implementation this is an
  10   integer that refers to an open database handle, but in the MySQL
  11   version it's an associative array that contains the DB information.
  12
  13 * Functions that return the page data must return a hash (associative
  14   array) of all the data, where 'content' == the text of the page in Wiki
  15   markup, 'version' is an integer representing the version, 'author'
  16   the IP address or host name of the previous author and so on. See
  17   the next paragraph for a precise description.
  18
  19 * The data structure. This is commonly named $pagehash in the source
  20   code; it's an associative array with values that are integers,
  21   strings and arrays (i.e. a heterogenous data structure). Here's a
  22   current description:
  23
  24   $pagehash = {
  25      author       => string,
  26      content      => array (where each element is a line of the page),
  27      created      => integer (a number in Unix time since the Epoch),
  28      flags        => integer,
  29      lastmodified => integer (also Unix time),
  30      pagename     => string,
  31      version      => integer,
  32      refs         => array (where each element is a reference)
  33   };
  34
  35 The functions are:
  36
  37       OpenDataBase($dbname)
  38       takes:   a string, the name of the database
  39       returns: a reference to the database (a handle)
  40
  41
  42       CloseDataBase($dbi)
  43       takes:   a reference to the database (handle)
  44       returns: the value of the close. For databases with persistent
  45                connections, this doesn't return anything.
  46
  47
  48       RetrievePage($dbi, $pagename)
  49       takes:   db reference, string which is the name of a page
  50       returns: a PHP associative array containing the page data
  51                (text, version, author, etc)
  52
  53
  54       InsertPage($dbi, $pagename, $pagehash)
  55       takes:   db reference, page name (string), associative array
  56                of all page data
  57       returns: nothing (hmm. It should probably return true/false)
  58
  59
  60       IsWikiPage($dbi, $pagename)
  61       takes:   db reference, string containing page name
  62       returns: true or false, if the page already exists
  63
  64
  65       InitTitleSearch($dbi, $search)
  66       takes:   db reference, search string
  67       returns: a handle to identify the query and the current position
  68                within the result set.
  69
  70
  71       TitleSearchNextMatch($dbi, &$pos)
  72       takes:   db reference, reference to a hash created by
  73                InitTitleSearch
  74       returns: the next page name that contains a match to the search term
  75                (advances $pos to next result field as well)
  76
  77
  78       InitFullSearch($dbi, $search)
  79       takes:   db reference, string containing search term
  80       returns: similar to InitTitleSearch: a handle to identify the
  81                query and the current position within the result set.
  82
  83
  84       FullSearchNextMatch($dbi, &$pos)
  85       takes:   db reference, reference to a hash created by
  86                InitFullSearch
  87       returns: an associative array, where:
  88                   'name' -- contains the page name
  89                   'hash' -- contains the hash of the page data
  90                (advances $pos to next result field as well)
  91
  92
  93       IncreaseHitCount($dbi, $pagename)
  94       takes: db reference, string (name of a page)
  95       returns: nothing (MySQL implementation returns the last result
  96                set but it is not used by the caller)
  97
  98
  99       GetHitCount($dbi, $pagename)
 100       takes: db reference, string (page name)
 101       returns: an integer, the number of hits the page has received
 102
 103
 104       InitMostPopular($dbi, $limit)
 105       takes: a db reference and an integer, which is the limit of the
 106              number of pages you want returned.
 107       returns: the result set from the query
 108
 109
 110       MostPopularNextMatch($dbi, $res)
 111       takes: db reference, the result set returned by InitMostPopular
 112       returns: the next row from the result set, as a PHP array type
 113
 114       GetAllWikiPageNames($dbi)
 115       GetWikiPageLinks($dbi, $pagename)
 116       SetWikiPageLinks($dbi, $pagename, $linklist)
 117
 118 $Id: DBLIB.txt,v 1.7 2000-10-21 04:14:02 wainstead Exp $
 119