DBA
[ class tree: DBA ] [ index: DBA ] [ all elements ]

Source for file Builtin.php

Documentation is available at Builtin.php

  1. <?php
  2. /* vim: set expandtab tabstop=4 shiftwidth=4: */
  3. // +----------------------------------------------------------------------+
  4. // | Copyright (c) 2002-2003 Brent Cook                                        |
  5. // +----------------------------------------------------------------------+
  6. // | This library is free software; you can redistribute it and/or        |
  7. // | modify it under the terms of the GNU Lesser General Public           |
  8. // | License as published by the Free Software Foundation; either         |
  9. // | version 2.1 of the License, or (at your option) any later version.   |
  10. // |                                                                      |
  11. // | This library is distributed in the hope that it will be useful,      |
  12. // | but WITHOUT ANY WARRANTY; without even the implied warranty of       |
  13. // | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU    |
  14. // | Lesser General Public License for more details.                      |
  15. // |                                                                      |
  16. // | You should have received a copy of the GNU Lesser General Public     |
  17. // | License along with this library; if not, write to the Free Software  |
  18. // | Foundation, Inc., 59 Temple Place, Suite 330,Boston,MA 02111-1307 USA|
  19. // +----------------------------------------------------------------------+
  20. //
  21. // $Id: Builtin.php,v 1.14 2007/04/16 07:52:30 davidc Exp $
  22.  
  23. require_once 'DBA.php';
  24.  
  25. /**
  26.  * DBA_Driver_Builtin uses the builtin dba functions of PHP as the underlying
  27.  * driver for a DBA class. Depending on the driver, this can be faster or
  28.  * slower than the DBA_Driver_File class.
  29.  *
  30.  * This class has been tested with DB3 and GDBM and probably works with DB2.
  31.  * Other drivers may have quirks that this class does not address yet. CDB
  32.  * is known to be unsuitable as a driver due to its lack of write ability.
  33.  *
  34.  * @author  Brent Cook <busterb@mail.utexas.edu>
  35.  * @version 1.0
  36.  * @access  public
  37.  * @package DBA
  38.  */
  39. class DBA_Driver_Builtin extends DBA
  40. {
  41.  
  42.     // {{{ instance variables
  43.     /**
  44.      * Name of the database
  45.      * @access private
  46.      */
  47.     var $_dbName;
  48.  
  49.     /**
  50.      * Indicates the current ability for read/write operations
  51.      * @access private
  52.      */
  53.     var $_writable;
  54.  
  55.     /**
  56.      * Indicates the current ability for read operations
  57.      * @access private
  58.      */
  59.     var $_readable;
  60.  
  61.     /**
  62.      * Name of the builtin dba driver to use
  63.      * @access private
  64.      */
  65.     var $_driver;
  66.  
  67.     /**
  68.      * Indicates the ability of the dba driver to replace values
  69.      * @access private
  70.      */
  71.     var $_hasReplace;
  72.     // }}}
  73.  
  74.     // {{{ DBA_Driver_Builtin($driver = 'gdbm')
  75.     /* Constructor
  76.      *
  77.      * @access public
  78.      * @param   string  $driver dba driver to use
  79.      */
  80.     function DBA_Driver_Builtin($driver 'gdbm')
  81.     {
  82.         // call the base constructor
  83.         $this->DBA();
  84.         $this->_driver $driver;
  85.     }
  86.     // }}}
  87.  
  88.     // {{{ open($dbName='', $mode='r', $persistent=false)
  89.     /**
  90.      * Opens a database.
  91.      *
  92.      * @access public
  93.      * @param   string  $dbName The name of a database
  94.      * @param   string  $mode The mode in which to open a database.
  95.      *                    'r' opens read-only.
  96.      *                    'w' opens read-write.
  97.      *                    'n' creates a new database and opens read-write.
  98.      *                    'c' creates a new database if the database does not
  99.      *                       exist and opens read-write.
  100.      * @param   boolean $persistent Determines whether to open the database
  101.      *                   peristently. Not supported here.
  102.      * @return  object PEAR_Error on failure
  103.      */
  104.     function open($dbName=''$mode='r'$persistent = false)
  105.     {
  106.         if (is_null($this->_driver)) {
  107.             return $this->raiseError(DBA_ERROR_NO_DRIVER);
  108.         }
  109.  
  110.         if ($this->_driver == 'gdbm'{
  111.             $this->_hasReplace = false;
  112.         else {
  113.             $this->_hasReplace = true;
  114.         }
  115.  
  116.         if ($dbName == ''{
  117.             return $this->raiseError(DBA_ERROR_NO_DBNAME);
  118.         else {
  119.             $this->_dbName $dbName;
  120.         }
  121.  
  122.         switch ($mode{
  123.             case 'r':
  124.                     // open for reading
  125.                     $this->_writable = false;
  126.                     $this->_readable = true;
  127.                     break;
  128.             case 'n':
  129.             case 'c':
  130.             case 'w':
  131.                     $this->_writable = true;
  132.                     $this->_readable = true;
  133.                     break;
  134.             default:
  135.                 return $this->raiseError(DBA_ERROR_INVALID_MODENULLNULL,
  136.                     'filemode: '.$mode);
  137.         }
  138.  
  139.         // open the index file
  140.         $params = array($dbname$mode$this->_driver);
  141.         
  142.         $connect_function !is_null($persistent'dba_popen' 'dba_open';
  143.         $connector        @call_user_func($connect_function$params)
  144.         
  145.         if (PEAR::isError($connector)) {
  146.             $this->_writable = false;
  147.             $this->_readable = false;
  148.             return $this->raiseError(DBA_ERROR_CANNOT_OPENnullnull,
  149.                                      'DB Name: ' $dbName ' filemode: ' $mode);
  150.         }
  151.         
  152.         if ($connector === false{
  153.             $this->_writable = false;
  154.             $this->_readable = false;
  155.             return $this->raiseError(DBA_ERROR_CANNOT_OPENNULLNULL,
  156.                 'dbname: '.$dbName.' filemode: '.$mode);
  157.         }
  158.  
  159.         $this->_dba $connector;
  160.     }
  161.     // }}}
  162.  
  163.     // {{{ close()
  164.     /**
  165.      * Closes an open database.
  166.      *
  167.      * @access  public
  168.      * @return  object PEAR_Error on failure
  169.      */
  170.     function close()
  171.     {
  172.         if ($this->isOpen()) {
  173.             $this->_readable = false;
  174.             $this->_writable = false;
  175.             dba_sync($this->_dba)// db2 is known to require syncs
  176.             dba_close($this->_dba);
  177.         else {
  178.             return $this->raiseError(DBA_ERROR_NOT_OPEN);
  179.         }
  180.     }
  181.     // }}}
  182.  
  183.     // {{{ reopen($mode)
  184.     /**
  185.      * Reopens an already open database in read-only or write mode.
  186.      * If the database is already in the requested mode, then this function
  187.      * does nothing.
  188.      *
  189.      * @access  public
  190.      * @param   string  $mode 'r' for read-only, 'w' for read/write
  191.      * @return  object PEAR_Error on failure
  192.      */
  193.     function reopen($mode)
  194.     {
  195.         if ($this->isOpen()) {
  196.             if (($mode == 'r'&& $this->isWritable()) {
  197.                 // Reopening as read-only
  198.                 $this->close();
  199.                 return $this->open($this->_dbName'r');
  200.             elseif (($mode == 'w'&& (!$this->isWritable)) {
  201.                 // Reopening as read-write
  202.                 $this->close();
  203.                 return $this->open($this->_dbName'w');
  204.             }
  205.         else {
  206.             return $this->raiseError(DBA_ERROR_NOT_OPEN);
  207.         }
  208.     }
  209.     // }}}
  210.  
  211.     // {{{ _DBA_Driver_Builtin()
  212.     /**
  213.      * PEAR emulated destructor calls close on PHP shutdown
  214.      * @access private
  215.      */
  216.     function _DBA_Driver_Builtin()
  217.     {
  218.         $this->close();
  219.     }
  220.     // }}}
  221.  
  222.     // {{{ isOpen()
  223.     /**
  224.      * Returns the current open status for the database
  225.      *
  226.      * @access  public
  227.      * @return  boolean true if open, false if closed
  228.      */
  229.     function isOpen()
  230.     {
  231.         return($this->_readable || $this->_writable);
  232.     }
  233.     // }}}
  234.  
  235.     // {{{ isReadable()
  236.     /**
  237.      * Returns the current read status for the database
  238.      *
  239.      * @access  public
  240.      * @return  boolean true if readable, false if not
  241.      */
  242.     function isReadable()
  243.     {
  244.         return $this->_readable;
  245.     }
  246.     // }}}
  247.  
  248.     // {{{ isWritable()
  249.     /**
  250.      * Returns the current write status for the database
  251.      *
  252.      * @access  public
  253.      * @return  boolean true if writable, false if not
  254.      */
  255.      function isWritable()
  256.      {
  257.          return $this->_writable;
  258.      }
  259.     // }}}
  260.  
  261.     // {{{ remove($key)
  262.     /**
  263.      * Removes the value at location $key
  264.      *
  265.      * @access  public
  266.      * @param   string  $key key to delete
  267.      * @return  object PEAR_Error on failure
  268.      */
  269.     function remove($key)
  270.     {
  271.         if ($this->isWritable()) {
  272.             if (!dba_delete($key$this->_dba)) {
  273.                 return $this->raiseError(DBA_ERROR_NOT_FOUNDNULLNULL'key: '.$key);
  274.             }
  275.         else {
  276.             return $this->raiseError(DBA_ERROR_NOT_WRITEABLE);
  277.         }
  278.     }
  279.     // }}}
  280.  
  281.     // {{{ fetch($key)
  282.     /**
  283.      * Returns the value that is stored at $key.
  284.      *
  285.      * @access  public
  286.      * @param   string $key key to examine
  287.      * @return  mixed the requested value on success, false on failure
  288.      */
  289.     function fetch($key)
  290.     {
  291.         if ($this->isReadable()) {
  292.             if (dba_exists($key$this->_dba)) {
  293.                 return dba_fetch($key$this->_dba);
  294.             else {
  295.                 return $this->raiseError(DBA_ERROR_NOT_FOUNDNULLNULL'key: '.$key);
  296.             }
  297.         else {
  298.             return $this->raiseError(DBA_ERROR_NOT_READABLE);
  299.         }
  300.     }
  301.     // }}}
  302.  
  303.     // {{{ firstkey()
  304.     /**
  305.      * Returns the first key in the database
  306.      *
  307.      * @access  public
  308.      * @return  mixed string on success, false on failure
  309.      */
  310.     function firstkey()
  311.     {
  312.         if ($this->isReadable()) {
  313.             return dba_firstkey($this->_dba);
  314.         else {
  315.             return false;
  316.         }
  317.     }
  318.     // }}}
  319.  
  320.     // {{{ size()
  321.     /**
  322.      * Calculates the size of the database in number of keys
  323.      *
  324.      * @access  public
  325.      * @return  int    number of keys in the database
  326.      */
  327.     function size()
  328.     {
  329.         $key dba_firstkey($this->_dba);
  330.         $size = 0;
  331.         while ($key !== false{
  332.             ++$size;
  333.             $key dba_nextkey($this->_dba);
  334.         }
  335.         return $size;
  336.     }
  337.     // }}}
  338.  
  339.     // {{{ nextkey()
  340.     /**
  341.      * Returns the next key in the database, false if there is a problem
  342.      *
  343.      * @access  public
  344.      * @return  mixed string on success, false on failure
  345.      */
  346.     function nextkey()
  347.     {
  348.         if ($this->isReadable()) {
  349.             return dba_nextkey($this->_dba);
  350.         else {
  351.             return false;
  352.         }
  353.     }
  354.     // }}}
  355.  
  356.     // {{{ getkeys()
  357.     /**
  358.      * Returns all keys in the database
  359.      *
  360.      * @access  public
  361.      * @return  mixed  array
  362.      */
  363.     function getkeys()
  364.     {
  365.         $keys = array();
  366.         if ($this->isReadable()) {
  367.             $key $this->firstkey();
  368.             while ($key !== FALSE{
  369.                 $keys[$key;
  370.                 $key $this->nextkey($key);
  371.             }
  372.         }
  373.         return $keys;
  374.     }
  375.     // }}}
  376.  
  377.     // {{{ insert($key, $value)
  378.     /**
  379.      * Inserts a new value at $key. Will not overwrite if the key/value pair
  380.      * already exist
  381.      *
  382.      * @access public
  383.      * @param   string  $key key to insert
  384.      * @param   string  $value value to store
  385.      * @return  object PEAR_Error on failure
  386.      */
  387.     function insert($key$value)
  388.     {
  389.         if ($this->isWritable()) {
  390.  
  391.             if ((!$this->_hasReplace && dba_exists($key$this->_dba)) ||
  392.                 (!dba_insert($key$value$this->_dba))) {
  393.                 return $this->raiseError(DBA_ERROR_ALREADY_EXISTSNULLNULL,
  394.                     'key: '.$key);
  395.             }
  396.         else {
  397.             return $this->raiseError(DBA_ERROR_NOT_WRITEABLE);
  398.         }
  399.     }
  400.     // }}}
  401.  
  402.     // {{{ replace($key, $value)
  403.     /**
  404.      * Inserts a new value at key. If the key/value pair
  405.      * already exist, overwrites the value
  406.      *
  407.      * @access public
  408.      * @param   $key    string the key to insert
  409.      * @param   $value  string the value to store
  410.      * @return  object  PEAR_Error on failure
  411.      */
  412.     function replace($key$value)
  413.     {
  414.         if ($this->isWritable()) {
  415.  
  416.             if ($this->_hasReplace{
  417.                 return dba_replace($key$value$this->_dba);
  418.             else {
  419.                 $r = true;
  420.                 if (dba_exists($key$this->_dba)) {
  421.                     $r dba_delete($key$this->_dba);
  422.                 }
  423.                 return $r && dba_insert($key$value$this->_dba);
  424.             }
  425.  
  426.         else {
  427.             return $this->raiseError(DBA_ERROR_NOT_WRITEABLE);
  428.         }
  429.     }
  430.     // }}}
  431.     
  432.     // {{{ create($dbName, $driver='gdbm')
  433.     /**
  434.      * Creates a new database file if one does not exist. If it already exists,
  435.      * updates the last-updated timestamp on the database
  436.      *
  437.      * @access  public
  438.      * @param   string  $dbName the database to create
  439.      * @param   string  $driver the dba driver to use
  440.      * @return  object  PEAR_Error on failure
  441.      */
  442.     function create($dbName$driver='gdbm')
  443.     {
  444.         $db dba_open($dbName'n'$driver);
  445.  
  446.         if (PEAR::isError($db)) {
  447.             return $this->raiseError(DBA_ERROR_CANNOT_CREATENULLNULL,
  448.                                      'dbname: '.$dbname);
  449.         }
  450.  
  451.         if (!(($db !== false&& dba_close($db))) {
  452.             return $this->raiseError(DBA_ERROR_CANNOT_CREATENULLNULL,
  453.                 'dbname: '.$dbname);
  454.         }
  455.     }
  456.     // }}}
  457.  
  458.     // {{{ db_exists($dbName)
  459.     /**
  460.      * Indicates whether a database with given name exists
  461.      *
  462.      * @access  public
  463.      * @param   string  $dbName the database name to check for existence
  464.      * @return  boolean true if the database exists, false if it doesn't
  465.      */
  466.     function db_exists($dbName)
  467.     {
  468.         return file_exists($dbName);
  469.     }
  470.     // }}}
  471.  
  472.     // {{{ db_drop($dbName)
  473.     /**
  474.      * Removes a database from existence
  475.      *
  476.      * @access  public
  477.      * @param   string  $dbName the database name to drop
  478.      * @return  object  PEAR_Error on failure
  479.      */
  480.     function db_drop($dbName)
  481.     {
  482.         if (DBA_Driver_Builtin::db_exists($dbName)) {
  483.             if (!unlink($dbName)) {
  484.                 return $this->raiseError(DBA_ERROR_CANNOT_DROPNULLNULL,
  485.                     'dbname: '.$dbName);
  486.             }
  487.         else {
  488.             return $this->raiseError(DBA_ERROR_NOSUCHDBNULLNULL,
  489.                 'dbname: '.$dbName);
  490.         }
  491.     }
  492.     // }}}
  493.  
  494.     // {{{ drop()
  495.     /**
  496.      * Removes the last open database from existence
  497.      *
  498.      * @access  public
  499.      * @return  object  PEAR_Error on failure
  500.      */
  501.     function drop()
  502.     {
  503.         $this->close();
  504.         return $this->db_drop($this->_dbName);
  505.     }
  506.     // }}}
  507.  
  508.     // {{{ exists($key)
  509.     /**
  510.      * Check whether key exists
  511.      *
  512.      * @access  public
  513.      * @param   string   $key 
  514.      * @return  boolean true if the key exists, false if it doesn't
  515.      */
  516.     function exists($key)
  517.     {
  518.         return($this->isOpen(&& dba_exists($key$this->_dba));
  519.     }
  520.     // }}}
  521.  
  522.     // {{{ sync()
  523.     /**
  524.      * Synchronizes an open database to disk
  525.      * @access public
  526.      */
  527.     function sync()
  528.     {
  529.         return dba_sync($this->_dba);
  530.     }
  531.     // }}}
  532.  
  533.     // {{{ optimize()
  534.     /**
  535.      * Optimizes an open database
  536.      * @access public
  537.      */
  538.     function optimize()
  539.     {
  540.         return dba_optimize($this->_dba);
  541.     }
  542.     // }}}
  543. }
  544. ?>

Documentation generated on Mon, 11 Mar 2019 14:59:54 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.