X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=functions%2Fabook_database.php;h=9ca3ce1751d028443dc0e3a60974509b37222485;hb=15d98101f0c2b3cae541e1e8de0f5edfaa820965;hp=5fdd0d60ffe8bc649fe55f37f8c7c36a12f8edb8;hpb=11f2b6ba3ef9009deb73816743b6f439cd7c3b36;p=squirrelmail.git diff --git a/functions/abook_database.php b/functions/abook_database.php index 5fdd0d60..9ca3ce17 100644 --- a/functions/abook_database.php +++ b/functions/abook_database.php @@ -1,12 +1,31 @@ \n"; + $error .= sprintf(_("Is PEAR installed, and is the include path set correctly to find %s?"), + 'DB.php') . "
\n"; + $error .= _("Please contact your system administrator and report this error."); + error_box($error, $color); + exit; +} + +/** + * Address book in a database backend + * + * Backend for personal/shared address book stored in a database, * accessed using the DB-classes in PEAR. * * IMPORTANT: The PEAR modules must be in the include path @@ -14,59 +33,88 @@ * * An array with the following elements must be passed to * the class constructor (elements marked ? are optional): - * - * dsn => database DNS (see PEAR for syntax) - * table => table to store addresses in (must exist) - * owner => current user (owner of address data) - * ? writeable => set writeable flag (true/false) - * + * 
+ *   dsn       => database DNS (see PEAR for syntax)
+ *   table     => table to store addresses in (must exist)
+ *   owner     => current user (owner of address data)
+ * ? name      => name of address book
+ * ? writeable => set writeable flag (true/false)
+ * ? listing   => enable/disable listing
+ *
* The table used should have the following columns: * owner, nickname, firstname, lastname, email, label * The pair (owner,nickname) should be unique (primary key). * * NOTE. This class should not be used directly. Use the * "AddressBook" class instead. - * - * @version $Id$ * @package squirrelmail * @subpackage addressbook */ - -/** Needs the DB functions */ -require_once('DB.php'); - -/** - * Undocumented class - stores the addressbook in a sql database - * @package squirrelmail - */ class abook_database extends addressbook_backend { + /** + * Backend type + * @var string + */ var $btype = 'local'; + /** + * Backend name + * @var string + */ var $bname = 'database'; - + + /** + * Data Source Name (connection description) + * @var string + */ var $dsn = ''; + /** + * Table that stores addresses + * @var string + */ var $table = ''; + /** + * Owner name + * + * Limits list of database entries visible to end user + * @var string + */ var $owner = ''; + /** + * Database Handle + * @var resource + */ var $dbh = false; - + /** + * Enable/disable writing into address book + * @var bool + */ var $writeable = true; - + /** + * Enable/disable address book listing + * @var bool + */ + var $listing = true; + /* ========================== Private ======================= */ - - /* Constructor */ + + /** + * Constructor + * @param array $param address book backend options + */ function abook_database($param) { $this->sname = _("Personal address book"); - + if (is_array($param)) { - if (empty($param['dsn']) || - empty($param['table']) || + if (empty($param['dsn']) || + empty($param['table']) || empty($param['owner'])) { return $this->set_error('Invalid parameters'); } - + $this->dsn = $param['dsn']; $this->table = $param['table']; $this->owner = $param['owner']; - + if (!empty($param['name'])) { $this->sname = $param['name']; } @@ -85,42 +133,52 @@ class abook_database extends addressbook_backend { return $this->set_error('Invalid argument to constructor'); } } - - - /* Open the database. New connection if $new is true */ + + + /** + * Open the database. + * @param bool $new new connection if it is true + * @return bool + */ function open($new = false) { $this->error = ''; - + /* Return true is file is open and $new is unset */ if ($this->dbh && !$new) { return true; } - + /* Close old file, if any */ if ($this->dbh) { $this->close(); } - + $dbh = DB::connect($this->dsn, true); - + if (DB::isError($dbh)) { return $this->set_error(sprintf(_("Database error: %s"), DB::errorMessage($dbh))); } - + $this->dbh = $dbh; return true; } - /* Close the file and forget the filehandle */ + /** + * Close the file and forget the filehandle + */ function close() { $this->dbh->disconnect(); $this->dbh = false; } /* ========================== Public ======================== */ - - /* Search the file */ + + /** + * Search the database + * @param string $expr search expression + * @return array search results + */ function &search($expr) { $ret = array(); if(!$this->open()) { @@ -160,20 +218,24 @@ class abook_database extends addressbook_backend { } return $ret; } - - /* Lookup alias */ + + /** + * Lookup alias + * @param string $alias alias + * @return array search results + */ function &lookup($alias) { if (empty($alias)) { return array(); } - + $alias = strtolower($alias); if (!$this->open()) { return false; } - - $query = sprintf("SELECT * FROM %s WHERE owner='%s' AND nickname='%s'", + + $query = sprintf("SELECT * FROM %s WHERE owner='%s' AND LOWER(nickname)='%s'", $this->table, $this->owner, $this->dbh->quoteString($alias)); $res = $this->dbh->query($query); @@ -196,23 +258,26 @@ class abook_database extends addressbook_backend { return array(); } - /* List all addresses */ + /** + * List all addresses + * @return array search results + */ function &list_addr() { $ret = array(); if (!$this->open()) { return false; } - - if(isset($this->listing) && !$this->listing) { - return array(); - } + + if(isset($this->listing) && !$this->listing) { + return array(); + } $query = sprintf("SELECT * FROM %s WHERE owner='%s'", $this->table, $this->owner); $res = $this->dbh->query($query); - + if (DB::isError($res)) { return $this->set_error(sprintf(_("Database error: %s"), DB::errorMessage($res))); @@ -231,7 +296,11 @@ class abook_database extends addressbook_backend { return $ret; } - /* Add address */ + /** + * Add address + * @param array $userdata added data + * @return bool + */ function add($userdata) { if (!$this->writeable) { return $this->set_error(_("Addressbook is read-only")); @@ -240,7 +309,7 @@ class abook_database extends addressbook_backend { if (!$this->open()) { return false; } - + /* See if user exist already */ $ret = $this->lookup($userdata['nickname']); if (!empty($ret)) { @@ -254,9 +323,9 @@ class abook_database extends addressbook_backend { "'%s','%s','%s')", $this->table, $this->owner, $this->dbh->quoteString($userdata['nickname']), - $this->dbh->quoteString($userdata['firstname']), + $this->dbh->quoteString($userdata['firstname']), $this->dbh->quoteString($userdata['lastname']), - $this->dbh->quoteString($userdata['email']), + $this->dbh->quoteString($userdata['email']), $this->dbh->quoteString($userdata['label']) ); /* Do the insert */ @@ -270,7 +339,11 @@ class abook_database extends addressbook_backend { DB::errorMessage($r))); } - /* Delete address */ + /** + * Delete address + * @param string $alias alias that has to be deleted + * @return bool + */ function remove($alias) { if (!$this->writeable) { return $this->set_error(_("Addressbook is read-only")); @@ -279,7 +352,7 @@ class abook_database extends addressbook_backend { if (!$this->open()) { return false; } - + /* Create query */ $query = sprintf("DELETE FROM %s WHERE owner='%s' AND (", $this->table, $this->owner); @@ -303,7 +376,12 @@ class abook_database extends addressbook_backend { DB::errorMessage($r))); } - /* Modify address */ + /** + * Modify address + * @param string $alias modified alias + * @param array $userdata new data + * @return bool + */ function modify($alias, $userdata) { if (!$this->writeable) { return $this->set_error(_("Addressbook is read-only")); @@ -312,7 +390,7 @@ class abook_database extends addressbook_backend { if (!$this->open()) { return false; } - + /* See if user exist */ $ret = $this->lookup($alias); if (empty($ret)) { @@ -324,11 +402,11 @@ class abook_database extends addressbook_backend { $query = sprintf("UPDATE %s SET nickname='%s', firstname='%s', ". "lastname='%s', email='%s', label='%s' ". "WHERE owner='%s' AND nickname='%s'", - $this->table, + $this->table, $this->dbh->quoteString($userdata['nickname']), - $this->dbh->quoteString($userdata['firstname']), + $this->dbh->quoteString($userdata['firstname']), $this->dbh->quoteString($userdata['lastname']), - $this->dbh->quoteString($userdata['email']), + $this->dbh->quoteString($userdata['email']), $this->dbh->quoteString($userdata['label']), $this->owner, $this->dbh->quoteString($alias) ); @@ -345,4 +423,5 @@ class abook_database extends addressbook_backend { } } /* End of class abook_database */ -?> +// vim: et ts=4 +?> \ No newline at end of file