Current file: /home/greg/workspace/PHPDS-dev-trunk/PHPDevShell/stable/trunk/includes/PHPDS_query.class.php
Legend: executed not executed dead code

  Coverage
  Classes Functions / Methods Lines
Total
0.00%0.00%
0.00% 0 / 1
26.47%26.47%
26.47% 9 / 34 CRAP
39.58%39.58%
39.58% 76 / 192
 
PHPDS_query
0.00%0.00%
0.00% 0 / 1
26.47%26.47%
26.47% 9 / 34
39.58%39.58%
39.58% 76 / 192
 __construct ()
100.00%100.00%
100.00% 1 / 1 6
100.00%100.00%
100.00% 11 / 11
 connector($connector = null)
100.00%100.00%
100.00% 1 / 1 2
100.00%100.00%
100.00% 2 / 2
 invoke($parameters = null)
0.00%0.00%
0.00% 0 / 1 14.50
53.33%53.33%
53.33% 8 / 15
 query($parameters = null)
100.00%100.00%
100.00% 1 / 1 1
100.00%100.00%
100.00% 2 / 2
 querySQL($sql)
100.00%100.00%
100.00% 1 / 1 2
100.00%100.00%
100.00% 6 / 6
 queryDebug($sql)
0.00%0.00%
0.00% 0 / 1 43.18
30.77%30.77%
30.77% 4 / 13
 rows($parameters = null)
0.00%0.00%
0.00% 0 / 1 20
0.00%0.00%
0.00% 0 / 14
 sql($sql = null)
100.00%100.00%
100.00% 1 / 1 2
100.00%100.00%
100.00% 2 / 2
 build($parameters = null)
0.00%0.00%
0.00% 0 / 1 6.02
92.31%92.31%
92.31% 12 / 13
 extraBuild($parameters = null)
100.00%100.00%
100.00% 1 / 1 5
100.00%100.00%
100.00% 6 / 6
 preBuild()
0.00%0.00%
0.00% 0 / 1 25.85
27.27%27.27%
27.27% 3 / 11
 addWhere($sql, $mode = 'AND')
0.00%0.00%
0.00% 0 / 1 6
0.00%0.00%
0.00% 0 / 3
 protectArray(array $a)
0.00%0.00%
0.00% 0 / 1 30
0.00%0.00%
0.00% 0 / 13
 protectString($string)
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 2
 getKey($row = null)
0.00%0.00%
0.00% 0 / 1 42
0.00%0.00%
0.00% 0 / 8
 asWhole()
0.00%0.00%
0.00% 0 / 1 56
0.00%0.00%
0.00% 0 / 11
 typeCast($values, $key = null)
100.00%100.00%
100.00% 1 / 1 13
100.00%100.00%
100.00% 18 / 18
 getResults()
0.00%0.00%
0.00% 0 / 1 30
0.00%0.00%
0.00% 0 / 8
 asArray($field)
0.00%0.00%
0.00% 0 / 1 20
0.00%0.00%
0.00% 0 / 9
 asLine($row_number = null)
0.00%0.00%
0.00% 0 / 1 12
0.00%0.00%
0.00% 0 / 5
 asOne($row_number = null, $field = null)
0.00%0.00%
0.00% 0 / 1 30
0.00%0.00%
0.00% 0 / 6
 count()
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 1
 limit($limit)
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 2
 checkParameters(&$parameters = null)
100.00%100.00%
100.00% 1 / 1 1
100.00%100.00%
100.00% 1 / 1
 checkResults(&$results = null)
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 1
 debugInstance($domain = null)
100.00%100.00%
100.00% 1 / 1 2
100.00%100.00%
100.00% 1 / 1
 extra_build($parameters = null)
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 1
 protect_array(array $a)
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 1
 get_key($row = null)
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 1
 as_whole()
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 1
 get_results()
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 1
 as_array($field)
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 1
 as_line($row_number = null)
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 1
 as_one($row_number = null, $field = null)
0.00%0.00%
0.00% 0 / 1 2
0.00%0.00%
0.00% 0 / 1


       1                 : <?php                                                                                                                                                                                             
       2                 : /**                                                                                                                                                                                               
       3                 :  * PHPDevShell is a RAD Framework aimed at developing administrative applications.                                                                                                                
       4                 :  *                                                                                                                                                                                                
       5                 :  * @package PHPDevShell                                                                                                                                                                           
       6                 :  * @link http://www.phpdevshell.org                                                                                                                                                               
       7                 :  * @copyright Copyright (C) 2007 Jason Schoeman, All rights reserved.                                                                                                                             
       8                 :  * @license GNU/LGPL, see readme/licensed_under_lgpl or http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html                                                                                    
       9                 :  * @author Jason Schoeman, Contact: titan [at] phpdevshell [dot] org.                                                                                                                             
      10                 :  *                                                                                                                                                                                                
      11                 :  * This is an abstraction class to help you deal with SQL queries. Look at http://wiki.phpdevshell.org/wiki/Queries.                                                                              
      12                 :  *                                                                                                                                                                                                
      13                 :  * Copyright notice: See readme/notice                                                                                                                                                            
      14                 :  * By using PHPDevShell you agree to notice and license, if you dont agree to this notice/license you are not allowed to use PHPDevShell.                                                         
      15                 :  */                                                                                                                                                                                               
      16                 :                                                                                                                                                                                                   
      17                 : /**                                                                                                                                                                                               
      18                 :  * PHPDevShell official Query handler.                                                                                                                                                            
      19                 :  *                                                                                                                                                                                                
      20                 :  * @author Greg                                                                                                                                                                                   
      21                 :  */                                                                                                                                                                                               
      22                 : class PHPDS_query extends PHPDS_dependant                                                                                                                                                         
      23                 : {                                                                                                                                                                                                 
      24                 :     /**                                                                                                                                                                                           
      25                 :      * The explicit SQL query                                                                                                                                                                     
      26                 :      *                                                                                                                                                                                            
      27                 :      * This value, if present, is used when not overiden by an array in the field named "fields"                                                                                                  
      28                 :      * It can be accessed from the outside world thought the sql() method.                                                                                                                        
      29                 :      * @see $fields                                                                                                                                                                               
      30                 :      * @see sql()                                                                                                                                                                                 
      31                 :      * @var string,                                                                                                                                                                               
      32                 :      */                                                                                                                                                                                           
      33                 :     protected $sql;                                                                                                                                                                               
      34                 :                                                                                                                                                                                                   
      35                 :     /**                                                                                                                                                                                           
      36                 :      * The name of the field to use as a key.                                                                                                                                                     
      37                 :      *                                                                                                                                                                                            
      38                 :      * By default this is set to the special value '__auto__', which means the class have to figure out what's to be used.                                                                        
      39                 :      * @var string                                                                                                                                                                                
      40                 :      */                                                                                                                                                                                           
      41                 :     protected $keyField = '__auto__';                                                                                                                                                             
      42                 :                                                                                                                                                                                                   
      43                 :     /**                                                                                                                                                                                           
      44                 :      * Make a field the point of interest                                                                                                                                                         
      45                 :      *                                                                                                                                                                                            
      46                 :      * This field changes the way some arrays are returned:                                                                                                                                       
      47                 :      * - if $focus contains a field name, a row will be the value of this field (scalar) instead of an array of all values in the row                                                             
      48                 :      * - if the row doesn't contain a field an empty value is used for the row                                                                                                                    
      49                 :      * @var string                                                                                                                                                                                
      50                 :      */                                                                                                                                                                                           
      51                 :     protected $focus = ''; // can be empty for 'no' or any other value for field name                                                                                                             
      52                 :                                                                                                                                                                                                   
      53                 :     /**                                                                                                                                                                                           
      54                 :      * strips any row with no content                                                                                                                                                             
      55                 :      * @var boolean                                                                                                                                                                               
      56                 :      */                                                                                                                                                                                           
      57                 :     protected $noEmptyRow = false;                                                                                                                                                                
      58                 :                                                                                                                                                                                                   
      59                 :     /**                                                                                                                                                                                           
      60                 :      * Guidelines to typecast/forcecast the result data                                                                                                                                           
      61                 :      *                                                                                                                                                                                            
      62                 :      * @var string | array of strings                                                                                                                                                             
      63                 :      */                                                                                                                                                                                           
      64                 :     protected $typecast;                                                                                                                                                                          
      65                 :                                                                                                                                                                                                   
      66                 :     /**                                                                                                                                                                                           
      67                 :      * The first line of the result is returned instead of a one-line array                                                                                                                       
      68                 :      *                                                                                                                                                                                            
      69                 :      * @var boolean                                                                                                                                                                               
      70                 :      */                                                                                                                                                                                           
      71                 :     protected $singleRow = false;                                                                                                                                                                 
      72                 :                                                                                                                                                                                                   
      73                 :     /**                                                                                                                                                                                           
      74                 :      * Automatically escape bad chars for all in-parameters                                                                                                                                       
      75                 :      * @var boolean                                                                                                                                                                               
      76                 :      */                                                                                                                                                                                           
      77                 :     protected $autoProtect = false;                                                                                                                                                               
      78                 :                                                                                                                                                                                                   
      79                 :     /**                                                                                                                                                                                           
      80                 :      * Instead of the query result, returns the last_insert_id()                                                                                                                                  
      81                 :      * @var boolean                                                                                                                                                                               
      82                 :      */                                                                                                                                                                                           
      83                 :     protected $returnId = false;                                                                                                                                                                  
      84                 :                                                                                                                                                                                                   
      85                 :     /**                                                                                                                                                                                           
      86                 :      * Return one value from the asked field of the asked line                                                                                                                                    
      87                 :      * @var boolean                                                                                                                                                                               
      88                 :      */                                                                                                                                                                                           
      89                 :     protected $singleValue = false;                                                                                                                                                               
      90                 :                                                                                                                                                                                                   
      91                 :     /**                                                                                                                                                                                           
      92                 :      * A link between the query and the actual database server.                                                                                                                                   
      93                 :      *                                                                                                                                                                                            
      94                 :      * Don't mess up with this.                                                                                                                                                                   
      95                 :      * @var PHPDS_db_connector, the connector used to carry the query                                                                                                                             
      96                 :      */                                                                                                                                                                                           
      97                 :     private $connector;                                                                                                                                                                           
      98                 :                                                                                                                                                                                                   
      99                 :     /**                                                                                                                                                                                           
     100                 :      * The list of fields to study                                                                                                                                                                
     101                 :      *                                                                                                                                                                                            
     102                 :      * If present, this associative array contains the fields which will be present in the SELECT ... clause.                                                                                     
     103                 :      * This will override the $sql field; however if you use the sql('something') method after prebuild() the new query string will override the fields                                           
     104                 :      * @see $sql                                                                                                                                                                                  
     105                 :      * @var array (optional)                                                                                                                                                                      
     106                 :      */                                                                                                                                                                                           
     107                 :     protected $fields;                                                                                                                                                                            
     108                 :                                                                                                                                                                                                   
     109                 :     /**                                                                                                                                                                                           
     110                 :      * The WHERE clause                                                                                                                                                                           
     111                 :      *                                                                                                                                                                                            
     112                 :      * A default WHERE clause; note you can use the addWhere() method to concatenate after this value                                                                                             
     113                 :      * @var string (optional)                                                                                                                                                                     
     114                 :      */                                                                                                                                                                                           
     115                 :     protected $where;                                                                                                                                                                             
     116                 :     protected $groupby = '';                                                                                                                                                                      
     117                 :     protected $orderby = '';                                                                                                                                                                      
     118                 :     protected $limit = '';                                                                                                                                                                        
     119                 :                                                                                                                                                                                                   
     120                 :     /**                                                                                                                                                                                           
     121                 :      * In some specific case (namely debugging) this will contain a cached version of the results                                                                                                 
     122                 :      * AVOID playing with that                                                                                                                                                                    
     123                 :      * @date 20110218 (greg) added                                                                                                                                                                
     124                 :      * @var array                                                                                                                                                                                 
     125                 :      */                                                                                                                                                                                           
     126                 :     protected $cachedResult;                                                                                                                                                                      
     127                 :                                                                                                                                                                                                   
     128                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     129                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     130                 :     //////////// DEPRECATED DUE TO WRONG NAMING CONVENTION ///////////////////////                                                                                                                
     131                 :     //////////// DONT USE THESE METHODS !!!!!!!!!!!!!!!!! ////////////////////////                                                                                                                
     132                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     133                 :     /**                                                                                                                                                                                           
     134                 :      * @deprecated                                                                                                                                                                                
     135                 :      * @var boolean                                                                                                                                                                               
     136                 :      */                                                                                                                                                                                           
     137                 :     protected $single_value;                                                                                                                                                                      
     138                 :     /**                                                                                                                                                                                           
     139                 :      * @deprecated                                                                                                                                                                                
     140                 :      * @var boolean                                                                                                                                                                               
     141                 :      */                                                                                                                                                                                           
     142                 :     protected $return_id;                                                                                                                                                                         
     143                 :     /**                                                                                                                                                                                           
     144                 :      * @deprecated                                                                                                                                                                                
     145                 :      * @var boolean                                                                                                                                                                               
     146                 :      */                                                                                                                                                                                           
     147                 :     protected $auto_protect;                                                                                                                                                                      
     148                 :     /**                                                                                                                                                                                           
     149                 :      * @deprecated                                                                                                                                                                                
     150                 :      * @var boolean                                                                                                                                                                               
     151                 :      */                                                                                                                                                                                           
     152                 :     protected $single_row;                                                                                                                                                                        
     153                 :     /**                                                                                                                                                                                           
     154                 :      * @deprecated                                                                                                                                                                                
     155                 :      * @var boolean                                                                                                                                                                               
     156                 :      */                                                                                                                                                                                           
     157                 :     protected $no_empty_row;                                                                                                                                                                      
     158                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     159                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     160                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     161                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     162                 :                                                                                                                                                                                                   
     163                 :     /**                                                                                                                                                                                           
     164                 :      * Backwards compatible variables.                                                                                                                                                            
     165                 :      */                                                                                                                                                                                           
     166                 :     public function __construct ()                                                                                                                                                                
     167                 :     {                                                                                                                                                                                             
     168              57 :         if (isset($this->no_empty_row))                                                                                                                                                           
     169              57 :             $this->noEmptyRow = $this->no_empty_row;                                                                                                                                              
     170              57 :         if (isset($this->single_row))                                                                                                                                                             
     171              57 :             $this->singleRow = $this->single_row;                                                                                                                                                 
     172              57 :         if (isset($this->auto_protect))                                                                                                                                                           
     173              57 :             $this->autoProtect = $this->auto_protect;                                                                                                                                             
     174              57 :         if (isset($this->return_id))                                                                                                                                                              
     175              57 :             $this->returnId = $this->return_id;                                                                                                                                                   
     176              57 :         if (isset($this->single_value))                                                                                                                                                           
     177              57 :             $this->singleValue = $this->single_value;                                                                                                                                             
     178              57 :     }                                                                                                                                                                                             
     179                 :                                                                                                                                                                                                   
     180                 :     public function connector($connector = null)                                                                                                                                                  
     181                 :     {                                                                                                                                                                                             
     182              57 :         if (is_a($connector, 'PHPDS_dbConnector')) $this->connector = $connector;                                                                                                                 
     183              57 :         return $this->connector = $connector;                                                                                                                                                     
     184                 :     }                                                                                                                                                                                             
     185                 :                                                                                                                                                                                                   
     186                 :     /**                                                                                                                                                                                           
     187                 :      * The usual process of a query: check the parameters, send the query to the server, check the results                                                                                        
     188                 :      *                                                                                                                                                                                            
     189                 :      * Return the results as an array (for SELECT queries), true for other successfull queries, false on failure                                                                                  
     190                 :      *                                                                                                                                                                                            
     191                 :      * @version 1.1.1                                                                                                                                                                             
     192                 :      * @date 20100709 (greg) (v1.1.1) changed is_resource() to !empty() because it may return something else                                                                                      
     193                 :      * @param mixed $parameters                                                                                                                                                                   
     194                 :      * @return array or boolean                                                                                                                                                                   
     195                 :      */                                                                                                                                                                                           
     196                 :     public function invoke($parameters = null)                                                                                                                                                    
     197                 :     {                                                                                                                                                                                             
     198                 :         try {                                                                                                                                                                                     
     199              21 :             if ($this->checkParameters($parameters)) {                                                                                                                                            
     200              21 :                 $res = $this->query($parameters);                                                                                                                                                 
     201                 :                 // Fix to prevent invoke from returning false if INSERT REPLACE DELETE etc... is executed on success.                                                                             
     202               1 :                 if ($res === true && empty($this->returnId))                                                                                                                                      
     203                 :                     // Check affected rows.                                                                                                                                                       
     204               1 :                     return $this->connector->affectedRows();                                                                                                                                      
     205               0 :                 if (!empty($res)) {                                                                                                                                                               
     206               0 :                     $results = $this->getResults();                                                                                                                                               
     207               0 :                     if ($this->checkResults($results))                                                                                                                                            
     208               0 :                         return $results;                                                                                                                                                          
     209               0 :                 } else return $res;                                                                                                                                                               
     210               0 :             }                                                                                                                                                                                     
     211               0 :             return false;                                                                                                                                                                         
     212              20 :         } catch (Exception $e) {                                                                                                                                                                  
     213              20 :             $msg = '<p>The faulty query source sql is:<br /><pre class="ui-state-highlight ui-corner-all">'.$this->sql().'</pre><br />';                                                          
     214              20 :             if (!empty($parameters)) $msg .= 'The parameters were:<br /><tt>'.PU_dumpArray($parameters).'</tt></p>';                                                                              
     215              20 :             throw new PHPDS_databaseException($msg, 0, $e);                                                                                                                                       
     216                 :         }                                                                                                                                                                                         
     217                 :     }                                                                                                                                                                                             
     218                 :                                                                                                                                                                                                   
     219                 :     /**                                                                                                                                                                                           
     220                 :      * Build and send the query to the database                                                                                                                                                   
     221                 :      *                                                                                                                                                                                            
     222                 :      * @since 20100219                                                                                                                                                                            
     223                 :      * @version 1.0.3                                                                                                                                                                             
     224                 :      * @date 20110216 (greg) (v1.0.3) added a log of the sql + the class name                                                                                                                     
     225                 :      * @date 20110731 (greg) altered to use $this->querySQL                                                                                                                                       
     226                 :      * @author    greg                                                                                                                                                                            
     227                 :      * @param mixed $parameters (optional)array, the parameters to inject into the query                                                                                                          
     228                 :      * @return void                                                                                                                                                                               
     229                 :      */                                                                                                                                                                                           
     230                 :     public function query($parameters = null)                                                                                                                                                     
     231                 :     {                                                                                                                                                                                             
     232                 :                                                                                                                                                                                                   
     233              21 :         $sql = $this->build($parameters);                                                                                                                                                         
     234              21 :         return $this->querySQL($sql);                                                                                                                                                             
     235                 :     }                                                                                                                                                                                             
     236                 :                                                                                                                                                                                                   
     237                 :     /**                                                                                                                                                                                           
     238                 :      * Direclty send the query to the database                                                                                                                                                    
     239                 :      *                                                                                                                                                                                            
     240                 :      * @since 20110731                                                                                                                                                                            
     241                 :      * @version 1.0                                                                                                                                                                               
     242                 :      * @date 20110731 (greg) added based on old $this->query                                                                                                                                      
     243                 :      * @author greg                                                                                                                                                                               
     244                 :      * @param string $sql, the sql request                                                                                                                                                        
     245                 :      * @return void                                                                                                                                                                               
     246                 :      */                                                                                                                                                                                           
     247                 :     public function querySQL($sql)                                                                                                                                                                
     248                 :     {                                                                                                                                                                                             
     249                 :         try {                                                                                                                                                                                     
     250              21 :             $result = $this->connector->query($sql);                                                                                                                                              
     251                 :                                                                                                                                                                                                   
     252               1 :             $this->queryDebug($sql);                                                                                                                                                              
     253                 :                                                                                                                                                                                                   
     254               1 :             return $result;                                                                                                                                                                       
     255              20 :         } catch (Exception $e) {                                                                                                                                                                  
     256              20 :             $msg = '<p>The faulty query REAL SQL was:<br /><pre class="ui-state-highlight ui-corner-all">' . $sql . '</pre><br />';                                                               
     257              20 :             throw new PHPDS_databaseException($msg, 0, $e);                                                                                                                                       
     258                 :         }                                                                                                                                                                                         
     259                 :     }                                                                                                                                                                                             
     260                 :                                                                                                                                                                                                   
     261                 :     public function queryDebug($sql)                                                                                                                                                              
     262                 :     {                                                                                                                                                                                             
     263               1 :         $debug = $this->debugInstance();                                                                                                                                                          
     264               1 :         $firephp = $this->errorHandler->getFirePHP();                                                                                                                                             
     265               1 :         if ($debug->enable() && $firephp && !headers_sent()) {                                                                                                                                    
     266                 :                                                                                                                                                                                                   
     267                 :             $flags =                                                                                                                                                                              
     268               0 :                 ($this->singleRow ? ' singleRow' : '' ).($this->singleValue ? ' singleValue' : '' ).($this->noEmptyRow ? ' noEmptyRow ' : '' )                                                    
     269               0 :                 .(empty($this->focus) ? '' :  ' focus='.$this->focus).(empty($this->keyField) ? '' :  ' keyField='.$this->keyField).(empty($this->typeCast) ? '' :  ' typeCast='.$this->typeCast);
     270                 :                                                                                                                                                                                                   
     271               0 :             $table   = array();                                                                                                                                                                   
     272               0 :             $table[] = array('','');                                                                                                                                                              
     273               0 :             $table[] = array('SQL', $sql);                                                                                                                                                        
     274               0 :             $table[] = array('count', $this->count(). ' rows');                                                                                                                                   
     275               0 :             $table[] = array('flags', $flags);                                                                                                                                                    
     276                 :                                                                                                                                                                                                   
     277               0 :             $firephp->table('Query: '.get_class($this), $table);                                                                                                                                  
     278                 :                                                                                                                                                                                                   
     279                 :             /*$firephp->group('Query: '.get_class($this),                                                                                                                                         
     280                 :                                 array('Collapsed' => true,                                                                                                                                        
     281                 :                                             'Color' => '#64c40a'));                                                                                                                               
     282                 :                                                                                                                                                                                                   
     283                 :             $firephp->log($sql, '[ SQL ]');                                                                                                                                                       
     284                 :             $firephp->log($this->count(). ' rows', '[ count ]');                                                                                                                                  
     285                 :             $firephp->log($flags,'[ flags ]');                                                                                                                                                    
     286                 :             //$firephp->log($this->asWhole(), '[ '.$this->count(). ' rows ]');                                                                                                                    
     287                 :             $firephp->groupEnd();*/                                                                                                                                                               
     288               0 :         }                                                                                                                                                                                         
     289               1 :     }                                                                                                                                                                                             
     290                 :                                                                                                                                                                                                   
     291                 :     /**                                                                                                                                                                                           
     292                 :      * Build a query combination of columns and rows specifically designed to write rows of data to the database.                                                                                 
     293                 :      *                                                                                                                                                                                            
     294                 :      * @since 20100226                                                                                                                                                                            
     295                 :      * @since 20100226                                                                                                                                                                            
     296                 :      * @version 1.0.0                                                                                                                                                                             
     297                 :      * @param array Holds columns in the order they need to be written.                                                                                                                           
     298                 :      */                                                                                                                                                                                           
     299                 :     public function rows($parameters = null)                                                                                                                                                      
     300                 :     {                                                                                                                                                                                             
     301                 :         // Loop and build rows.                                                                                                                                                                   
     302               0 :         $r = '';                                                                                                                                                                                  
     303               0 :         $build = '';                                                                                                                                                                              
     304               0 :         foreach ($parameters as $col) {                                                                                                                                                           
     305               0 :             foreach ($col as $row) {                                                                                                                                                              
     306               0 :                 $r .= "'" . $row . "',";                                                                                                                                                          
     307               0 :             }                                                                                                                                                                                     
     308               0 :             $r = rtrim($r, ',');                                                                                                                                                                  
     309               0 :             $build .= "($r),";                                                                                                                                                                    
     310               0 :             $r = '';                                                                                                                                                                              
     311               0 :         }                                                                                                                                                                                         
     312               0 :         $parameters = rtrim($build, ',');                                                                                                                                                         
     313               0 :         if (! empty($parameters)) {                                                                                                                                                               
     314               0 :             return $parameters;                                                                                                                                                                   
     315                 :         } else {                                                                                                                                                                                  
     316               0 :             return false;                                                                                                                                                                         
     317                 :         }                                                                                                                                                                                         
     318                 :     }                                                                                                                                                                                             
     319                 :                                                                                                                                                                                                   
     320                 :     /**                                                                                                                                                                                           
     321                 :      * Get/set actual sql string.                                                                                                                                                                 
     322                 :      *                                                                                                                                                                                            
     323                 :      * You may want to override this to alter the sql string as whole, and/or build it from various sources.                                                                                      
     324                 :      * Note this is only the first part of the query (SELECT ... FROM ...), NOT including WHERE, GROUP BY, ORDER BY, LIMIT                                                                        
     325                 :      *                                                                                                                                                                                            
     326                 :      * @param string $sql (optional) if given, stored into the object's sql string                                                                                                                
     327                 :      * @return string the sql text                                                                                                                                                                
     328                 :      * @version    1.0                                                                                                                                                                            
     329                 :      * @author greg                                                                                                                                                                               
     330                 :      */                                                                                                                                                                                           
     331                 :     public function sql($sql = null)                                                                                                                                                              
     332                 :     {                                                                                                                                                                                             
     333              21 :         if (!empty($sql)) $this->sql = $sql;                                                                                                                                                      
     334              21 :         return $this->sql;                                                                                                                                                                        
     335                 :     }                                                                                                                                                                                             
     336                 :                                                                                                                                                                                                   
     337                 :     /**                                                                                                                                                                                           
     338                 :      * Build the query based on the private sql and the parameters                                                                                                                                
     339                 :      *                                                                                                                                                                                            
     340                 :      * @since 20100216                                                                                                                                                                            
     341                 :      * @since 20100428    (v1.0.1) (greg) use sql() instead of sql                                                                                                                                
     342                 :      * @date 20100630 (v1.0.2) (greg) use array_compact to avoid null values                                                                                                                      
     343                 :      * @version 1.0.2                                                                                                                                                                             
     344                 :      * @author    greg                                                                                                                                                                            
     345                 :      * @param $parameters (optional)array, the parameters to inject into the query                                                                                                                
     346                 :      * @return string, the sql query string                                                                                                                                                       
     347                 :      */                                                                                                                                                                                           
     348                 :     public function build($parameters = null)                                                                                                                                                     
     349                 :     {                                                                                                                                                                                             
     350              21 :         $sql = '';                                                                                                                                                                                
     351                 :                                                                                                                                                                                                   
     352                 :         try {                                                                                                                                                                                     
     353                 :             // Pre built.                                                                                                                                                                         
     354              21 :             $this->preBuild();                                                                                                                                                                    
     355              21 :             $sql = $this->sql() . $this->extraBuild($parameters);                                                                                                                                 
     356                 :                                                                                                                                                                                                   
     357              21 :             if (!empty($parameters)) {                                                                                                                                                            
     358              20 :                 if (is_scalar($parameters)) $parameters = array($parameters);                                                                                                                     
     359                 :                                                                                                                                                                                                   
     360              20 :                 if (is_array($parameters)) {                                                                                                                                                      
     361                 :                     // Todo: Currently breaks code as we do double protection in security.class.php.                                                                                              
     362              20 :                     if ($this->autoProtect) $parameters = $this->protectArray($parameters);                                                                                                       
     363                 :                     //$sql = vsprintf($sql, PU_array_compact($parameters));                                                                                                                       
     364              20 :                     $sql = PU_sprintfn($sql, PU_array_compact($parameters));                                                                                                                      
     365              20 :                 }                                                                                                                                                                                 
     366                 :                 //TODO is parameters is neither scalar nor array what should we do?                                                                                                               
     367              20 :             }                                                                                                                                                                                     
     368              21 :         } catch (Exception $e) {                                                                                                                                                                  
     369               0 :             throw new PHPDS_databaseException('Error building sql for <tt>' . get_class() . '</tt>', 0 ,$e);                                                                                      
     370                 :         }                                                                                                                                                                                         
     371              21 :         return $sql;                                                                                                                                                                              
     372                 :     }                                                                                                                                                                                             
     373                 :                                                                                                                                                                                                   
     374                 :     /**                                                                                                                                                                                           
     375                 :      * Construct the extra part of the query (WHERE ... GROUP BY ... ORDER BY...)                                                                                                                 
     376                 :      * Doesn't change $this->sql                                                                                                                                                                  
     377                 :      *                                                                                                                                                                                            
     378                 :      * @param array $parameters                                                                                                                                                                   
     379                 :      * @return string (sql)                                                                                                                                                                       
     380                 :      * @version    1.0                                                                                                                                                                            
     381                 :      * @author greg                                                                                                                                                                               
     382                 :      */                                                                                                                                                                                           
     383                 :     public function extraBuild($parameters = null)                                                                                                                                                
     384                 :     {                                                                                                                                                                                             
     385              21 :         $extra_sql = '';                                                                                                                                                                          
     386                 :                                                                                                                                                                                                   
     387              21 :         if (!empty($this->where)) $extra_sql .= ' WHERE '.$this->where.' ';                                                                                                                       
     388              21 :         if (!empty($this->groupby)) $extra_sql .= ' GROUP BY '.$this->groupby.' ';                                                                                                                
     389              21 :         if (!empty($this->orderby)) $extra_sql .= ' ORDER BY '.$this->orderby.' ';                                                                                                                
     390              21 :         if (!empty($this->limit)) $extra_sql .= ' LIMIT '.$this->limit.' ';                                                                                                                       
     391                 :                                                                                                                                                                                                   
     392              21 :         return $extra_sql;                                                                                                                                                                        
     393                 :     }                                                                                                                                                                                             
     394                 :                                                                                                                                                                                                   
     395                 :     /**                                                                                                                                                                                           
     396                 :      * If the fields list has been set, construct the SELECT statement (or else do nothing)                                                                                                       
     397                 :      *                                                                                                                                                                                            
     398                 :      * @version 1.0.1                                                                                                                                                                             
     399                 :      * @author greg                                                                                                                                                                               
     400                 :      * @date 20100628 (v1.0.1) (greg) the build sql string replaces the obejct's sql field, instead of being appended                                                                             
     401                 :      * @return nothing                                                                                                                                                                            
     402                 :      */                                                                                                                                                                                           
     403                 :     public function preBuild()                                                                                                                                                                    
     404                 :     {                                                                                                                                                                                             
     405              21 :         $fields = $this->fields;                                                                                                                                                                  
     406              21 :         if (!empty($fields)) {                                                                                                                                                                    
     407               0 :             $sql = '';                                                                                                                                                                            
     408               0 :             $key = $this->getKey();                                                                                                                                                               
     409               0 :             if ($key && !in_array($key, $fields)) $fields[$key] = true;                                                                                                                           
     410               0 :             foreach(array_keys($fields) as $key) if (!is_numeric($key)) $sql .= $key.', ';                                                                                                        
     411               0 :             $sql = 'SELECT '.rtrim($sql, ', ');                                                                                                                                                   
     412                 :                                                                                                                                                                                                   
     413               0 :             if (!empty($this->tables)) $sql .= ' FROM ' . $this->tables;                                                                                                                          
     414               0 :             $this->sql = $sql;                                                                                                                                                                    
     415               0 :         }                                                                                                                                                                                         
     416              21 :     }                                                                                                                                                                                             
     417                 :                                                                                                                                                                                                   
     418                 :     /**                                                                                                                                                                                           
     419                 :      * Add a subclause to the main WHERE clause of the query                                                                                                                                      
     420                 :      *                                                                                                                                                                                            
     421                 :      * @param string $sql                                                                                                                                                                         
     422                 :      * @return self                                                                                                                                                                               
     423                 :      */                                                                                                                                                                                           
     424                 :     public function addWhere($sql, $mode = 'AND')                                                                                                                                                 
     425                 :     {                                                                                                                                                                                             
     426               0 :         if (empty($this->where)) $this->where = '1';                                                                                                                                              
     427               0 :         $this->where .= " $mode $sql ";                                                                                                                                                           
     428               0 :         return $this;                                                                                                                                                                             
     429                 :     }                                                                                                                                                                                             
     430                 :                                                                                                                                                                                                   
     431                 :     /**                                                                                                                                                                                           
     432                 :      * Protect a array of strings from possible hacker (i.e. escape possible harmfull chars)                                                                                                      
     433                 :      *                                                                                                                                                                                            
     434                 :      * @since 20100216                                                                                                                                                                            
     435                 :      * @version 1.0                                                                                                                                                                               
     436                 :      * @author  greg                                                                                                                                                                              
     437                 :      * @param $a    array, the strings to protect                                                                                                                                                 
     438                 :      * @return array, the same string but safe                                                                                                                                                    
     439                 :      */                                                                                                                                                                                           
     440                 :     public function protectArray(array $a)                                                                                                                                                        
     441                 :     {                                                                                                                                                                                             
     442               0 :         foreach($a as $index => $value) {                                                                                                                                                         
     443               0 :             $v = null;                                                                                                                                                                            
     444               0 :             if (is_array($value)) {                                                                                                                                                               
     445               0 :                 $v = $this->protectArray($value);                                                                                                                                                 
     446               0 :             }                                                                                                                                                                                     
     447               0 :             if (is_scalar($value)) {                                                                                                                                                              
     448               0 :                 $v = $this->connector->protect($value);                                                                                                                                           
     449               0 :             }                                                                                                                                                                                     
     450               0 :             if (!empty($v)) {                                                                                                                                                                     
     451               0 :                 $a[$index] = $v;                                                                                                                                                                  
     452               0 :             }                                                                                                                                                                                     
     453               0 :         }                                                                                                                                                                                         
     454                 :                                                                                                                                                                                                   
     455               0 :         return $a;                                                                                                                                                                                
     456                 :     }                                                                                                                                                                                             
     457                 :                                                                                                                                                                                                   
     458                 :     /**                                                                                                                                                                                           
     459                 :      * Protect a strings from possible hacker (i.e. escape possible harmfull chars)                                                                                                               
     460                 :      *                                                                                                                                                                                            
     461                 :      * @since 20101109                                                                                                                                                                            
     462                 :      * @version 1.0                                                                                                                                                                               
     463                 :      * @author  Jason                                                                                                                                                                             
     464                 :      * @param string the strings to protect                                                                                                                                                       
     465                 :      * @return string the same string but safe                                                                                                                                                    
     466                 :      */                                                                                                                                                                                           
     467                 :     public function protectString($string)                                                                                                                                                        
     468                 :     {                                                                                                                                                                                             
     469               0 :         $clean = $this->connector->protect($string);                                                                                                                                              
     470               0 :         return $clean;                                                                                                                                                                            
     471                 :     }                                                                                                                                                                                             
     472                 :                                                                                                                                                                                                   
     473                 :     /**                                                                                                                                                                                           
     474                 :      * Try to figure out which is the key field.                                                                                                                                                  
     475                 :      *                                                                                                                                                                                            
     476                 :      * @param array $row, a sample row to study                                                                                                                                                   
     477                 :      * @return string (or null), the key field name                                                                                                                                               
     478                 :      * @version    1.0                                                                                                                                                                            
     479                 :      * @author greg                                                                                                                                                                               
     480                 :      */                                                                                                                                                                                           
     481                 :     public function getKey($row = null)                                                                                                                                                           
     482                 :     {                                                                                                                                                                                             
     483               0 :         $key = $this->keyField;                                                                                                                                                                   
     484               0 :         if (is_array($row)) {                                                                                                                                                                     
     485               0 :             if ('__auto__' == $key) {                                                                                                                                                             
     486               0 :                 $keys = array_keys($row);                                                                                                                                                         
     487               0 :                 $key = array_shift($keys);                                                                                                                                                        
     488               0 :             }                                                                                                                                                                                     
     489               0 :             return ($key && !empty($row[$key])) ? $row[$key] : null;                                                                                                                              
     490                 :         } else {                                                                                                                                                                                  
     491               0 :             return '__auto__' != $key ? $key : null;                                                                                                                                              
     492                 :         }                                                                                                                                                                                         
     493                 :     }                                                                                                                                                                                             
     494                 :                                                                                                                                                                                                   
     495                 :     /**                                                                                                                                                                                           
     496                 :      * Returns all lines from the result as a big array of arrays                                                                                                                                 
     497                 :      *                                                                                                                                                                                            
     498                 :      * @since 20100216    (v1.0) (greg)                                                                                                                                                           
     499                 :      * @since 20100428    (v1.1) (greg) use the focus parameter; use the smart key                                                                                                                
     500                 :      * @since 20100607 (v1.2) (greg) renamed compact to focus, use the noEmptyRow/single_line parameters                                                                                          
     501                 :      * @version 1.1                                                                                                                                                                               
     502                 :      * @author    greg                                                                                                                                                                            
     503                 :      * @return array, all the lines as arrays                                                                                                                                                     
     504                 :      */                                                                                                                                                                                           
     505                 :     public function asWhole()                                                                                                                                                                     
     506                 :     {                                                                                                                                                                                             
     507               0 :         $result = array();                                                                                                                                                                        
     508                 :                                                                                                                                                                                                   
     509               0 :         while ($row = $this->asLine()) {                                                                                                                                                          
     510               0 :             $key = $this->getKey($row);                                                                                                                                                           
     511               0 :             if (!empty($this->focus)) {                                                                                                                                                           
     512               0 :                 $row = (isset($row[$this->focus])) ?  $row[$this->focus] : null;                                                                                                                  
     513               0 :             }                                                                                                                                                                                     
     514               0 :             if ($row || !empty($this->noEmptyRow)) {                                                                                                                                              
     515               0 :                 if ($key) $result[$key] = $row; else $result[] = $row;                                                                                                                            
     516               0 :             }                                                                                                                                                                                     
     517               0 :         }                                                                                                                                                                                         
     518               0 :         return $result;                                                                                                                                                                           
     519                 :     }                                                                                                                                                                                             
     520                 :                                                                                                                                                                                                   
     521                 :     /**                                                                                                                                                                                           
     522                 :      *                                                                                                                                                                                            
     523                 :      * @param <type> $values                                                                                                                                                                      
     524                 :      * @param <type> $key                                                                                                                                                                         
     525                 :      * @return <type>                                                                                                                                                                             
     526                 :      */                                                                                                                                                                                           
     527                 :     public function typeCast($values, $key = null)                                                                                                                                                
     528                 :     {                                                                                                                                                                                             
     529              35 :         if (!empty($this->typecast)) {                                                                                                                                                            
     530              35 :             if (is_array($values)) {                                                                                                                                                              
     531               1 :                 foreach($values as $key => $value) $values[$key] = $this->typeCast($value, $key);                                                                                                 
     532               1 :             } else {                                                                                                                                                                              
     533              35 :                 $type = is_array($this->typecast) ? (!empty($this->typecast[$key]) ? $this->typecast[$key] : null) : $this->typecast;                                                             
     534                 :                 switch ($type) {                                                                                                                                                                  
     535              35 :                     case 'string':                                                                                                                                                                
     536               5 :                         $values = (string)$values; break;                                                                                                                                         
     537              31 :                     case 'int':                                                                                                                                                                   
     538              31 :                     case 'integer':                                                                                                                                                               
     539              11 :                         $values = (int)$values; break;                                                                                                                                            
     540              21 :                     case 'bool':                                                                                                                                                                  
     541              21 :                     case 'boolean':                                                                                                                                                               
     542              11 :                         $values = (bool)$values; break;                                                                                                                                           
     543              10 :                     case 'float':                                                                                                                                                                 
     544              10 :                     case 'double':                                                                                                                                                                
     545              10 :                         $values = (float)$values; break;                                                                                                                                          
     546                 :                     // default is to NOT change the $value                                                                                                                                        
     547                 :                 }                                                                                                                                                                                 
     548                 :                                                                                                                                                                                                   
     549                 :             }                                                                                                                                                                                     
     550              35 :         }                                                                                                                                                                                         
     551              35 :         return $values;                                                                                                                                                                           
     552                 :     }                                                                                                                                                                                             
     553                 :                                                                                                                                                                                                   
     554                 :     /**                                                                                                                                                                                           
     555                 :      * Deal with all special cases (i.e flags) regarding how results should be returned                                                                                                           
     556                 :      *                                                                                                                                                                                            
     557                 :      * The special cases handled are these (in order of precedence):                                                                                                                              
     558                 :      * - returnId (instead of the actual result, lastId is returned)                                                                                                                              
     559                 :      * - singleValue (only the first value is returned as a scalar)                                                                                                                               
     560                 :      * - singleRow (the first row is returned as a an one-dimension array)                                                                                                                        
     561                 :      *                                                                                                                                                                                            
     562                 :      * Cell-specific handling is done elsewhere                                                                                                                                                   
     563                 :      *                                                                                                                                                                                            
     564                 :      * In the absence of special case, the whole result is returned as an array of arrays (by calling as_whole() )                                                                                
     565                 :      *                                                                                                                                                                                            
     566                 :      * @version 1.1                                                                                                                                                                               
     567                 :      *                                                                                                                                                                                            
     568                 :      * @date 20100610 (greg) (v1.0) added, based on Jason's work                                                                                                                                  
     569                 :      * @date 20100617 (jason) (v1.0.1) added support for "string" setting                                                                                                                         
     570                 :      * @date 20100620 (greg) (v1.0.2) cleaned up using class methods                                                                                                                              
     571                 :      * @date 20100708 (greg) (v1.1) clean up with definitive API                                                                                                                                  
     572                 :      *                                                                                                                                                                                            
     573                 :      * @return usually an array, although can be false, or int for an ID                                                                                                                          
     574                 :      */                                                                                                                                                                                           
     575                 :     public function getResults()                                                                                                                                                                  
     576                 :     {                                                                                                                                                                                             
     577                 :         // connection ID could be returned whatever the result size                                                                                                                               
     578               0 :         if (! empty($this->returnId))                                                                                                                                                             
     579               0 :             return $this->connector->lastId();                                                                                                                                                    
     580                 :                                                                                                                                                                                                   
     581               0 :         if (!empty($this->singleValue))                                                                                                                                                           
     582               0 :             return $this->asOne();                                                                                                                                                                
     583                 :                                                                                                                                                                                                   
     584               0 :         if (!empty($this->singleRow))                                                                                                                                                             
     585               0 :             return $this->asLine();                                                                                                                                                               
     586                 :                                                                                                                                                                                                   
     587                 :         // Special case when result is actualy empty.                                                                                                                                             
     588               0 :         if ($this->count() == 0) return false;                                                                                                                                                    
     589                 :                                                                                                                                                                                                   
     590                 :         // Default return as whole.                                                                                                                                                               
     591               0 :         return  $this->asWhole();                                                                                                                                                                 
     592                 :     }                                                                                                                                                                                             
     593                 :                                                                                                                                                                                                   
     594                 :     /**                                                                                                                                                                                           
     595                 :      * Returns a single field from every line, resulting in an array of values (ie some kind of "vertical" fetching)                                                                              
     596                 :      *                                                                                                                                                                                            
     597                 :      * Note: this is different from as_whole, since only ONE value is present in each line                                                                                                        
     598                 :      *                                                                                                                                                                                            
     599                 :      * @since 20100216                                                                                                                                                                            
     600                 :      * @version 1.0                                                                                                                                                                               
     601                 :      * @author    greg                                                                                                                                                                            
     602                 :      * @param $field    string, the field to extract on each line                                                                                                                                 
     603                 :      * @return array, all the values                                                                                                                                                              
     604                 :      */                                                                                                                                                                                           
     605                 :     public function asArray($field)                                                                                                                                                               
     606                 :     {                                                                                                                                                                                             
     607               0 :         $a = array();                                                                                                                                                                             
     608                 :                                                                                                                                                                                                   
     609               0 :         while ($row = $this->connector->fetchAssoc()) {                                                                                                                                           
     610               0 :             if (!empty($row[$field])) {                                                                                                                                                           
     611               0 :                 $value = $row[$field];                                                                                                                                                            
     612                 :                                                                                                                                                                                                   
     613               0 :                 if (!empty($row[$this->keyField])) $a[$row[$this->keyField]] = $value;                                                                                                            
     614               0 :                     else $a[] = $value;                                                                                                                                                           
     615               0 :             }                                                                                                                                                                                     
     616               0 :         }                                                                                                                                                                                         
     617               0 :         return $a;                                                                                                                                                                                
     618                 :     }                                                                                                                                                                                             
     619                 :                                                                                                                                                                                                   
     620                 :     /**                                                                                                                                                                                           
     621                 :      * Returns the asked line as an array                                                                                                                                                         
     622                 :      *                                                                                                                                                                                            
     623                 :      * You can either ask for the next line (no parameter) or given a row number in the result.                                                                                                   
     624                 :      *                                                                                                                                                                                            
     625                 :      * Note: the row number is based on the result, it may not be same as the row number in the complete table                                                                                    
     626                 :      *                                                                                                                                                                                            
     627                 :      * @since 3.0                                                                                                                                                                                 
     628                 :      * @version 1.0.1                                                                                                                                                                             
     629                 :      * @author greg                                                                                                                                                                               
     630                 :      *                                                                                                                                                                                            
     631                 :      * @date 20100810 (v1.0.1) (greg) return null if the resultset is empty                                                                                                                       
     632                 :                                                                                                                                                                                                   
     633                 :      * @param integer $row_number (optional)                                                                                                                                                      
     634                 :      * @return array| null, the line or null if the resultset is empty                                                                                                                            
     635                 :      */                                                                                                                                                                                           
     636                 :     public function asLine($row_number = null)                                                                                                                                                    
     637                 :     {                                                                                                                                                                                             
     638               0 :         if ($this->count() > 0) {                                                                                                                                                                 
     639               0 :             if (is_integer($row_number)) $this->connector->seek($row_number);                                                                                                                     
     640               0 :             $row = $this->connector->fetchAssoc();                                                                                                                                                
     641                 :                                                                                                                                                                                                   
     642               0 :             return $this->typeCast($row);                                                                                                                                                         
     643                 :         }                                                                                                                                                                                         
     644               0 :     }                                                                                                                                                                                             
     645                 :                                                                                                                                                                                                   
     646                 :     /**                                                                                                                                                                                           
     647                 :      * Return one value from the asked field of the asked line                                                                                                                                    
     648                 :      *                                                                                                                                                                                            
     649                 :      * @since 3.0                                                                                                                                                                                 
     650                 :      * @version 1.0.3                                                                                                                                                                             
     651                 :      * @author greg                                                                                                                                                                               
     652                 :      *                                                                                                                                                                                            
     653                 :      * @date 20100620 (v1.0.1) (greg) made parameters optional (no "field" means first field)                                                                                                     
     654                 :      * @date 20100630 (v1.0.2) (greg) object's focus is used if "$field" parameter is empty                                                                                                       
     655                 :      * @date 20100810 (v1.0.3) (greg) return null if the resultset is empty                                                                                                                       
     656                 :      *                                                                                                                                                                                            
     657                 :      * @param integer $row_number (optional)                                                                                                                                                      
     658                 :      * @param string $field field name (optional)                                                                                                                                                 
     659                 :      * @return string | null                                                                                                                                                                      
     660                 :      */                                                                                                                                                                                           
     661                 :     public function asOne($row_number = null, $field = null)                                                                                                                                      
     662                 :     {                                                                                                                                                                                             
     663               0 :         if ($this->count() > 0) {                                                                                                                                                                 
     664               0 :             $row = $this->asLine($row_number);                                                                                                                                                    
     665               0 :             if (!empty($field)) $field = $this->focus;                                                                                                                                            
     666               0 :             if (!empty($field)) return (isset($row[$field]) ? $row[$field] : null);                                                                                                               
     667               0 :             else return array_shift($row);                                                                                                                                                        
     668                 :         }                                                                                                                                                                                         
     669               0 :     }                                                                                                                                                                                             
     670                 :                                                                                                                                                                                                   
     671                 :     /**                                                                                                                                                                                           
     672                 :      * Return the number of lines in a result                                                                                                                                                     
     673                 :      *                                                                                                                                                                                            
     674                 :      * @since 20100216                                                                                                                                                                            
     675                 :      * @version 1.0                                                                                                                                                                               
     676                 :      * @author greg                                                                                                                                                                               
     677                 :      * @return integer, the number of rows                                                                                                                                                        
     678                 :      */                                                                                                                                                                                           
     679                 :     public function count()                                                                                                                                                                       
     680                 :     {                                                                                                                                                                                             
     681               0 :         return $this->connector->numrows();                                                                                                                                                       
     682                 :     }                                                                                                                                                                                             
     683                 :                                                                                                                                                                                                   
     684                 :     /**                                                                                                                                                                                           
     685                 :      * Limits query.                                                                                                                                                                              
     686                 :      *                                                                                                                                                                                            
     687                 :      * @param int $limit                                                                                                                                                                          
     688                 :      */                                                                                                                                                                                           
     689                 :     public function limit($limit)                                                                                                                                                                 
     690                 :     {                                                                                                                                                                                             
     691                 :         // TODO: check parameter                                                                                                                                                                  
     692               0 :         $this->limit = $limit;                                                                                                                                                                    
     693               0 :     }                                                                                                                                                                                             
     694                 :                                                                                                                                                                                                   
     695                 :     /* THESE METHODS ARE MEANT TO BE OVERRIDEN */                                                                                                                                                 
     696                 :                                                                                                                                                                                                   
     697                 :     /**                                                                                                                                                                                           
     698                 :      * Allows daughter classes to check the parameters array before the query is sent                                                                                                             
     699                 :      *                                                                                                                                                                                            
     700                 :      * @param $parameters array, the unprotected parameters                                                                                                                                       
     701                 :      * @return boolean true is it's ok to sent, false otherwise                                                                                                                                   
     702                 :      */                                                                                                                                                                                           
     703                 :     public function checkParameters(&$parameters = null)                                                                                                                                          
     704                 :     {                                                                                                                                                                                             
     705               1 :         return true;                                                                                                                                                                              
     706                 :     }                                                                                                                                                                                             
     707                 :                                                                                                                                                                                                   
     708                 :     /**                                                                                                                                                                                           
     709                 :      * Allows daughter classes to check the results array before it's sent back                                                                                                                   
     710                 :      *                                                                                                                                                                                            
     711                 :      * @param $parameters array, the unprotected results                                                                                                                                          
     712                 :      * @return boolean true is it's ok to sent, false otherwise                                                                                                                                   
     713                 :      */                                                                                                                                                                                           
     714                 :     public function checkResults(&$results = null)                                                                                                                                                
     715                 :     {                                                                                                                                                                                             
     716               0 :         return true;                                                                                                                                                                              
     717                 :     }                                                                                                                                                                                             
     718                 :                                                                                                                                                                                                   
     719                 :                                                                                                                                                                                                   
     720                 :     public function debugInstance($domain = null)                                                                                                                                                 
     721                 :     {                                                                                                                                                                                             
     722               1 :         return parent::debugInstance(empty($domain) ? 'QUERY%'.get_class($this): $domain);                                                                                                        
     723                 :     }                                                                                                                                                                                             
     724                 :                                                                                                                                                                                                   
     725                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     726                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     727                 :     //////////// DEPRECATED DUE TO WRONG NAMING CONVENTION ///////////////////////                                                                                                                
     728                 :     //////////// DONT USE THESE METHODS !!!!!!!!!!!!!!!!! ////////////////////////                                                                                                                
     729                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     730                 :     /**                                                                                                                                                                                           
     731                 :      * Construct the extra part of the query (WHERE ... GROUP BY ... ORDER BY...)                                                                                                                 
     732                 :      * Doesn't change $this->sql                                                                                                                                                                  
     733                 :      *                                                                                                                                                                                            
     734                 :      * @deprecated                                                                                                                                                                                
     735                 :      * @param array $parameters                                                                                                                                                                   
     736                 :      * @return string (sql)                                                                                                                                                                       
     737                 :      * @version    1.0                                                                                                                                                                            
     738                 :      * @author greg                                                                                                                                                                               
     739                 :      */                                                                                                                                                                                           
     740                 :     public function extra_build($parameters = null)                                                                                                                                               
     741                 :     {                                                                                                                                                                                             
     742               0 :         return $this->extraBuild($parameters);                                                                                                                                                    
     743                 :     }                                                                                                                                                                                             
     744                 :                                                                                                                                                                                                   
     745                 :     /**                                                                                                                                                                                           
     746                 :      * Protect a array of strings from possible hacker (i.e. escape possible harmfull chars)                                                                                                      
     747                 :      *                                                                                                                                                                                            
     748                 :      * @deprecated                                                                                                                                                                                
     749                 :      * @since 20100216                                                                                                                                                                            
     750                 :      * @version 1.0                                                                                                                                                                               
     751                 :      * @author  greg                                                                                                                                                                              
     752                 :      * @param $a    array, the strings to protect                                                                                                                                                 
     753                 :      * @return array, the same string but safe                                                                                                                                                    
     754                 :      */                                                                                                                                                                                           
     755                 :     public function protect_array(array $a)                                                                                                                                                       
     756                 :     {                                                                                                                                                                                             
     757               0 :         return $this->protectArray($a);                                                                                                                                                           
     758                 :     }                                                                                                                                                                                             
     759                 :                                                                                                                                                                                                   
     760                 :     /**                                                                                                                                                                                           
     761                 :      * Try to figure out which is the key field.                                                                                                                                                  
     762                 :      *                                                                                                                                                                                            
     763                 :      * @deprecated                                                                                                                                                                                
     764                 :      * @param array $row, a sample row to study                                                                                                                                                   
     765                 :      * @return string (or null), the key field name                                                                                                                                               
     766                 :      * @version    1.0                                                                                                                                                                            
     767                 :      * @author greg                                                                                                                                                                               
     768                 :      */                                                                                                                                                                                           
     769                 :     public function get_key($row = null)                                                                                                                                                          
     770                 :     {                                                                                                                                                                                             
     771               0 :         return $this->getKey($row);                                                                                                                                                               
     772                 :     }                                                                                                                                                                                             
     773                 :                                                                                                                                                                                                   
     774                 :     /**                                                                                                                                                                                           
     775                 :      * Returns all lines from the result as a big array of arrays                                                                                                                                 
     776                 :      *                                                                                                                                                                                            
     777                 :      * @deprecated                                                                                                                                                                                
     778                 :      * @since 20100216    (v1.0) (greg)                                                                                                                                                           
     779                 :      * @since 20100428    (v1.1) (greg) use the focus parameter; use the smart key                                                                                                                
     780                 :      * @since 20100607 (v1.2) (greg) renamed compact to focus, use the noEmptyRow/single_line parameters                                                                                          
     781                 :      * @version 1.1                                                                                                                                                                               
     782                 :      * @author    greg                                                                                                                                                                            
     783                 :      * @return array, all the lines as arrays                                                                                                                                                     
     784                 :      */                                                                                                                                                                                           
     785                 :     public function as_whole()                                                                                                                                                                    
     786                 :     {                                                                                                                                                                                             
     787               0 :         return $this->asWhole();                                                                                                                                                                  
     788                 :     }                                                                                                                                                                                             
     789                 :                                                                                                                                                                                                   
     790                 :     /**                                                                                                                                                                                           
     791                 :      * Deal with all special cases (i.e flags) regarding how results should be returned                                                                                                           
     792                 :      *                                                                                                                                                                                            
     793                 :      * The special cases handled are these (in order of precedence):                                                                                                                              
     794                 :      * - returnId (instead of the actual result, last_id is returned)                                                                                                                             
     795                 :      * - single_value (only the first value is returned as a scalar)                                                                                                                              
     796                 :      * - singleRow (the first row is returned as a an one-dimension array)                                                                                                                        
     797                 :      *                                                                                                                                                                                            
     798                 :      * Cell-specific handling is done elsewhere                                                                                                                                                   
     799                 :      *                                                                                                                                                                                            
     800                 :      * In the absence of special case, the whole result is returned as an array of arrays (by calling as_whole() )                                                                                
     801                 :      *                                                                                                                                                                                            
     802                 :      * @deprecated                                                                                                                                                                                
     803                 :      * @version 1.1                                                                                                                                                                               
     804                 :      *                                                                                                                                                                                            
     805                 :      * @date 20100610 (greg) (v1.0) added, based on Jason's work                                                                                                                                  
     806                 :      * @date 20100617 (jason) (v1.0.1) added support for "string" setting                                                                                                                         
     807                 :      * @date 20100620 (greg) (v1.0.2) cleaned up using class methods                                                                                                                              
     808                 :      * @date 20100708 (greg) (v1.1) clean up with definitive API                                                                                                                                  
     809                 :      *                                                                                                                                                                                            
     810                 :      * @return usually an array, although can be false, or int for an ID                                                                                                                          
     811                 :      */                                                                                                                                                                                           
     812                 :     public function get_results()                                                                                                                                                                 
     813                 :     {                                                                                                                                                                                             
     814               0 :         return $this->getResults();                                                                                                                                                               
     815                 :     }                                                                                                                                                                                             
     816                 :                                                                                                                                                                                                   
     817                 :     /**                                                                                                                                                                                           
     818                 :      * Returns a single field from every line, resulting in an array of values (ie some kind of "vertical" fetching)                                                                              
     819                 :      *                                                                                                                                                                                            
     820                 :      * Note: this is different from as_whole, since only ONE value is present in each line                                                                                                        
     821                 :      *                                                                                                                                                                                            
     822                 :      * @deprecated                                                                                                                                                                                
     823                 :      * @since 20100216                                                                                                                                                                            
     824                 :      * @version 1.0                                                                                                                                                                               
     825                 :      * @author    greg                                                                                                                                                                            
     826                 :      * @param $field    string, the field to extract on each line                                                                                                                                 
     827                 :      * @return array, all the values                                                                                                                                                              
     828                 :      */                                                                                                                                                                                           
     829                 :     public function as_array($field)                                                                                                                                                              
     830                 :     {                                                                                                                                                                                             
     831               0 :         return $this->asArray($field);                                                                                                                                                            
     832                 :     }                                                                                                                                                                                             
     833                 :                                                                                                                                                                                                   
     834                 :     /**                                                                                                                                                                                           
     835                 :      * Returns the asked line as an array                                                                                                                                                         
     836                 :      *                                                                                                                                                                                            
     837                 :      * You can either ask for the next line (no parameter) or given a row number in the result.                                                                                                   
     838                 :      *                                                                                                                                                                                            
     839                 :      * Note: the row number is based on the result, it may not be same as the row number in the complete table                                                                                    
     840                 :      *                                                                                                                                                                                            
     841                 :      * @deprecated                                                                                                                                                                                
     842                 :      * @since 3.0                                                                                                                                                                                 
     843                 :      * @version 1.0.1                                                                                                                                                                             
     844                 :      * @author greg                                                                                                                                                                               
     845                 :      *                                                                                                                                                                                            
     846                 :      * @date 20100810 (v1.0.1) (greg) return null if the resultset is empty                                                                                                                       
     847                 :                                                                                                                                                                                                   
     848                 :      * @param integer $row_number (optional)                                                                                                                                                      
     849                 :      * @return array| null, the line or null if the resultset is empty                                                                                                                            
     850                 :      */                                                                                                                                                                                           
     851                 :     public function as_line($row_number = null)                                                                                                                                                   
     852                 :     {                                                                                                                                                                                             
     853               0 :         return $this->asLine($row_number);                                                                                                                                                        
     854                 :     }                                                                                                                                                                                             
     855                 :                                                                                                                                                                                                   
     856                 :     /**                                                                                                                                                                                           
     857                 :      * Return one value from the asked field of the asked line                                                                                                                                    
     858                 :      *                                                                                                                                                                                            
     859                 :      * @deprecated                                                                                                                                                                                
     860                 :      * @since 3.0                                                                                                                                                                                 
     861                 :      * @version 1.0.3                                                                                                                                                                             
     862                 :      * @author greg                                                                                                                                                                               
     863                 :      *                                                                                                                                                                                            
     864                 :      * @date 20100620 (v1.0.1) (greg) made parameters optional (no "field" means first field)                                                                                                     
     865                 :      * @date 20100630 (v1.0.2) (greg) object's focus is used if "$field" parameter is empty                                                                                                       
     866                 :      * @date 20100810 (v1.0.3) (greg) return null if the resultset is empty                                                                                                                       
     867                 :      *                                                                                                                                                                                            
     868                 :      *                                                                                                                                                                                            
     869                 :      * @param integer $row_number (optional)                                                                                                                                                      
     870                 :      * @param string $field field name (optional)                                                                                                                                                 
     871                 :      * @return string | null                                                                                                                                                                      
     872                 :      */                                                                                                                                                                                           
     873                 :     public function as_one($row_number = null, $field = null)                                                                                                                                     
     874                 :     {                                                                                                                                                                                             
     875               0 :         return $this->asOne($row_number, $field);                                                                                                                                                 
     876                 :     }                                                                                                                                                                                             
     877                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     878                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     879                 :     //////////// END DEPRECATED NAMING CONVENTIONS ///////////////////////////////                                                                                                                
     880                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     881                 :     //////////////////////////////////////////////////////////////////////////////                                                                                                                
     882                 : }                                                                                                                                                                                                 
     883                 :                                                                                                                                                                                                   
     884                 :                                                                                                                                                                                                   
     885                 :                                                                                                                                                                                                   
     886                 :                                                                                                                                                                                                   
     887                 :                                                                                                                                                                                                   

Generated by PHP_CodeCoverage 1.0.4 using PHP 5.3.6 and PHPUnit 3.5.14 at Mon Aug 8 22:35:38 PDT 2011.