Intro
DBFunctions class is used to interface with the Document Storage Database. It utilizes the pear MDB2 package, which must be installed.
Before using any of these functions the following lines must be included in the script calling it :
require_once("MDB2.php");
require_once("DBFunctions.php");
$db = new DBFunctions();
all usage examples assume this has been done, and utilize the $db object handle.
Many of the functions return a mdb2 $result object. This object contains the results of the query. Iteration over the results can be accomplished like so :
$res = $db->SomeFunction();
while (($row = $res->fetchRow())) {
print "First Row is : " . $row[0] . "<br>\n";
print "Second Row is : " . $row[1] . "<br>\n";
print "And so on...";
}
Functions
listBib()
Description
Retrieves a list of all the Licenses available in the database, useful for generating dropdown selection boxes. The resulting array structure is :
Usage
$res = $db->listBib();
while (($row = $res->fetchRow())) {
$CopyrightID = $row[0];
$CopyrightName = $row[1];
}
listDocPub()
Description
Retrieves a list of all public Documents. This retrieves the document information, but not the documents themselves.
Usage
$res = $db->listDocPub();
while (($row = $res->fetchRow())) {
$DocID = $row[0];
$Title = $row[1];
$Author = $row[2];
$Publisher = $row[3];
$Location = $row[4];
$Medium = $row[5];
$Date = $row[6];
$Copyright = $row[7];
$FileID = $row[8];
}
listDocPers($UserID)
Description
Retrieves a list of all personal documents. This only retrives the document information and not the document itself. This function is for development use only since it doesn't retrieve personal documents belonging to the user logged in, it just dumps all the contents. This will probably be phased out or upgraded soon.
Usage
$res = $db->listDocPub($_SESSION['UserID']);
while (($row = $res->fetchRow())) {
$DocID = $row[0];
$OwnerID = $row[1];
$Title = $row[2];
$FileID = $row[3];
}
addDocPers($OwnerID, $Title, $Text)
Description
This adds a personal document to the database and returns the ID of the newly inserted Document.
$OwnerID (int) is the UserID of the documents owner
$Title (string) is the documents Title or Name, entered by the User
$Text (string) is the text of the document being uploaded.
This function doesn't work for non-text documents like PDF's.
The OwnerID should be retrieved from the UserID session variable.
Usage
$OwnerID = $_SESSION['UserID'];
$Title = "Some Sort of Title";
$Text = "blah de blah blah bloom";
$DocID = $db->addDocPers($OwnerID, $Title, $Text);
getKeywords()
Description
Retrieves a list of keywords in database which can be attached to a file. returns an array containing the keywords.
Usage
$keywords = $db->getKeywords();
foreach($keywords as $keyword){
print "$keyword<br>";
}
addKeyword($keyword)
Description
Function to add keyword to database, has no return value
Usage
$db->addKeyword("mykeyword");
uploadDoc($info, $TmpFile, $name, $type)
Description
Function to upload new document to the database and create document info entry. It is suggested to use the $_FILES array created when a file is uploaded.
Usage
$doc = array(
array('Title' => 'Some Book'),
array('Author' => 'Some Dude'),
array('Publisher' => 'Some Company'),
array('Location' => 'Some Place'),
array('Medium' => 'Book'),
array('Date' => '2004-11-22'),
array('CopyrightID' => '2'));
$db = uplodDoc($doc, $_FILES['tmp_name'], $_FILES['name'], $_FILES['type']);
AddDocInfo($a)
Description
Adds a documents information but no file to the database. This is for note-taking on texts which are not stored in the database.
The Date must be submitted in a YYYY-MM-DD format.
Usage
$book = array(
array('Title' => 'Some Book'),
array('Author' => 'Some Dude'),
array('Publisher' => 'Some Company'),
array('Location' => 'Some Place'),
array('Medium' => 'Book'),
array('Date' => '2004-11-22'),
array('CopyrightID' => '2'));
$db = addDocInfo($book);
getDocRefs()
Description
Retrieves all public documents whose text is not stored in the database. These are documents which have excerpts and notes manually entered into the database by a user.
Usage
$res = $db->getDocRefs();
while (($row = $res->fetchRow())) {
$DocID = $row[0];
$OwnerID = $row[1];
$Title = $row[2];
}
storeText($data, $name)
Description
Stores text documents into Document Storage and returns the DocumentID of the inserted document. This function isn't meant for direct usage, it's mainly used by other document storage functions.
$data (string) the text of the document
$name (string) the title of the document
Usage
$name = "A Title";
$data = "Document Text";
$DocStorageID = $db->storeText($data, $name);
storeDoc($TmpFile, $name, $type)
Description
Stores non-text Documents in document storage and returns the DocumentID of the Inserted Document. Like storeText, this function is meant for use by other functions.
$TmpFile (filehandle) Filehandle for the uploaded document
$name (string) The document Title
$type (string) the document type (PDF, JPG, etc..)
Usage
$TmpFile = $_POST['File'];
$name = "Document Title";
$type = "PDF";
$DocStorageID = $db->storeDoc($TmpFile, $name, $type);
saveDoc($DocID, $ChangedText)
Description
This changes a personal document already stored in the database. Currently it just obliterates the old document but as soon as I build/find a diff utility for PHP this function will also store the differences between the old and new file in the DocArchive table.
$DocID (int) ID of the document to save over
$ChangedText (string) The updated text to save
Usage
//clipped from the addDocPers usage example
$OwnerID = $_SESSION['UserID'];
$Title = "Some Sort of Title";
$Text = "blah de blah blah bloom";
$DocID = $db->addDocPers($OwnerID, $Title, $Text);
$UpdatedText = "blah de blah bloom blah";
$db->saveDoc($DocID, $UpdatedText);
titleSearch($DocType, $SearchType, $SearchTerm)
Description
Searches public or private documents for a title matching the search term. Search Types are Contains, Starts with, Ends With, and Exactly. returns the document result array.
$DocType (Pers|Pub) Type of document, only valid options are Pers and Pub
$SearchType (Starts|Ends|Exact|Contains) What type of search you want to do.
$SearchTerm (string) the search string.
Usage
//Search for a public Document whose title contains "China"
$res = $db->titleSearch("Pub", "Contains", "China");
//Search for a private Document whose title starts with "Home"
$res = $db->titleSearch("Pers", "Starts", "Home");
//Search for a public Document whose title is exactly "The Illiad"
$res = $db->TitleSearch("Pub", "Exactly", "The Illiad");
//Search for a private document whose title ends with "work"
$res = $db->TitleSearch("Pers", "Ends", "work");
authUser($User, $Pass)
Description
this authenticates a username and password against the MySQL database. It encrypts the plaintext password passed to and compares it to the md5 hash stored in the database.
$User (string) The username to authenticate
$Pass (string) The password to authenticate
Usage
Usage :
if($db->authUser($_POST['User'], $_POST['Pass'])){
print("User Authenticated");
} else {
print("Bad username or password given");
}
addUser($User, $Email, $Pass)
Description
this adds a user to the database, storing the username, email address, and password given. This also encrypts the password with an md5 hash.
$User (string) the username to add
$Pass (string) the password to use for the user
$Email (string) the email address of the user
Usage
$db->addUser($_POST['User'], $_POST['Email'], $_POST['Pass']);
changePass($User, $OldPass, $NewPass)
Description
This changes a users password. This first authenticates the old password using authUser(), and then changes the password.
$User (string) the user whose password needs to be changed
$OldPass (string) the old password
$NewPass (string) the new password
Usage
$db->changePass($_POST['User'], $_POST['OldPass'], $_POST['NewPass']);
