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 a hash of
  10   integers that refer to open database files, 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       MakeDBHash($pagename, $pagehash)
  49       takes: page name, page array
  50       returns: an encoded version of the $pagehash suitable for
  51       insertion into the data store. This is an internal helper
  52       function used mainly for the RDBMSs.
  53
  54       MakePageHash($dbhash)
  55       takes: an array that came from the database
  56       returns: the $pagehash data structure used by the
  57       application. This function undoes what MakeDBHash does.
  58
  59       RetrievePage($dbi, $pagename, $pagestore)
  60       takes:   db reference, string which is the name of a page, and a
  61       string indicating which store to fetch the page from (live or archive).
  62       returns: a PHP associative array containing the page data
  63                (text, version, author, etc)
  64
  65
  66       InsertPage($dbi, $pagename, $pagehash)
  67       takes:   db reference, page name (string), associative array
  68                of all page data
  69       returns: nothing (hmm. It should probably return true/false)
  70
  71       SaveCopyToArchive($dbi, $pagename, $pagehash)
  72       Similar to InsertPage but for handling the archive store. The
  73       goal here was to separate the two (live db and archive db) in
  74       case there were different storage formats (for example, the
  75       archive might only store diffs of the pages). However this is
  76       not the case in the implementations.
  77
  78       IsWikiPage($dbi, $pagename)
  79       takes:   db reference, string containing page name
  80       returns: true or false, if the page already exists in the live db.
  81
  82       IsInArchive($dbi, $pagename)
  83       takes:   db reference, string containing page name
  84       returns: true or false, if the page already exists in the archive.
  85
  86       InitTitleSearch($dbi, $search)
  87       takes:   db reference, search string
  88       returns: a handle to identify the query and the current position
  89                within the result set.
  90
  91       RemovePage($dbi, $pagename)
  92       takes: db reference, name of the page
  93       returns: nothing
  94       This deletes a page from both the live and archive page stores.
  95
  96       TitleSearchNextMatch($dbi, &$pos)
  97       takes:   db reference, reference to a hash created by
  98                InitTitleSearch
  99       returns: the next page name that contains a match to the search term
 100                (advances $pos to next result field as well)
 101
 102       MakeSQLSearchClause($search, $column)
 103       takes: a search string, column name
 104       returns: a SQL query string suitable for a database query
 105
 106       InitFullSearch($dbi, $search)
 107       takes:   db reference, string containing search term
 108       returns: similar to InitTitleSearch: a handle to identify the
 109                query and the current position within the result set.
 110
 111
 112       FullSearchNextMatch($dbi, &$pos)
 113       takes:   db reference, reference to a hash created by
 114                InitFullSearch
 115       returns: an associative array, where:
 116                   'name' -- contains the page name
 117                   'hash' -- contains the hash of the page data
 118                (advances $pos to next result field as well)
 119
 120
 121       IncreaseHitCount($dbi, $pagename)
 122       takes: db reference, string (name of a page)
 123       returns: nothing (MySQL implementation returns the last result
 124                set but it is not used by the caller)
 125
 126
 127       GetHitCount($dbi, $pagename)
 128       takes: db reference, string (page name)
 129       returns: an integer, the number of hits the page has received
 130
 131
 132       InitMostPopular($dbi, $limit)
 133       takes: a db reference and an integer, which is the limit of the
 134              number of pages you want returned.
 135       returns: the result set from the query
 136
 137
 138       MostPopularNextMatch($dbi, $res)
 139       takes: db reference, the result set returned by InitMostPopular
 140       returns: the next row from the result set, as a PHP array type
 141
 142       GetAllWikiPageNames($dbi)
 143       takes: db reference
 144       returns: an array containing all page names
 145
 146       GetWikiPageLinks($dbi, $pagename)
 147       takes: db reference, page name
 148       returns: a two-dimensional array containing outbound links
 149       ordered by score desc ('out'); inbound links ordered by score
 150       desc ('in'); inbound or outbound links ordered by most number of
 151       page views ('popular').
 152
 153       SetWikiPageLinks($dbi, $pagename, $linklist)
 154       takes: db reference, page name, list of pages linking to this
 155       one
 156       This deletes the existing list of linking pages and inserts all
 157       the page names in $linklist.
 158
 159 $Id: DBLIB.txt,v 1.8 2000-12-12 21:53:20 wainstead Exp $
 160