X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=functions%2Fabook_database.php;h=db7e1a008a1cb823f83d40e388f2b587c91b44fb;hb=4e38bc70577f553a97a320bbd0a1d0c5dac70b6e;hp=82ddba9dcd5ba708b9a2f829748d54fc430c43f4;hpb=17fca61d112f76a3f9c69be39eb1e8c252c95965;p=squirrelmail.git diff --git a/functions/abook_database.php b/functions/abook_database.php index 82ddba9d..db7e1a00 100644 --- a/functions/abook_database.php +++ b/functions/abook_database.php @@ -1,12 +1,30 @@ \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 addressbook stored in a database, + * 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,67 +32,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 */ -if (!include_once('DB.php')) { - // same error also in db_prefs.php - require_once(SM_PATH . 'functions/display_messages.php'); - $error = _("Could not include PEAR database functions required for the database backend.") . "
\n"; - $error .= _("Is PEAR installed, and is the include path set correctly to find DB.php?") . "
\n"; - $error .= _("Please contact your system administrator and report this error."); - error_box($error, $color); - exit; -} - -/** - * 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']; } @@ -93,43 +132,53 @@ 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 */ - function &search($expr) { + + /** + * Search the database + * @param string $expr search expression + * @return array search results + */ + function search($expr) { $ret = array(); if(!$this->open()) { return false; @@ -140,6 +189,10 @@ class abook_database extends addressbook_backend { return; } + // don't allow wide search when listing is disabled. + if ($expr=='*' && ! $this->listing) + return array(); + /* Make regexp from glob'ed expression */ $expr = str_replace('?', '_', $expr); $expr = str_replace('*', '%', $expr); @@ -168,19 +221,23 @@ class abook_database extends addressbook_backend { } return $ret; } - - /* Lookup alias */ - function &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 LOWER(nickname)='%s'", $this->table, $this->owner, $this->dbh->quoteString($alias)); @@ -204,23 +261,26 @@ class abook_database extends addressbook_backend { return array(); } - /* List all addresses */ - function &list_addr() { + /** + * 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))); @@ -239,7 +299,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")); @@ -248,12 +312,11 @@ class abook_database extends addressbook_backend { if (!$this->open()) { return false; } - + /* See if user exist already */ $ret = $this->lookup($userdata['nickname']); if (!empty($ret)) { - return $this->set_error(sprintf(_("User '%s' already exist"), - $ret['nickname'])); + return $this->set_error(sprintf(_("User \"%s\" already exists"),$ret['nickname'])); } /* Create query */ @@ -262,10 +325,10 @@ 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['lastname']), - $this->dbh->quoteString($userdata['email']), - $this->dbh->quoteString($userdata['label']) ); + $this->dbh->quoteString($userdata['firstname']), + $this->dbh->quoteString((!empty($userdata['lastname'])?$userdata['lastname']:'')), + $this->dbh->quoteString($userdata['email']), + $this->dbh->quoteString((!empty($userdata['label'])?$userdata['label']:'')) ); /* Do the insert */ $r = $this->dbh->simpleQuery($query); @@ -278,7 +341,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")); @@ -287,7 +354,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); @@ -311,7 +378,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")); @@ -320,24 +392,23 @@ class abook_database extends addressbook_backend { if (!$this->open()) { return false; } - + /* See if user exist */ $ret = $this->lookup($alias); if (empty($ret)) { - return $this->set_error(sprintf(_("User '%s' does not exist"), - $alias)); + return $this->set_error(sprintf(_("User \"%s\" does not exist"),$alias)); } /* Create query */ $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['lastname']), - $this->dbh->quoteString($userdata['email']), - $this->dbh->quoteString($userdata['label']), + $this->dbh->quoteString($userdata['firstname']), + $this->dbh->quoteString((!empty($userdata['lastname'])?$userdata['lastname']:'')), + $this->dbh->quoteString($userdata['email']), + $this->dbh->quoteString((!empty($userdata['label'])?$userdata['label']:'')), $this->owner, $this->dbh->quoteString($alias) ); @@ -353,6 +424,5 @@ class abook_database extends addressbook_backend { } } /* End of class abook_database */ - // vim: et ts=4 ?>