Source for file abook_database.php

Documentation is available at abook_database.php

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

Documentation generated on Wed, 19 Jun 2013 04:21:32 +0200 by phpDocumentor 1.4.3