ManiaLib 1.0b1 API Reference

Source for file Database.php

Documentation is available at Database.php

  1. <?php
  2. /**
  3.  * MySQL abstraction layer
  4.  * 
  5.  * @see DatabaseConnection
  6.  * @author Maxime Raoust
  7.  * @copyright 2009-2010 NADEO
  8.  * @package ManiaLib
  9.  */
  10.  
  11. /**
  12.  * Database connection
  13.  * 
  14.  * Usage example:
  15.  * <code>
  16.  * <?php
  17.  * require_once(APP_FRAMEWORK_LIBRARIES_PATH.'Database.php');
  18.  * 
  19.  * try
  20.  * {
  21.  *     $database = DatabaseConnection::getInstance();
  22.  *     $result = $database->execute('SELECT * FROM mytable WHERE id < 10');
  23.  *     while($array = $result->fetchAssoc())
  24.  *     {
  25.  *         print_r($array);
  26.  *     }
  27.  *     $myvar = 'Some \'text with quotes\' and "double quotes"';
  28.  *     $myvarQuoted = $database->quote($myvar);
  29.  *     $database->execute( 'INSERT INTO mytable (MyText) VALUES ('.$myvarQuoted.')' );
  30.  *     echo $database->insertID.' is a newly inserted ID';
  31.  * }
  32.  * catch(Exception $e)
  33.  * {
  34.  *     // Error handling...
  35.  * }
  36.  * ?>
  37.  * </code>
  38.  * 
  39.  * @package ManiaLib
  40.  * @subpackage Database
  41.  */
  42. class DatabaseConnection
  43. {
  44.     /**
  45.      * @ignore
  46.      */
  47.     static protected $instance;
  48.     /**#@+
  49.      * @ignore
  50.      */
  51.     protected $connection;
  52.     protected $host;
  53.     protected $user;
  54.     protected $password;
  55.     protected $database;
  56.     protected $charset;
  57.     /**#@-*/
  58.     
  59.     /**
  60.      * Get an instance on the database connection object, and connects to the mysql server if needed
  61.      * To configure your connection, override these constants in your config:
  62.      * <ul>
  63.      * <li>APP_DATABASE_HOST</li>
  64.      * <li>APP_DATABASE_USER</li>
  65.      * <li>APP_DATABASE_PASSWORD</li>
  66.      * <li>APP_DATABASE_NAME</li>
  67.      * <li>APP_DATABASE_CHARSET</li>
  68.      * </ul>
  69.      * 
  70.      * @return DatabaseConnection 
  71.      */
  72.     public static function getInstance()
  73.     {
  74.         if (!self::$instance)
  75.         {
  76.             self::$instance = new self();
  77.         }
  78.         return self::$instance;
  79.     }
  80.     
  81.     /**
  82.      * @throws DatabaseConnectionException
  83.      * @ignore
  84.      */
  85.     protected function __construct()
  86.     {
  87.         $this->host = APP_DATABASE_HOST;
  88.         $this->user = APP_DATABASE_USER;
  89.         $this->password = APP_DATABASE_PASSWORD;
  90.         
  91.         $this->connection = mysql_connect($this->host, $this->user, $this->password);
  92.                 
  93.         if(!$this->connection)
  94.         {
  95.             throw new DatabaseConnectionException();
  96.         }
  97.  
  98.         $this->select(APP_DATABASE_NAME);    
  99.         $this->setCharset(APP_DATABASE_CHARSET);
  100.     }
  101.     
  102.     /**
  103.      * Sets the charset for the database connection
  104.      */
  105.     function setCharset($charset)
  106.     {
  107.         if($charset != $this->charset)
  108.         {
  109.             $this->charset = $charset;
  110.             if(!mysql_set_charset($charset, $this->connection))
  111.             {
  112.                 throw new DatabaseException('Couldn\'t set charset: '.$charset);
  113.             }
  114.         }
  115.     }
  116.     
  117.     /**
  118.      * Selects a database
  119.      */
  120.     function select($database)
  121.     {
  122.         if($database != $this->database)
  123.         {
  124.             $this->database = $database;
  125.             if(!mysql_select_db($this->database, $this->connection))
  126.             {
  127.                 throw new DatabaseSelectionException(mysql_error(), mysql_errno());
  128.             }
  129.         }
  130.     }
  131.  
  132.     /**
  133.      * Escape and quote variables so you can insert them safely
  134.      */
  135.     function quote($string)
  136.     {
  137.         return '\''.mysql_real_escape_string($string, $this->connection).'\'';
  138.     }
  139.     
  140.     /**
  141.      * Executes a query
  142.      * @param string The query
  143.      * @return DatabaseRecordSet 
  144.      */
  145.     function execute($query)
  146.     {
  147.         $result = mysql_query($query, $this->connection);
  148.         if(!$result)
  149.         {
  150.             throw new DatabaseQueryException(mysql_error(), mysql_errno());
  151.         }
  152.         return new DatabaseRecordSet($result);
  153.     }
  154.     
  155.     /**
  156.      * Get number of affected rows in previous operation
  157.      * @return int 
  158.      */
  159.     function affectedRows()
  160.     {
  161.         return mysql_affected_rows($this->connection);
  162.     }
  163.     
  164.     /**
  165.      * Get the ID generated in the last query
  166.      * @return int 
  167.      */
  168.     function insertID()
  169.     {
  170.         return mysql_insert_id($this->connection);
  171.     }
  172.     
  173.     /**
  174.      * @return bool 
  175.      */
  176.     function isConnected()
  177.     {
  178.         return (!$this->connection); 
  179.     }
  180.  
  181.     /**
  182.      * Currently selected database
  183.      * @return string 
  184.      */
  185.     function getDatabase()
  186.     {
  187.         return $this->database;
  188.     }
  189. }
  190.  
  191. /**
  192.  * Database query result
  193.  * @see DatabaseConnection
  194.  * @package ManiaLib
  195.  * @subpackage Database
  196.  */
  197. class DatabaseRecordSet
  198. {
  199.     /**#@+
  200.      * Constants to use with DatabaseRecordSet::fetchArray()
  201.      */
  202.     const FETCH_ASSOC = MYSQL_ASSOC;
  203.     const FETCH_NUM = MYSQL_NUM;
  204.     const FETCH_BOTH = MYSQL_BOTH;
  205.     /**#@-*/
  206.  
  207.     /**
  208.      * MySQL ressource
  209.      * @ignore
  210.      */
  211.     protected $result;
  212.     
  213.     /**
  214.      * @ignore
  215.      */
  216.     function __construct($result)
  217.     {
  218.         $this->result = $result;
  219.     }
  220.     
  221.     /**
  222.      * Get a result row as an enumerated array
  223.      * @return array 
  224.      */
  225.     function fetchRow()
  226.     {
  227.         return mysql_fetch_row($this->result);
  228.     }
  229.     
  230.     /**
  231.      * Fetch a result row as an associative array
  232.      * @return array 
  233.      */
  234.     function fetchAssoc()
  235.     {
  236.         return mysql_fetch_assoc($this->result);
  237.     }
  238.     
  239.     /**
  240.      * Fetch a result row as an associative, a numeric array, or both
  241.      * @return array 
  242.      */    
  243.     function fetchArray($resultType = self::FETCH_ASSOC)
  244.     {
  245.         return mysql_fetch_array($this->result, $resultType);
  246.     }
  247.     
  248.     /**
  249.      * Returns the current row of a result set as an object
  250.      * @param string The name of the class to instantiate, set the properties of and return. If not specified, a stdClass object is returned.
  251.      * @param array An optional array of parameters to pass to the constructor for class_name objects.
  252.      * @return object 
  253.      */    
  254.     function fetchObject($className, array $params = array())
  255.     {
  256.         if($className)
  257.         {
  258.             return mysql_fetch_object($this->result, $className, $params);
  259.         }    
  260.         else
  261.         {
  262.             return mysql_fetch_object($this->result);
  263.         }
  264.     }
  265.     
  266.     /**
  267.      * Gets the number of rows in a result
  268.      * @return int 
  269.      */
  270.     function recordCount()
  271.     {
  272.         return mysql_num_rows($this->result);
  273.     }
  274. }
  275.  
  276. /**
  277.  * Misc database tools
  278.  * @see DatabaseConnection
  279.  * @package ManiaLib
  280.  * @subpackage Database
  281.  */
  282. abstract class DatabaseTools
  283. {
  284.     /**
  285.      * Returns the "LIMIT x,x" string depending on both values
  286.      */
  287.     static function getLimitString($offset, $length)
  288.     {
  289.         if(!$offset && !$length)
  290.         {
  291.             return '';
  292.         }
  293.         elseif(!$offset && $length==1)
  294.         {
  295.             return 'LIMIT 1';
  296.         }
  297.         else
  298.         {
  299.             return 'LIMIT '.$offset.', '.$length;
  300.         }
  301.     }
  302.     
  303.     /**
  304.      * Returns string like "(name1, name2) VALUES (value1, value2)"
  305.      */
  306.     static function getValuesString(array $values)
  307.     {
  308.         return 
  309.             '('.implode(', ', array_keys($values)).') '.
  310.             'VALUES '.
  311.             '('.implode(', ', $values).')';
  312.     }
  313.     
  314.     /**
  315.      * Returns string like "name1=VALUES(name1), name2=VALUES(name2)"
  316.      */
  317.     static function getOnDuplicateKeyUpdateValuesString(array $valueNames)
  318.     {
  319.         $strings = array(); 
  320.         foreach($valueNames as $valueName)
  321.         {
  322.             $strings[] = $valueName.'=VALUES('.$valueName.')';
  323.         }
  324.         return implode(', ', $strings);
  325.     }
  326. }
  327.  
  328. /**
  329.  * @package ManiaLib
  330.  * @subpackage Database
  331.  * @ignore
  332.  */
  333. class DatabaseException extends Exception {}
  334.  
  335. /**
  336.  * @package ManiaLib
  337.  * @subpackage Database
  338.  * @ignore
  339.  */
  340. class DatabaseConnectionException extends DatabaseException {}
  341.  
  342. /**
  343.  * @package ManiaLib
  344.  * @subpackage Database
  345.  * @ignore
  346.  */
  347. class DatabaseSelectionException extends DatabaseException {}
  348.  
  349. /**
  350.  * @package ManiaLib
  351.  * @subpackage Database
  352.  * @ignore
  353.  */
  354. class DatabaseQueryException extends DatabaseException {}
  355.  
  356. ?>