Support Joomla!

Joomla! 1.5 Documentation

Packages

Package: Joomla-Framework

License

Content on this site is copyright © 2005 - 2008 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution- NonCommercial- ShareAlike 2.5. Some parts of this website may be subject to other licenses.
Source code for file /joomla/database/database.php

Documentation is available at database.php

  1. <?php
  2. /**
  3. * @version        $Id: database.php 9870 2008-01-05 10:56:58Z eddieajau $
  4. * @package        Joomla.Framework
  5. * @subpackage    Database
  6. * @copyright    Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
  7. * @license        GNU/GPL, see LICENSE.php
  8. *  Joomla! is free software. This version may have been modified pursuant
  9. *  to the GNU General Public License, and as distributed it includes or
  10. *  is derivative of works licensed under the GNU General Public License or
  11. *  other free or open source software licenses.
  12. *  See COPYRIGHT.php for copyright notices and details.
  13. */
  14.  
  15. // Check to ensure this file is within the rest of the framework
  16. defined('JPATH_BASE') or die();
  17.  
  18. /**
  19.  * Database connector class
  20.  *
  21.  * @abstract
  22.  * @package        Joomla.Framework
  23.  * @subpackage    Database
  24.  * @since        1.0
  25.  */
  26. class JDatabase extends JObject
  27. {
  28.     /**
  29.      * The database driver name
  30.      *
  31.      * @var string 
  32.      */
  33.     var $name            = '';
  34.  
  35.     /**
  36.      * The query sql string
  37.      *
  38.      * @var string 
  39.      ***/
  40.     var $_sql            = '';
  41.  
  42.     /**
  43.      * The database error number
  44.      *
  45.      * @var int 
  46.      ***/
  47.     var $_errorNum        = 0;
  48.  
  49.     /**
  50.      * The database error message
  51.      *
  52.      * @var string 
  53.      */
  54.     var $_errorMsg        = '';
  55.  
  56.     /**
  57.      * The prefix used on all database tables
  58.      *
  59.      * @var string 
  60.      */
  61.     var $_table_prefix    = '';
  62.  
  63.     /**
  64.      * The connector resource
  65.      *
  66.      * @var resource 
  67.      */
  68.     var $_resource        = '';
  69.  
  70.     /**
  71.      * The last query cursor
  72.      *
  73.      * @var resource 
  74.      */
  75.     var $_cursor        = null;
  76.  
  77.     /**
  78.      * Debug option
  79.      *
  80.      * @var boolean 
  81.      */
  82.     var $_debug            = 0;
  83.  
  84.     /**
  85.      * The limit for the query
  86.      *
  87.      * @var int 
  88.      */
  89.     var $_limit            = 0;
  90.  
  91.     /**
  92.      * The for offset for the limit
  93.      *
  94.      * @var int 
  95.      */
  96.     var $_offset        = 0;
  97.  
  98.     /**
  99.      * The number of queries performed by the object instance
  100.      *
  101.      * @var int 
  102.      */
  103.     var $_ticker        = 0;
  104.  
  105.     /**
  106.      * A log of queries
  107.      *
  108.      * @var array 
  109.      */
  110.     var $_log            = null;
  111.  
  112.     /**
  113.      * The null/zero date string
  114.      *
  115.      * @var string 
  116.      */
  117.     var $_nullDate        = null;
  118.  
  119.     /**
  120.      * Quote for named objects
  121.      *
  122.      * @var string 
  123.      */
  124.     var $_nameQuote        = null;
  125.  
  126.     /**
  127.      * UTF-8 support
  128.      *
  129.      * @var boolean 
  130.      * @since    1.5
  131.      */
  132.     var $_utf            = 0;
  133.  
  134.     /**
  135.      * The fields that are to be quote
  136.      *
  137.      * @var array 
  138.      * @since    1.5
  139.      */
  140.     var $_quoted    = null;
  141.  
  142.     /**
  143.      *  Legacy compatibility
  144.      *
  145.      * @var bool 
  146.      * @since    1.5
  147.      */
  148.     var $_hasQuoted    = null;
  149.  
  150.     /**
  151.     * Database object constructor
  152.     *
  153.     * @access    public
  154.     * @param    array    List of options used to configure the connection
  155.     * @since    1.5
  156.     */
  157.     function __construct( $options )
  158.     {
  159.         $prefix        = array_key_exists('prefix', $options)    ? $options['prefix']    : 'jos_';
  160.  
  161.         // Determine utf-8 support
  162.         $this->_utf = $this->hasUTF();
  163.  
  164.         //Set charactersets (needed for MySQL 4.1.2+)
  165.         if ($this->_utf){
  166.             $this->setUTF();
  167.         }
  168.  
  169.         $this->_table_prefix    = $prefix;
  170.         $this->_ticker            = 0;
  171.         $this->_errorNum        = 0;
  172.         $this->_log                = array();
  173.         $this->_quoted            = array();
  174.         $this->_hasQuoted        = false;
  175.  
  176.         // Register faked "destructor" in PHP4 to close all connections we might have made
  177.         if (version_compare(PHP_VERSION, '5') == -1) {
  178.             register_shutdown_function(array(&$this, '__destruct'));
  179.         }
  180.     }
  181.  
  182.     /**
  183.      * Returns a reference to the global Database object, only creating it
  184.      * if it doesn't already exist.
  185.      *
  186.      * The 'driver' entry in the parameters array specifies the database driver
  187.      * to be used (defaults to 'mysql' if omitted). All other parameters are
  188.      * database driver dependent.
  189.      *
  190.      * @param array Parameters to be passed to the database driver
  191.      * @return JDatabase A database object
  192.      * @since 1.5
  193.     */
  194.     function &getInstance( $options    = array() )
  195.     {
  196.         static $instances;
  197.  
  198.         if (!isset( $instances )) {
  199.             $instances = array();
  200.         }
  201.  
  202.         $signature = serialize( $options );
  203.  
  204.         if (empty($instances[$signature]))
  205.         {
  206.             $driver        = array_key_exists('driver', $options)         ? $options['driver']    : 'mysql';
  207.             $select        = array_key_exists('select', $options)        ? $options['select']    : true;
  208.             $database    = array_key_exists('database', $options)    ? $options['database']    : null;
  209.  
  210.             $driver = preg_replace('/[^A-Z0-9_\.-]/i', '', $driver);
  211.             $path    = dirname(__FILE__).DS.'database'.DS.$driver.'.php';
  212.  
  213.             if (file_exists($path)) {
  214.                 require_once($path);
  215.             } else {
  216.                 JError::setErrorHandling(E_ERROR, 'die'); //force error type to die
  217.                 $error = JError::raiseError( 500, JTEXT::_('Unable to load Database Driver:') .$driver);
  218.                 return $error;
  219.             }
  220.  
  221.             $adapter    = 'JDatabase'.$driver;
  222.             $instance    = new $adapter($options);
  223.  
  224.             if ( $error = $instance->getErrorMsg() )
  225.             {
  226.                 JError::setErrorHandling(E_ERROR, 'ignore'); //force error type to die
  227.                 $error = JError::raiseError( 500, JTEXT::_('Unable to connect to the database:') .$error);
  228.                 return $error;
  229.             }
  230.  
  231.  
  232.             $instances[$signature] = & $instance;
  233.         }
  234.  
  235.         return $instances[$signature];
  236.     }
  237.  
  238.     /**
  239.      * Database object destructor
  240.      *
  241.      * @abstract
  242.      * @access private
  243.      * @return boolean 
  244.      * @since 1.5
  245.      */
  246.     function __destruct()
  247.     {
  248.         return true;
  249.     }
  250.  
  251.     /**
  252.      * Get the database connectors
  253.      *
  254.      * @access public
  255.      * @return array An array of available session handlers
  256.      */
  257.     function getConnectors()
  258.     {
  259.         jimport('joomla.filesystem.folder');
  260.         $handlers = JFolder::files(dirname(__FILE__).DS.'database', '.php$');
  261.  
  262.         $names = array();
  263.         foreach($handlers as $handler)
  264.         {
  265.             $name = substr($handler, 0, strrpos($handler, '.'));
  266.             $class = 'JDatabase'.ucfirst($name);
  267.  
  268.             if(!class_exists($class)) {
  269.                 require_once(dirname(__FILE__).DS.'database'.DS.$name.'.php');
  270.             }
  271.  
  272.             if(call_user_func_array( array( trim($class), 'test' ), null)) {
  273.                 $names[] = $name;
  274.             }
  275.         }
  276.  
  277.         return $names;
  278.     }
  279.  
  280.     /**
  281.      * Test to see if the MySQLi connector is available
  282.      *
  283.      * @static
  284.      * @access public
  285.      * @return boolean  True on success, false otherwise.
  286.      */
  287.     function test()
  288.     {
  289.         return false;
  290.     }
  291.  
  292.     /**
  293.      * Determines if the connection to the server is active.
  294.      *
  295.      * @access      public
  296.      * @return      boolean 
  297.      * @since       1.5
  298.      */
  299.     function connected()
  300.     {
  301.         return false;
  302.     }
  303.  
  304.     /**
  305.      * Determines UTF support
  306.      *
  307.      * @abstract
  308.      * @access public
  309.      * @return boolean 
  310.      * @since 1.5
  311.      */
  312.     function hasUTF() {
  313.         return false;
  314.     }
  315.  
  316.     /**
  317.      * Custom settings for UTF support
  318.      *
  319.      * @abstract
  320.      * @access public
  321.      * @since 1.5
  322.      */
  323.     function setUTF() {
  324.     }
  325.  
  326.     /**
  327.      * Adds a field or array of field names to the list that are to be quoted
  328.      *
  329.      * @access public
  330.      * @param mixed Field name or array of names
  331.      * @since 1.5
  332.      */
  333.     function addQuoted( $quoted )
  334.     {
  335.         if (is_string( $quoted )) {
  336.             $this->_quoted[] = $quoted;
  337.         } else {
  338.             $this->_quoted = array_merge( $this->_quoted, (array)$quoted );
  339.         }
  340.         $this->_hasQuoted = true;
  341.     }
  342.  
  343.     /**
  344.      * Checks if field name needs to be quoted
  345.      *
  346.      * @access public
  347.      * @param string The field name
  348.      * @return bool 
  349.      */
  350.     function isQuoted( $fieldName )
  351.     {
  352.         if ($this->_hasQuoted) {
  353.             return in_array( $fieldName, $this->_quoted );
  354.         } else {
  355.             return true;
  356.         }
  357.     }
  358.  
  359.     /**
  360.      * Sets the debug level on or off
  361.      *
  362.      * @access public
  363.      * @param int 0 = off, 1 = on
  364.      */
  365.     function debug( $level ) {
  366.         $this->_debug = intval( $level );
  367.     }
  368.  
  369.     /**
  370.      * Get the database UTF-8 support
  371.      *
  372.      * @access public
  373.      * @return boolean 
  374.      * @since 1.5
  375.      */
  376.     function getUTFSupport() {
  377.         return $this->_utf;
  378.     }
  379.  
  380.     /**
  381.      * Get the error number
  382.      *
  383.      * @access public
  384.      * @return int The error number for the most recent query
  385.      */
  386.     function getErrorNum() {
  387.         return $this->_errorNum;
  388.     }
  389.  
  390.  
  391.     /**
  392.      * Get the error message
  393.      *
  394.      * @access public
  395.      * @return string The error message for the most recent query
  396.      */
  397.     function getErrorMsg($escaped = false)
  398.     {
  399.         if($escaped) {
  400.             return addslashes($this->_errorMsg);
  401.         } else {
  402.             return $this->_errorMsg;
  403.         }
  404.     }
  405.  
  406.     /**
  407.      * Get a database escaped string
  408.      *
  409.      * @param    string    The string to be escaped
  410.      * @param    boolean    Optional parameter to provide extra escaping
  411.      * @return    string 
  412.      * @access    public
  413.      * @abstract
  414.      */
  415.     function getEscaped( $text, $extra = false )
  416.     {
  417.         return;
  418.     }
  419.  
  420.     /**
  421.      * Get a database error log
  422.      *
  423.      * @access public
  424.      * @return array 
  425.      */
  426.     function getLog( )
  427.     {
  428.         return $this->_log;
  429.     }
  430.  
  431.     /**
  432.      * Get the total number of queries made
  433.      *
  434.      * @access public
  435.      * @return array 
  436.      */
  437.     function getTicker( )
  438.     {
  439.         return $this->_ticker;
  440.     }
  441.  
  442.     /**
  443.      * Quote an identifier name (field, table, etc)
  444.      *
  445.      * @access public
  446.      * @param string The name
  447.      * @return string The quoted name
  448.      */
  449.     function nameQuote( $s )
  450.     {
  451.         $q = $this->_nameQuote;
  452.         if (strlen( $q ) == 1) {
  453.             return $q . $s . $q;
  454.         } else {
  455.             return $q{0} . $s . $q{1};
  456.         }
  457.     }
  458.     /**
  459.      * Get the database table prefix
  460.      *
  461.      * @access public
  462.      * @return string The database prefix
  463.      */
  464.     function getPrefix()
  465.     {
  466.         return $this->_table_prefix;
  467.     }
  468.  
  469.     /**
  470.      * Get the database null date
  471.      *
  472.      * @access public
  473.      * @return string Quoted null/zero date string
  474.      */
  475.     function getNullDate()
  476.     {
  477.         return $this->_nullDate;
  478.     }
  479.  
  480.     /**
  481.      * Sets the SQL query string for later execution.
  482.      *
  483.      * This function replaces a string identifier <var>$prefix</var> with the
  484.      * string held is the <var>_table_prefix</var> class variable.
  485.      *
  486.      * @access public
  487.      * @param string The SQL query
  488.      * @param string The offset to start selection
  489.      * @param string The number of results to return
  490.      * @param string The common table prefix
  491.      */
  492.     function setQuery( $sql, $offset = 0, $limit = 0, $prefix='#__' )
  493.     {
  494.         $this->_sql        = $this->replacePrefix( $sql, $prefix );
  495.         $this->_limit    = (int) $limit;
  496.         $this->_offset    = (int) $offset;
  497.     }
  498.  
  499.     /**
  500.      * This function replaces a string identifier <var>$prefix</var> with the
  501.      * string held is the <var>_table_prefix</var> class variable.
  502.      *
  503.      * @access public
  504.      * @param string The SQL query
  505.      * @param string The common table prefix
  506.      */
  507.     function replacePrefix( $sql, $prefix='#__' )
  508.     {
  509.         $sql = trim( $sql );
  510.  
  511.         $escaped = false;
  512.         $quoteChar = '';
  513.  
  514.         $n = strlen( $sql );
  515.  
  516.         $startPos = 0;
  517.         $literal = '';
  518.         while ($startPos < $n) {
  519.             $ip = strpos($sql, $prefix, $startPos);
  520.             if ($ip === false) {
  521.                 break;
  522.             }
  523.  
  524.             $j = strpos( $sql, "'", $startPos );
  525.             $k = strpos( $sql, '"', $startPos );
  526.             if (($k !== FALSE) && (($k < $j) || ($j === FALSE))) {
  527.                 $quoteChar    = '"';
  528.                 $j            = $k;
  529.             } else {
  530.                 $quoteChar    = "'";
  531.             }
  532.  
  533.             if ($j === false) {
  534.                 $j = $n;
  535.             }
  536.  
  537.             $literal .= str_replace( $prefix, $this->_table_prefix,substr( $sql, $startPos, $j - $startPos ) );
  538.             $startPos = $j;
  539.  
  540.             $j = $startPos + 1;
  541.  
  542.             if ($j >= $n) {
  543.                 break;
  544.             }
  545.  
  546.             // quote comes first, find end of quote
  547.             while (TRUE) {
  548.                 $k = strpos( $sql, $quoteChar, $j );
  549.                 $escaped = false;
  550.                 if ($k === false) {
  551.                     break;
  552.