Support Joomla!

Joomla! 1.5 Documentation

Packages

Package: Joomla-Framework

Developer Network License

The Joomla! Developer Network content is © copyright 2006 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution- NonCommercial- ShareAlike 2.5
Source code for file /joomla/database/database.php

Documentation is available at database.php

  1. <?php
  2. /**
  3. * @version        $Id: database.php 4350 2006-07-28 03:34:45Z eddiea $
  4. * @package        Joomla.Framework
  5. * @subpackage    Database
  6. * @copyright    Copyright (C) 2005 - 2007 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.     /** @var string The database driver name */
  29.     var $name            = '';
  30.     /** @var string Internal variable to hold the query sql */
  31.     var $_sql            = '';
  32.     /** @var int Internal variable to hold the database error number */
  33.     var $_errorNum        = 0;
  34.     /** @var string Internal variable to hold the database error message */
  35.     var $_errorMsg        = '';
  36.     /** @var string Internal variable to hold the prefix used on all database tables */
  37.     var $_table_prefix    = '';
  38.     /** @var Internal variable to hold the connector resource */
  39.     var $_resource        = '';
  40.     /** @var Internal variable to hold the last query cursor */
  41.     var $_cursor        = null;
  42.     /** @var boolean Debug option */
  43.     var $_debug            = 0;
  44.     /** @var int The limit for the query */
  45.     var $_limit            = 0;
  46.     /** @var int The for offset for the limit */
  47.     var $_offset        = 0;
  48.     /** @var int A counter for the number of queries performed by the object instance */
  49.     var $_ticker        = 0;
  50.     /** @var array A log of queries */
  51.     var $_log            = null;
  52.     /** @var string The null/zero date string */
  53.     var $_nullDate        = null;
  54.     /** @var string Quote for named objects */
  55.     var $_nameQuote        = null;
  56.     /**
  57.      * @var boolean UTF-8 support
  58.      * @since    1.5
  59.      */
  60.     var $_utf            = 0;
  61.     /**
  62.      * @var array The fields that are to be quote
  63.      * @since    1.5
  64.      */
  65.     var $_quoted    = null;
  66.     /**
  67.      * @var bool Legacy compatibility
  68.      * @since    1.5
  69.      */
  70.     var $_hasQuoted    = null;
  71.  
  72.     /**
  73.     * Database object constructor
  74.     *
  75.     * @param string Database host
  76.     * @param string Database user name
  77.     * @param string Database user password
  78.     * @param string Database name
  79.     * @param string Common prefix for all tables
  80.     */
  81.     function __construct( $host='localhost', $user, $pass, $db='', $table_prefix='')
  82.     {
  83.         // Determine utf-8 support
  84.         $this->_utf = $this->hasUTF();
  85.  
  86.         //Set charactersets (needed for MySQL 4.1.2+)
  87.         if ($this->_utf){
  88.             $this->setUTF();
  89.         }
  90.  
  91.         $this->_table_prefix    = $table_prefix;
  92.         $this->_ticker            = 0;
  93.         $this->_errorNum        = 0;
  94.         $this->_log                = array();
  95.         $this->_quoted            = array();
  96.         $this->_hasQuoted        = false;
  97.  
  98.         // Register faked "destructor" in PHP4 to close all connections we might have made
  99.         if (version_compare(PHP_VERSION, '5') == -1) {
  100.             register_shutdown_function(array(&$this, '__destruct'));
  101.         }
  102.     }
  103.  
  104.     /**
  105.      * Returns a reference to the global Database object, only creating it
  106.      * if it doesn't already exist.
  107.      *
  108.      * @param string  Database driver
  109.      * @param string Database host
  110.      * @param string Database user name
  111.      * @param string Database user password
  112.      * @param string Database name
  113.      * @param string Common prefix for all tables
  114.      * @return JDatabase A database object
  115.      * @since 1.5
  116.     */
  117.     function &getInstance( $driver='mysql', $host='localhost', $user, $pass, $db='', $table_prefix='' )
  118.     {
  119.         static $instances;
  120.  
  121.         if (!isset( $instances )) {
  122.             $instances = array();
  123.         }
  124.  
  125.         $signature = serialize(array($driver, $host, $user, $pass, $db, $table_prefix));
  126.  
  127.         if (empty($instances[$signature])) {
  128.             jimport('joomla.database.database.'.$driver);
  129.             $adapter = 'JDatabase'.$driver;
  130.             $instances[$signature] = new $adapter($host, $user, $pass, $db, $table_prefix);
  131.         }
  132.  
  133.         return $instances[$signature];
  134.     }
  135.  
  136.     /**
  137.      * Database object destructor
  138.      *
  139.      * @abstract
  140.      * @access private
  141.      * @return boolean 
  142.      * @since 1.5
  143.      */
  144.     function __destruct()
  145.     {
  146.         return true;
  147.     }
  148.  
  149.     /**
  150.      * Determines UTF support
  151.      *
  152.      * @abstract
  153.      * @access public
  154.      * @return boolean 
  155.      * @since 1.5
  156.      */
  157.     function hasUTF() {
  158.         return false;
  159.     }
  160.  
  161.     /**
  162.      * Custom settings for UTF support
  163.      *
  164.      * @abstract
  165.      * @access public
  166.      * @since 1.5
  167.      */
  168.     function setUTF() {
  169.     }
  170.  
  171.     /**
  172.      * Adds a field or array of field names to the list that are to be quoted
  173.      *
  174.      * @access public
  175.      * @param mixed Field name or array of names
  176.      * @since 1.5
  177.      */
  178.     function addQuoted( $quoted )
  179.     {
  180.         if (is_string( $quoted )) {
  181.             $this->_quoted[] = $quoted;
  182.         } else {
  183.             $this->_quoted = array_merge( $this->_quoted, (array)$quoted );
  184.         }
  185.         $this->_hasQuoted = true;
  186.     }
  187.  
  188.     /**
  189.      * Checks if field name needs to be quoted
  190.      *
  191.      * @access public
  192.      * @param string The field name
  193.      * @return bool 
  194.      */
  195.     function isQuoted( $fieldName )
  196.     {
  197.         if ($this->_hasQuoted) {
  198.             return in_array( $fieldName, $this->_quoted );
  199.         } else {
  200.             return true;
  201.         }
  202.     }
  203.  
  204.     /**
  205.      * Sets the debug level on or off
  206.      *
  207.      * @access public
  208.      * @param int 0 = off, 1 = on
  209.      */
  210.     function debug( $level ) {
  211.         $this->_debug = intval( $level );
  212.     }
  213.  
  214.     /**
  215.      * Get the database UTF-8 support
  216.      *
  217.      * @access public
  218.      * @return boolean 
  219.      * @since 1.5
  220.      */
  221.     function getUTFSupport() {
  222.         return $this->_utf;
  223.     }
  224.  
  225.     /**
  226.      * Get the error number
  227.      *
  228.      * @access public
  229.      * @return int The error number for the most recent query
  230.      */
  231.     function getErrorNum() {
  232.         return $this->_errorNum;
  233.     }
  234.  
  235.  
  236.     /**
  237.      * Get the error message
  238.      *
  239.      * @access public
  240.      * @return string The error message for the most recent query
  241.      */
  242.     function getErrorMsg($escaped = false) {
  243.         if($escaped) {
  244.             return addslashes($this->_errorMsg);
  245.         } else {
  246.             return $this->_errorMsg;
  247.         }
  248.     }
  249.  
  250.     /**
  251.      * Get a database escaped string
  252.      *
  253.      * @abstract
  254.      * @access public
  255.      * @return string 
  256.      */
  257.     function getEscaped( $text ) {
  258.         return;
  259.     }
  260.  
  261.     /**
  262.      * Quote an identifier name (field, table, etc)
  263.      *
  264.      * @access public
  265.      * @param string The name
  266.      * @return string The quoted name
  267.      */
  268.     function nameQuote( $s )
  269.     {
  270.         $q = $this->_nameQuote;
  271.         if (strlen( $q ) == 1) {
  272.             return $q . $s . $q;
  273.         } else {
  274.             return $q{0} . $s . $q{1};
  275.         }
  276.     }
  277.     /**
  278.      * Get the database table prefix
  279.      *
  280.      * @access public
  281.      * @return string The database prefix
  282.      */
  283.     function getPrefix() {
  284.         return $this->_table_prefix;
  285.     }
  286.  
  287.     /**
  288.      * Get the database null date
  289.      *
  290.      * @access public
  291.      * @return string Quoted null/zero date string
  292.      */
  293.     function getNullDate() {
  294.         return $this->_nullDate;
  295.     }
  296.  
  297.     /**
  298.      * Sets the SQL query string for later execution.
  299.      *
  300.      * This function replaces a string identifier <var>$prefix</var> with the
  301.      * string held is the <var>_table_prefix</var> class variable.
  302.      *
  303.      * @access public
  304.      * @param string The SQL query
  305.      * @param string The offset to start selection
  306.      * @param string The number of results to return
  307.      * @param string The common table prefix
  308.      */
  309.     function setQuery( $sql, $offset = 0, $limit = 0, $prefix='#__' )
  310.     {
  311.         $this->_sql        = $this->replacePrefix( $sql, $prefix );
  312.         $this->_limit    = (int) $limit;
  313.         $this->_offset    = (int) $offset;
  314.     }
  315.  
  316.     /**
  317.      * This function replaces a string identifier <var>$prefix</var> with the
  318.      * string held is the <var>_table_prefix</var> class variable.
  319.      *
  320.      * @access public
  321.      * @param string The SQL query
  322.      * @param string The common table prefix
  323.      */
  324.     function replacePrefix( $sql, $prefix='#__' )
  325.     {
  326.         $sql = trim( $sql );
  327.  
  328.         $escaped = false;
  329.         $quoteChar = '';
  330.  
  331.         $n = strlen( $sql );
  332.  
  333.         $startPos = 0;
  334.         $literal = '';
  335.         while ($startPos < $n) {
  336.             $ip = strpos($sql, $prefix, $startPos);
  337.             if ($ip === false) {
  338.                 break;
  339.             }
  340.  
  341.             $j = strpos( $sql, "'", $startPos );
  342.             $k = strpos( $sql, '"', $startPos );
  343.             if (($k !== FALSE) && (($k < $j) || ($j === FALSE))) {
  344.                 $quoteChar    = '"';
  345.                 $j            = $k;
  346.             } else {
  347.                 $quoteChar    = "'";
  348.             }
  349.  
  350.             if ($j === false) {
  351.                 $j = $n;
  352.             }
  353.  
  354.             $literal .= str_replace( $prefix, $this->_table_prefix,substr( $sql, $startPos, $j - $startPos ) );
  355.             $startPos = $j;
  356.  
  357.             $j = $startPos + 1;
  358.  
  359.             if ($j >= $n) {
  360.                 break;
  361.             }
  362.  
  363.             // quote comes first, find end of quote
  364.             while (TRUE) {
  365.                 $k = strpos( $sql, $quoteChar, $j );
  366.                 $escaped = false;
  367.                 if ($k === false) {
  368.                     break;
  369.                 }
  370.                 $l = $k - 1;
  371.                 while ($l >= 0 && $sql{$l} == '\\') {
  372.                     $l--;
  373.                     $escaped = !$escaped;
  374.                 }
  375.                 if ($escaped) {
  376.                     $j    = $k+1;
  377.                     continue;
  378.                 }
  379.                 break;
  380.             }
  381.             if ($k === FALSE) {
  382.                 // error in the query - no end quote; ignore it
  383.                 break;
  384.             }
  385.             $literal .= substr( $sql, $startPos, $k - $startPos + 1 );
  386.             $startPos = $k+1;
  387.         }
  388.         if ($startPos < $n) {
  389.             $literal .= substr( $sql, $startPos, $n - $startPos );
  390.         }
  391.         return $literal;
  392.     }
  393.  
  394.     /**
  395.      * Get the active query
  396.      *
  397.      * @access public
  398.      * @return string The current value of the internal SQL vairable
  399.      */
  400.     function getQuery() {
  401.         return "<pre>" . htmlspecialchars( $this->_sql ) . "</pre>";
  402.     }
  403.  
  404.     /**
  405.      * Execute the query
  406.      *
  407.      * @abstract
  408.      * @access public
  409.      * @return mixed A database resource if successful, FALSE if not.
  410.      */
  411.     function query() {
  412.         return;
  413.     }
  414.  
  415.     /**
  416.      * Get the affected rows by the most recent query
  417.      *
  418.      * @abstract
  419.      * @access public
  420.      * @return int The number of affected rows in the previous operation
  421.      * @since 1.0.5
  422.      */
  423.     function getAffectedRows() {
  424.         return;
  425.     }
  426.  
  427.    /**
  428.     * Execute a batch query
  429.     *
  430.     * @abstract
  431.     * @access public
  432.     * @return mixed A database resource if successful, FALSE if not.
  433.     */
  434.     function queryBatch( $abort_on_error=true, $p_transaction_safe = false) {
  435.         return false;
  436.     }
  437.  
  438.     /**
  439.      * Diagnostic function
  440.      *
  441.      * @abstract
  442.      * @access public
  443.      */
  444.     function explain() {
  445.         return;
  446.     }
  447.  
  448.     /**
  449.      * Get the number of rows returned by the most recent query
  450.      *
  451.      * @abstract
  452.      * @access public
  453.      * @param object Database resource
  454.      * @return int The number of rows
  455.      */
  456.     function getNumRows( $cur=null ) {
  457.         return;
  458.     }
  459.  
  460.     /**
  461.      * This method loads the first field of the first row returned by the query.
  462.      *
  463.      * @abstract
  464.      * @access public
  465.      * @return The value returned in the query or null if the query failed.
  466.      */
  467.     function loadResult() {
  468.         return;
  469.     }
  470.  
  471.     /**
  472.      * Load an array of single field results into an array
  473.      *
  474.      * @abstract
  475.      */
  476.     function loadResultArray($numinarray = 0) {
  477.         return;
  478.     }
  479.  
  480.     /**
  481.     * Fetch a result row as an associative array
  482.     *
  483.     * @abstract
  484.     */
  485.     function loadAssoc() {
  486.         return;
  487.     }
  488.  
  489.     /**
  490.      * Load a associactive list of database rows
  491.      *
  492.      * @abstract
  493.      * @access public
  494.      * @param string The field name of a primary key
  495.      * @return array If key is empty as sequential list of returned records.
  496.      */
  497.     function loadAssocList( $key='' ) {
  498.         return;
  499.     }
  500.  
  501.     /**
  502.      * This global function loads the first row of a query into an object
  503.      *
  504.      *
  505.      * @abstract
  506.      * @access public
  507.      * @param object 
  508.      */
  509.     function loadObject( ) {
  510.         return;
  511.     }
  512.  
  513.     /**
  514.     * Load a list of database objects
  515.     *
  516.     * @abstract
  517.     * @access public
  518.     * @param string The field name of a primary key
  519.     * @return array If <var>key</var> is empty as sequential list of returned records.
  520.  
  521.     *  If <var>key</var> is not empty then the returned array is indexed by the value
  522.     *  the database key.  Returns <var>null</var> if the query fails.
  523.     */
  524.     function loadObjectList( $key='' ) {
  525.         return;
  526.     }
  527.  
  528.     /**
  529.      * Load the first row returned by the query
  530.      *
  531.      * @abstract
  532.      * @access public
  533.      * @return The first row of the query.
  534.      */
  535.     function loadRow() {
  536.         return;
  537.     }
  538.  
  539.     /**
  540.     * Load a list of database rows (numeric column indexing)
  541.     *
  542.     * If <var>key</var> is not empty then the returned array is indexed by the value
  543.     * the database key.  Returns <var>null</var> if the query fails.
  544.     *
  545.     * @abstract
  546.     * @access public
  547.     * @param string The field name of a primary key
  548.     * @return array 
  549.     */
  550.     function loadRowList( $key='' ) {
  551.         return;
  552.     }
  553.  
  554.     /**
  555.      * Inserts a row into a table based on an objects properties
  556.      * @param    string    The name of the table
  557.      * @param    object    An object whose properties match table fields
  558.      * @param    string    The name of the primary key. If provided the object property is updated.
  559.      */
  560.     function insertObject( $table, &$object, $keyName = NULL ) {
  561.         return;
  562.     }
  563.  
  564.     /**
  565.      * Update ab object in the database
  566.      *
  567.      * @abstract
  568.      * @access public
  569.      * @param string 
  570.      * @param object 
  571.      * @param string 
  572.      * @param boolean 
  573.      */
  574.     function updateObject( $table, &$object, $keyName, $updateNulls=true ) {
  575.         return;
  576.     }
  577.  
  578.     /**
  579.      * Print out an error statement
  580.      *
  581.      * @param boolean If TRUE, displays the last SQL statement sent to the database
  582.      * @return string A standised error message
  583.      */
  584.     function stderr( $showSQL = false ) {
  585.         if ( $this->_errorNum != 0 ) {
  586.             return "DB function failed with error number $this->_errorNum"
  587.             ."<br /><font color=\"red\">$this->_errorMsg</font>"
  588.             .($showSQL ? "<br />SQL = <pre>$this->_sql</pre>" : '');
  589.         } else {
  590.             return "DB function reports no errors";
  591.         }
  592.     }
  593.  
  594.     /**
  595.      * Get the ID generated from the previous INSERT operation
  596.      *
  597.      * @abstract
  598.      * @access public
  599.      * @return mixed 
  600.      */
  601.     function insertid() {
  602.         return;
  603.     }
  604.  
  605.     /**
  606.      * Get the database collation
  607.      *
  608.      * @abstract
  609.      * @access public
  610.      * @return string Collation in use
  611.      */
  612.     function getCollation() {
  613.         return;
  614.     }
  615.  
  616.     /**
  617.      * Get the version of the database connector
  618.      *
  619.      * @abstract
  620.      */
  621.     function getVersion() {
  622.         return 'Not available for this connector';
  623.     }
  624.  
  625.     /**
  626.      * List tables in a database
  627.      *
  628.      * @abstract
  629.      * @access public
  630.      * @return array A list of all the tables in the database
  631.      */
  632.     function getTableList() {
  633.         return;
  634.     }
  635.  
  636.     /**
  637.      *
  638.      *
  639.      * @abstract
  640.      * @access public
  641.      * @param array A list of table names
  642.      * @return array A list the create SQL for the tables
  643.      */
  644.     function getTableCreate( $tables ) {
  645.         return;
  646.     }
  647.  
  648.     /**
  649.      * List database table fields
  650.      *
  651.      * @abstract
  652.      * @access public
  653.      * @param array A list of table names
  654.      * @return array An array of fields by table
  655.      */
  656.     function getTableFields( $tables ) {
  657.         return;
  658.     }
  659.  
  660.     // ----
  661.     // ADODB Compatibility Functions
  662.     // ----
  663.  
  664.     
  665.     /**
  666.     * Get a quoted database escaped string
  667.     *
  668.     * @access public
  669.     * @return string 
  670.     */
  671.     function Quote( $text ) {
  672.         return '\'' . $this->getEscaped( $text ) . '\'';
  673.     }
  674.  
  675.     /**
  676.      * ADODB compatability function
  677.      *
  678.      * @access public
  679.      * @param string SQL
  680.      * @since 1.5
  681.      */
  682.     function GetCol( $query )
  683.     {
  684.         $this->setQuery( $query );
  685.         return $this->loadResultArray();
  686.     }
  687.  
  688.     /**
  689.      * ADODB compatability function
  690.      *
  691.      * @access public
  692.      * @param string SQL
  693.      * @return object 
  694.      * @since 1.5
  695.      */
  696.     function Execute( $query )
  697.     {
  698.         jimport( 'joomla.database.recordset' );
  699.  
  700.         $query = trim( $query );
  701.         $this->setQuery( $query );
  702.         if (eregi( '^select', $query )) {
  703.             $result = $this->loadRowList();
  704.             return new JRecordSet( $result );
  705.         } else {
  706.             $result = $this->query();
  707.             if ($result === false) {
  708.                 return false;
  709.             } else {
  710.                 return new JRecordSet( array() );
  711.             }
  712.         }
  713.     }
  714.  
  715.     /**
  716.      * ADODB compatability function
  717.      *
  718.      * @access public
  719.      * @since 1.5
  720.      */
  721.     function SelectLimit( $query, $count, $offset=0 )
  722.     {
  723.         jimport( 'joomla.database.recordset' );
  724.  
  725.         $this->setQuery( $query, $offset, $count );
  726.         $result = $this->loadRowList();
  727.         return new JRecordSet( $result );
  728.     }
  729.  
  730.     /**
  731.      * ADODB compatability function
  732.      *
  733.      * @access public
  734.      * @since 1.5
  735.      */
  736.     function PageExecute( $sql, $nrows, $page, $inputarr=false, $secs2cache=0 )
  737.     {
  738.         jimport( 'joomla.database.recordset' );
  739.  
  740.         $this->setQuery( $sql, $page*$nrows, $nrows );
  741.         $result = $this->loadRowList();
  742.         return new JRecordSet( $result );
  743.     }
  744.     /**
  745.      * ADODB compatability function
  746.      *
  747.      * @access public
  748.      * @param string SQL
  749.      * @return array 
  750.      * @since 1.5
  751.      */
  752.     function GetRow( $query )
  753.     {
  754.         $this->setQuery( $query );
  755.         $result = $this->loadRowList();
  756.         return $result[0];
  757.     }
  758.  
  759.     /**
  760.      * ADODB compatability function
  761.      *
  762.      * @access public
  763.      * @param string SQL
  764.      * @return mixed 
  765.      * @since 1.5
  766.      */
  767.     function GetOne( $query )
  768.     {
  769.         $this->setQuery( $query );
  770.         $result = $this->loadResult();
  771.         return $result;
  772.     }
  773.  
  774.     /**
  775.      * ADODB compatability function
  776.      *
  777.      * @since 1.5
  778.      */
  779.     function BeginTrans() {
  780.     }
  781.  
  782.     /**
  783.      * ADODB compatability function
  784.      *
  785.      * @since 1.5
  786.      */
  787.     function RollbackTrans() {
  788.     }
  789.  
  790.     /**
  791.      * ADODB compatability function
  792.      *
  793.      * @since 1.5
  794.      */
  795.     function CommitTrans() {
  796.     }
  797.  
  798.     /**
  799.      * ADODB compatability function
  800.      *
  801.      * @since 1.5
  802.      */
  803.     function ErrorMsg() {
  804.         return $this->getErrorMsg();
  805.     }
  806.  
  807.     /**
  808.      * ADODB compatability function
  809.      *
  810.      * @since 1.5
  811.      */
  812.     function ErrorNo() {
  813.         return $this->getErrorNum();
  814.     }
  815.  
  816.     /**
  817.      * ADODB compatability function
  818.      *
  819.      * @since 1.5
  820.      */
  821.     function GenID( $foo1=null, $foo2=null ) {
  822.         return '0';
  823.     }
  824. }
Documentation generated on Mon, 05 Mar 2007 20:56:05 +0000 by phpDocumentor 1.3.1