Source for file abook_database.php

Documentation is available at abook_database.php

  1. <?php
  2.  
  3. /**
  4.  * abook_database.php
  5.  *
  6.  * Supported database schema
  7.  * <pre>
  8.  *  owner varchar(128) NOT NULL
  9.  *  nickname varchar(16) NOT NULL
  10.  *  firstname varchar(128)
  11.  *  lastname varchar(128)
  12.  *  email varchar(128) NOT NULL
  13.  *  label varchar(255)
  14.  *  PRIMARY KEY (owner,nickname)
  15.  * </pre>
  16.  *
  17.  * @copyright &copy; 1999-2006 The SquirrelMail Project Team
  18.  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  19.  * @version $Id: abook_database.php,v 1.44 2006/07/15 12:00:44 tokul Exp $
  20.  * @package squirrelmail
  21.  * @subpackage addressbook
  22.  */
  23.  
  24. /**
  25.  * Needs the DB functions
  26.  * Don't display errors here. Error will be set in class constructor function.
  27.  */
  28. @include_once('DB.php');
  29.  
  30. /**
  31.  * Address book in a database backend
  32.  *
  33.  * Backend for personal/shared address book stored in a database,
  34.  * accessed using the DB-classes in PEAR.
  35.  *
  36.  * IMPORTANT:  The PEAR modules must be in the include path
  37.  * for this class to work.
  38.  *
  39.  * An array with the following elements must be passed to
  40.  * the class constructor (elements marked ? are optional):
  41.  * <pre>
  42.  *   dsn       => database DNS (see PEAR for syntax)
  43.  *   table     => table to store addresses in (must exist)
  44.  *   owner     => current user (owner of address data)
  45.  * ? name      => name of address book
  46.  * ? writeable => set writeable flag (true/false)
  47.  * ? listing   => enable/disable listing
  48.  * </pre>
  49.  * The table used should have the following columns:
  50.  * owner, nickname, firstname, lastname, email, label
  51.  * The pair (owner,nickname) should be unique (primary key).
  52.  *
  53.  *  NOTE. This class should not be used directly. Use the
  54.  *        "AddressBook" class instead.
  55.  * @package squirrelmail
  56.  * @subpackage addressbook
  57.  */
  58. class abook_database extends addressbook_backend {
  59.     /**
  60.      * Backend type
  61.      * @var string 
  62.      */
  63.     var $btype = 'local';
  64.     /**
  65.      * Backend name
  66.      * @var string 
  67.      */
  68.     var $bname = 'database';
  69.  
  70.     /**
  71.      * Data Source Name (connection description)
  72.      * @var string 
  73.      */
  74.     var $dsn       = '';
  75.     /**
  76.      * Table that stores addresses
  77.      * @var string 
  78.      */
  79.     var $table     = '';
  80.     /**
  81.      * Owner name
  82.      *
  83.      * Limits list of database entries visible to end user
  84.      * @var string 
  85.      */
  86.     var $owner     = '';
  87.     /**
  88.      * Database Handle
  89.      * @var resource 
  90.      */
  91.     var $dbh       = false;
  92.     /**
  93.      * Enable/disable writing into address book
  94.      * @var bool 
  95.      */
  96.     var $writeable = true;
  97.     /**
  98.      * Enable/disable address book listing
  99.      * @var bool 
  100.      */
  101.     var $listing = true;
  102.  
  103.     /* ========================== Private ======================= */
  104.  
  105.     /**
  106.      * Constructor
  107.      * @param array $param address book backend options
  108.      */
  109.     function abook_database($param) {
  110.         $this->sname = _("Personal address book");
  111.  
  112.         /* test if Pear DB class is available and freak out if it is not */
  113.         if (! class_exists('DB')) {
  114.             // same error also in db_prefs.php
  115.             $error  = _("Could not include PEAR database functions required for the database backend.") . "\n";
  116.             $error .= sprintf(_("Is PEAR installed, and is the include path set correctly to find %s?"),
  117.                               'DB.php') . "\n";
  118.             $error .= _("Please contact your system administrator and report this error.");
  119.             return $this->set_error($error);
  120.         }
  121.  
  122.         if (is_array($param)) {
  123.             if (empty($param['dsn']) ||
  124.                 empty($param['table']) ||
  125.                 empty($param['owner'])) {
  126.                 return $this->set_error('Invalid parameters');
  127.             }
  128.  
  129.             $this->dsn   = $param['dsn'];
  130.             $this->table = $param['table'];
  131.             $this->owner = $param['owner'];
  132.  
  133.             if (!empty($param['name'])) {
  134.                $this->sname = $param['name'];
  135.             }
  136.  
  137.             if (isset($param['writeable'])) {
  138.                $this->writeable = $param['writeable'];
  139.             }
  140.  
  141.             if (isset($param['listing'])) {
  142.                $this->listing = $param['listing'];
  143.             }
  144.  
  145.             $this->open(true);
  146.         }
  147.         else {
  148.             return $this->set_error('Invalid argument to constructor');
  149.         }
  150.     }
  151.  
  152.  
  153.     /**
  154.      * Open the database.
  155.      * @param bool $new new connection if it is true
  156.      * @return bool 
  157.      */
  158.     function open($new = false) {
  159.         $this->error = '';
  160.  
  161.         /* Return true is file is open and $new is unset */
  162.         if ($this->dbh && !$new) {
  163.             return true;
  164.         }
  165.  
  166.         /* Close old file, if any */
  167.         if ($this->dbh) {
  168.             $this->close();
  169.         }
  170.  
  171.         $dbh = DB::connect($this->dsn, true);
  172.  
  173.         if (DB::isError($dbh)) {
  174.             return $this->set_error(sprintf(_("Database error: %s"),
  175.                                             DB::errorMessage($dbh)));
  176.         }
  177.  
  178.         $this->dbh = $dbh;
  179.  
  180.         /**
  181.          * field names are lowercased.
  182.          * We use unquoted identifiers and they use upper case in Oracle
  183.          */
  184.         $this->dbh->setOption('portability', DB_PORTABILITY_LOWERCASE);
  185.  
  186.         return true;
  187.     }
  188.  
  189.     /**
  190.      * Close the file and forget the filehandle
  191.      */
  192.     function close() {
  193.         $this->dbh->disconnect();
  194.         $this->dbh = false;
  195.     }
  196.  
  197.     /* ========================== Public ======================== */
  198.  
  199.     /**
  200.      * Search the database
  201.      *
  202.      * Backend supports only * and ? wildcards. Complex eregs are not supported.
  203.      * Search is case insensitive.
  204.      * @param string $expr search expression
  205.      * @return array search results. boolean false on error
  206.      */
  207.     function search($expr) {
  208.         $ret = array();
  209.         if(!$this->open()) {
  210.             return false;
  211.         }
  212.  
  213.         /* To be replaced by advanded search expression parsing */
  214.         if (is_array($expr)) {
  215.             return;
  216.         }
  217.  
  218.         // don't allow wide search when listing is disabled.
  219.         if ($expr=='*' && ! $this->listing)
  220.             return array();
  221.  
  222.         /* lowercase expression in order to make it case insensitive */
  223.         $expr = strtolower($expr);
  224.  
  225.         /* escape SQL wildcards */
  226.         $expr = str_replace('_', '\\_', $expr);
  227.         $expr = str_replace('%', '\\%', $expr);
  228.  
  229.         /* Convert wildcards to SQL syntax  */
  230.         $expr = str_replace('?', '_', $expr);
  231.         $expr = str_replace('*', '%', $expr);
  232.         $expr = $this->dbh->quoteString($expr);
  233.         $expr = "%$expr%";
  234.  
  235.         /* create escape expression */
  236.         $escape = 'ESCAPE \'' . $this->dbh->quoteString('\\') . '\'';
  237.     
  238.         $query = sprintf("SELECT * FROM %s WHERE owner='%s' AND " .
  239.                          "(LOWER(firstname) LIKE '%s' %s OR LOWER(lastname) LIKE '%s' %s)",
  240.                          $this->table, $this->owner, $expr, $escape, $expr, $escape);
  241.  
  242.         $res = $this->dbh->query($query);
  243.  
  244.         if (DB::isError($res)) {
  245.             return $this->set_error(sprintf(_("Database error: %s"),
  246.                                             DB::errorMessage($res)));
  247.         }
  248.  
  249.         while ($row = $res->fetchRow(DB_FETCHMODE_ASSOC)) {
  250.             array_push($ret, array('nickname'  => $row['nickname'],
  251.                                    'name'      => $this->fullname($row['firstname'], $row['lastname']),
  252.                                    'firstname' => $row['firstname'],
  253.                                    'lastname'  => $row['lastname'],
  254.                                    'email'     => $row['email'],
  255.                                    'label'     => $row['label'],
  256.                                    'backend'   => $this->bnum,
  257.                                    'source'    => &$this->sname));
  258.         }
  259.         return $ret;
  260.     }
  261.  
  262.     /**
  263.      * Lookup alias
  264.      * @param string $alias alias
  265.      * @return array search results
  266.      */
  267.     function lookup($alias) {
  268.         if (empty($alias)) {
  269.             return array();
  270.         }
  271.  
  272.         $alias = strtolower($alias);
  273.  
  274.         if (!$this->open()) {
  275.             return false;
  276.         }
  277.  
  278.         $query = sprintf("SELECT * FROM %s WHERE owner='%s' AND LOWER(nickname)='%s'",
  279.                          $this->table, $this->owner, $this->dbh->quoteString($alias));
  280.  
  281.         $res = $this->dbh->query($query);
  282.  
  283.         if (DB::isError($res)) {
  284.             return $this->set_error(sprintf(_("Database error: %s"),
  285.                                             DB::errorMessage($res)));
  286.         }
  287.  
  288.         if ($row = $res->fetchRow(DB_FETCHMODE_ASSOC)) {
  289.             return array('nickname'  => $row['nickname'],
  290.                          'name'      => $this->fullname($row['firstname'], $row['lastname']),
  291.                          'firstname' => $row['firstname'],
  292.                          'lastname'  => $row['lastname'],
  293.                          'email'     => $row['email'],
  294.                          'label'     => $row['label'],
  295.                          'backend'   => $this->bnum,
  296.                          'source'    => &$this->sname);
  297.         }
  298.         return array();
  299.     }
  300.  
  301.     /**
  302.      * List all addresses
  303.      * @return array search results
  304.      */
  305.     function list_addr() {
  306.         $ret = array();
  307.         if (!$this->open()) {
  308.             return false;
  309.         }
  310.  
  311.         if(isset($this->listing) && !$this->listing) {
  312.             return array();
  313.         }
  314.  
  315.  
  316.         $query = sprintf("SELECT * FROM %s WHERE owner='%s'",
  317.                          $this->table, $this->owner);
  318.  
  319.         $res = $this->dbh->query($query);
  320.  
  321.         if (DB::isError($res)) {
  322.             return $this->set_error(sprintf(_("Database error: %s"),
  323.                                             DB::errorMessage($res)));
  324.         }
  325.  
  326.         while ($row = $res->fetchRow(DB_FETCHMODE_ASSOC)) {
  327.             array_push($ret, array('nickname'  => $row['nickname'],
  328.                                    'name'      => $this->fullname($row['firstname'], $row['lastname']),
  329.                                    'firstname' => $row['firstname'],
  330.                                    'lastname'  => $row['lastname'],
  331.                                    'email'     => $row['email'],
  332.                                    'label'     => $row['label'],
  333.                                    'backend'   => $this->bnum,
  334.                                    'source'    => &$this->sname));
  335.         }
  336.         return $ret;
  337.     }
  338.  
  339.     /**
  340.      * Add address
  341.      * @param array $userdata added data
  342.      * @return bool 
  343.      */
  344.     function add($userdata) {
  345.         if (!$this->writeable) {
  346.             return $this->set_error(_("Address book is read-only"));
  347.         }
  348.  
  349.         if (!$this->open()) {
  350.             return false;
  351.         }
  352.  
  353.         /* See if user exist already */
  354.         $ret = $this->lookup($userdata['nickname']);
  355.         if (!empty($ret)) {
  356.             return $this->set_error(sprintf(_("User \"%s\" already exists"),$ret['nickname']));
  357.         }
  358.  
  359.         /* Create query */
  360.         $query = sprintf("INSERT INTO %s (owner, nickname, firstname, " .
  361.                          "lastname, email, label) VALUES('%s','%s','%s'," .
  362.                          "'%s','%s','%s')",
  363.                          $this->table, $this->owner,
  364.                          $this->dbh->quoteString($userdata['nickname']),
  365.                          $this->dbh->quoteString($userdata['firstname']),
  366.                          $this->dbh->quoteString((!empty($userdata['lastname'])?$userdata['lastname']:'')),
  367.                          $this->dbh->quoteString($userdata['email']),
  368.                          $this->dbh->quoteString((!empty($userdata['label'])?$userdata['label']:'')) );
  369.  
  370.          /* Do the insert */
  371.          $r = $this->dbh->simpleQuery($query);
  372.  
  373.          /* Check for errors */
  374.          if (DB::isError($r)) {
  375.              return $this->set_error(sprintf(_("Database error: %s"),
  376.                                              DB::errorMessage($r)));
  377.          }
  378.          return true;
  379.     }
  380.  
  381.     /**
  382.      * Deletes address book entries
  383.      * @param array $alias aliases that have to be deleted. numerical
  384.      *   array with nickname values
  385.      * @return bool 
  386.      */
  387.     function remove($alias) {
  388.         if (!$this->writeable) {
  389.             return $this->set_error(_("Address book is read-only"));
  390.         }
  391.  
  392.         if (!$this->open()) {
  393.             return false;
  394.         }
  395.  
  396.         /* Create query */
  397.         $query = sprintf("DELETE FROM %s WHERE owner='%s' AND (",
  398.                          $this->table, $this->owner);
  399.  
  400.         $sepstr = '';
  401.         while (list($undef, $nickname) = each($alias)) {
  402.             $query .= sprintf("%s nickname='%s' ", $sepstr,
  403.                               $this->dbh->quoteString($nickname));
  404.             $sepstr = 'OR';
  405.         }
  406.         $query .= ')';
  407.  
  408.         /* Delete entry */
  409.         $r = $this->dbh->simpleQuery($query);
  410.  
  411.         /* Check for errors */
  412.         if (DB::isError($r)) {
  413.             return $this->set_error(sprintf(_("Database error: %s"),
  414.                                             DB::errorMessage($r)));
  415.         }
  416.         return true;
  417.     }
  418.  
  419.     /**
  420.      * Modify address
  421.      * @param string $alias modified alias
  422.      * @param array $userdata new data
  423.      * @return bool 
  424.      */
  425.     function modify($alias, $userdata) {
  426.         if (!$this->writeable) {
  427.             return $this->set_error(_("Address book is read-only"));
  428.         }
  429.  
  430.         if (!$this->open()) {
  431.             return false;
  432.         }
  433.  
  434.          /* See if user exist */
  435.         $ret = $this->lookup($alias);
  436.         if (empty($ret)) {
  437.             return $this->set_error(sprintf(_("User \"%s\" does not exist"),$alias));
  438.         }
  439.  
  440.         /* make sure that new nickname is not used */
  441.         if (strtolower($alias) != strtolower($userdata['nickname'])) {
  442.             /* same check as in add() */
  443.             $ret = $this->lookup($userdata['nickname']);
  444.             if (!empty($ret)) {
  445.                 $error = sprintf(_("User '%s' already exist."), $ret['nickname']);
  446.                 return $this->set_error($error);
  447.             }
  448.         }
  449.  
  450.         /* Create query */
  451.         $query = sprintf("UPDATE %s SET nickname='%s', firstname='%s', ".
  452.                          "lastname='%s', email='%s', label='%s' ".
  453.                          "WHERE owner='%s' AND nickname='%s'",
  454.                          $this->table,
  455.                          $this->dbh->quoteString($userdata['nickname']),
  456.                          $this->dbh->quoteString($userdata['firstname']),
  457.                          $this->dbh->quoteString((!empty($userdata['lastname'])?$userdata['lastname']:'')),
  458.                          $this->dbh->quoteString($userdata['email']),
  459.                          $this->dbh->quoteString((!empty($userdata['label'])?$userdata['label']:'')),
  460.                          $this->owner,
  461.                          $this->dbh->quoteString($alias) );
  462.  
  463.         /* Do the insert */
  464.         $r = $this->dbh->simpleQuery($query);
  465.  
  466.         /* Check for errors */
  467.         if (DB::isError($r)) {
  468.             return $this->set_error(sprintf(_("Database error: %s"),
  469.                                             DB::errorMessage($r)));
  470.         }
  471.         return true;
  472.     }
  473. } /* End of class abook_database */
  474.  
  475. // vim: et ts=4

Documentation generated on Sat, 07 Oct 2006 16:08:24 +0300 by phpDocumentor 1.3.0RC6