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.
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.
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.
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
26 content => array (where each element is a line of the page),
27 created => integer (a number in Unix time since the Epoch),
29 lastmodified => integer (also Unix time),
32 refs => array (where each element is a reference)
38 takes: a string, the name of the database
39 returns: a reference to the database (a handle)
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.
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.
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.
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)
66 InsertPage($dbi, $pagename, $pagehash)
67 takes: db reference, page name (string), associative array
69 returns: nothing (hmm. It should probably return true/false)
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.
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.
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.
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.
91 RemovePage($dbi, $pagename)
92 takes: db reference, name of the page
94 This deletes a page from both the live and archive page stores.
96 TitleSearchNextMatch($dbi, &$pos)
97 takes: db reference, reference to a hash created by
99 returns: the next page name that contains a match to the search term
100 (advances $pos to next result field as well)
102 MakeSQLSearchClause($search, $column)
103 takes: a search string, column name
104 returns: a SQL query string suitable for a database query
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.
112 FullSearchNextMatch($dbi, &$pos)
113 takes: db reference, reference to a hash created by
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)
121 MakeBackLinkSearchRegexp($pagename)
123 returns: A PCRE suitable for searching for a link to the given page
124 within page (wiki-markup) text.
126 InitBackLinkSearch($dbi, $pagename)
127 takes: db reference, page name
128 returns: a handle to identify the query and the current position
129 within the result set.
131 BackLinkSearchNextMatch($dbi, &$pos)
132 takes: db reference, reference to a hash created by
134 returns: the next page name that contains a link to the specified page.
135 (advances $pos to next result field as well)
138 IncreaseHitCount($dbi, $pagename)
139 takes: db reference, string (name of a page)
140 returns: nothing (MySQL implementation returns the last result
141 set but it is not used by the caller)
144 GetHitCount($dbi, $pagename)
145 takes: db reference, string (page name)
146 returns: an integer, the number of hits the page has received
149 InitMostPopular($dbi, $limit)
150 takes: a db reference and an integer, which is the limit of the
151 number of pages you want returned.
152 returns: the result set from the query
155 MostPopularNextMatch($dbi, $res)
156 takes: db reference, the result set returned by InitMostPopular
157 returns: the next row from the result set, as a PHP array type
159 GetAllWikiPageNames($dbi)
161 returns: an array containing all page names
163 GetWikiPageLinks($dbi, $pagename)
164 takes: db reference, page name
165 returns: a two-dimensional array containing outbound links
166 ordered by score desc ('out'); inbound links ordered by score
167 desc ('in'); inbound or outbound links ordered by most number of
168 page views ('popular').
170 SetWikiPageLinks($dbi, $pagename, $linklist)
171 takes: db reference, page name, list of pages linking to this
173 This deletes the existing list of linking pages and inserts all
174 the page names in $linklist.
176 $Id: DBLIB.txt,v 1.8.2.1 2001-08-18 00:35:10 dairiki Exp $