Changeset 1555

Show
Ignore:
Timestamp:
12/16/2007 03:57:33 PM (13 months ago)
Author:
zombor
Message:

More updates to database driver comments.

Location:
trunk/system/libraries/drivers
Files:
2 modified

Legend:

Unmodified
Added
Removed

  • trunk/system/libraries/drivers/Database.php

    r1522 r1555  
    1414 
    1515        /** 
    16          * Method: connect 
    17          *  Connects to the database. 
    18          * 
    19          * Returns: 
    20          *  Database link on success or FALSE on failure 
     16         * Connect to our database 
     17         * Returns FALSE on failure or a MySQL resource 
     18         * 
     19         * @return mixed 
    2120         */ 
    2221        abstract public function connect(); 
    2322 
    2423        /** 
    25          * Method: query 
    26          *  Executes a query. 
    27          * 
    28          * Parameters: 
    29          *  sql - query to execute 
    30          *  
    31          * Returns: 
    32          *  Database result object 
     24         * Perform a query based on a manually written query 
     25         * 
     26         * @param  string $sql 
     27         * @return Mysql_Result 
    3328         */ 
    3429        abstract public function query($sql); 
    3530 
    3631        /** 
    37          * Method: delete 
    38          *  Builds a DELETE query. 
    39          * 
    40          * Parameters: 
    41          *  table - table name 
    42          *  where - WHERE clause 
    43          *  
    44          * Returns: 
    45          *  A DELETE sql query string 
     32         * Builds a DELETE query. 
     33         * 
     34         * @param  string $table 
     35         * @param  array $where 
     36         * @return string 
    4637         */ 
    4738        public function delete($table, $where) 
    … …  
    5142 
    5243        /** 
    53          * Method: update 
    54          *  Builds an UPDATE query. 
    55          * 
    56          * Parameters: 
    57          *  table  - table name 
    58          *  values - associative array of values 
    59          *  where  - WHERE clause 
    60          *  
    61          * Returns: 
    62          *  An UPDATE sql query string 
     44         * Builds an UPDATE query. 
     45         * 
     46         * @param  string $table 
     47         * @param  array $values 
     48         * @param  array $where 
     49         * @return string 
    6350         */ 
    6451        public function update($table, $values, $where) 
    … …  
    7259 
    7360        /** 
    74          * Method: set_charset 
    75          *  Sets the character set for future queries. 
    76          * 
    77          * Parameters: 
    78          *  charset - character set 
     61         * Set the charset using 'SET NAMES <charset>' 
     62         * 
     63         * @param string $charset 
    7964         */ 
    8065        abstract public function set_charset($charset); 
    8166 
    8267        /** 
    83          * Method: escape_table 
    84          *  Escape the passed table name. 
    85          * 
    86          * Parameters: 
    87          *  table - table name 
    88          * 
    89          * Returns: 
    90          *  A string containing the escaped table name 
     68         * Wrap the tablename in backticks, has support for: table.field syntax. 
     69         * 
     70         * @param  string $table 
     71         * @return string 
    9172         */ 
    9273        abstract public function escape_table($table); 
    9374 
    9475        /** 
    95          * Method: escape_column 
    96          *  Escape the passed column name. 
    97          * 
    98          * Parameters: 
    99          *  column - column name 
    100          * 
    101          * Returns: 
    102          *  A string containing the escaped column name 
     76         * Escape a column/field name, has support for special commands. 
     77         * 
     78         * @param  string $column 
     79         * @return string 
    10380         */ 
    10481        abstract public function escape_column($column); 
    10582 
    10683        /** 
    107          * Method: where 
    108          *  Builds a WHERE portion of a query. 
    109          * 
    110          * Parameters: 
    111          *  key        - key name or array of key => value pairs 
    112          *  value      - value to match with key 
    113          *  type       - operator to join multiple wheres with (AND/OR) 
    114          *  num_wheres - number of existing WHERE clauses 
    115          *  quote      - disable quoting of WHERE clause 
    116          * 
    117          * Returns: 
    118          *  A WHERE portion of a query 
     84         * Builds a WHERE portion of a query. 
     85         * 
     86         * @param  mixed  $key 
     87         * @param  string $value 
     88         * @param  string $type 
     89         * @param  int    $num_wheres 
     90         * @param  bool   $quote 
     91         * @return string 
    11992         */ 
    12093        public function where($key, $value, $type, $num_wheres, $quote) 
    … …  
    166139 
    167140        /** 
    168          * Method: like 
    169          *  Builds a LIKE portion of a query. 
    170          * 
    171          * Parameters: 
    172          *  field     - field name or array of field => match pairs 
    173          *  match     - like value to match with field 
    174          *  type      - operator to join multiple likes with (AND/OR) 
    175          *  num_likes - number of existing WHERE clauses 
    176          * 
    177          * Returns: 
    178          *  A LIKE portion of a query 
     141         * Builds a LIKE portion of a query. 
     142         * 
     143         * @param  mixed  $field 
     144         * @param  string $match 
     145         * @param  string $type 
     146         * @param  int    $num_likes 
     147         * @return string 
    179148         */ 
    180149        public function like($field, $match = '', $type = 'AND ', $num_likes) 
    … …  
    190159 
    191160        /** 
    192          * Method: notlike 
    193          *  Builds a NOT LIKE portion of a query. 
    194          * 
    195          * Parameters: 
    196          *  field     - field name or array of field => match pairs 
    197          *  match     - like value to match with field 
    198          *  type      - operator to join multiple likes with (AND/OR) 
    199          *  num_likes - number of existing WHERE clauses 
    200          * 
    201          * Returns: 
    202          *  A NOT LIKE portion of a query 
     161         * Builds a NOT LIKE portion of a query. 
     162         * 
     163         * @param  mixed  $field 
     164         * @param  string $match 
     165         * @param  string $type 
     166         * @param  int    $num_likes 
     167         * @return string 
    203168         */ 
    204169        public function notlike($field, $match = '', $type = 'AND ', $num_likes) 
    … …  
    214179 
    215180        /** 
    216          * Method: regex 
    217          *  Builds a REGEXP portion of a query. 
    218          * 
    219          * Parameters: 
    220          *  field     - field name or array of field => match pairs 
    221          *  match     - like value to match with field 
    222          *  type      - operator to join multiple likes with (AND/OR) 
    223          *  num_regexs - number of existing WHERE clauses 
    224          * 
    225          * Returns: 
    226          *  A string containing the REGEXP query 
     181         * Builds a REGEX portion of a query 
     182         * 
     183         * @param  string  $field 
     184         * @param  string  $match 
     185         * @param  string  $type 
     186         * @param  integer $num_regexs 
     187         * @return string 
    227188         */ 
    228189        abstract public function regex($field, $match, $type, $num_regexs); 
    229190 
    230191        /** 
    231          * Method: notregex 
    232          *  Builds a NOT REGEXP portion of a query. 
    233          * 
    234          * Parameters: 
    235          *  field     - field name or array of field => match pairs 
    236          *  match     - like value to match with field 
    237          *  type      - operator to join multiple likes with (AND/OR) 
    238          *  num_regexs - number of existing WHERE clauses 
    239          * 
    240          * Returns: 
    241          *  A string containing the NOT REGEXP query 
     192         * Builds a NOT REGEX portion of a query 
     193         * 
     194         * @param  string  $field 
     195         * @param  string  $match 
     196         * @param  string  $type 
     197         * @param  integer $num_regexs 
     198         * @return string 
    242199         */ 
    243200        abstract public function notregex($field, $match, $type, $num_regexs); 
    244201 
    245202        /** 
    246          * Method: insert 
    247          *  Builds an INSERT query. 
    248          * 
    249          * Parameters: 
    250          *  table  - table name 
    251          *  keys   - array of keys 
    252          *  values - array of values for the keys 
    253          * 
    254          * Returns: 
    255          *  A string containing the INSERT query 
     203         * Builds an INSERT query. 
     204         * 
     205         * @param  string  $table 
     206         * @param  array   $keys 
     207         * @param  array   $values 
     208         * @return string 
    256209         */ 
    257210        public function insert($table, $keys, $values) 
    … …  
    266219 
    267220        /** 
    268          * Method: merge 
    269          *  Builds an MERGE query. 
    270          * 
    271          * Parameters: 
    272          *  table  - table name 
    273          *  keys   - array of keys 
    274          *  values - array of values for the keys 
    275          * 
    276          * Returns: 
    277          *  A string containing the MERGE query 
     221         * Builds a MERGE portion of a query. 
     222         * 
     223         * @param  string $table 
     224         * @param  array  $keys 
     225         * @param  array  $values 
     226         * @return string 
    278227         */ 
    279228        abstract public function merge($table, $keys, $values); 
    280229 
    281230        /** 
    282          * Method: limit 
    283          *  Builds a LIMIT portion of a query. 
    284          * 
    285          * Parameters: 
    286          *  limit  - number of rows to limit result to 
    287          *  offset - offset in result to start returning rows from 
    288          * 
    289          * Returns: 
    290          *  A string containing the LIMIT query 
     231         * Builds a LIMIT portion of a query. 
     232         * 
     233         * @param  integer $limit 
     234         * @param  integer $offset 
     235         * @return string 
    291236         */ 
    292237        abstract public function limit($limit, $offset = 0); 
    293238 
    294239        /** 
    295          * Method: compile_select 
    296240         *  Compiles the SELECT statement. 
    297241         *  Generates a query string based on which functions were used. 
    298242         *  Should not be called directly, the get() function calls it. 
    299243         * 
    300          * Parameters: 
    301          *  database - all the query parts set from the database library 
    302          * 
    303          * Returns: 
    304          *  A string containing the SELECT query 
     244         * @param  array  $database 
     245         * @return string 
    305246         */ 
    306247        abstract public function compile_select($database); 
    307248 
    308249        /** 
    309          * Method: has_operator 
    310          *  Determines if the string has an arithmetic operator in it. 
    311          * 
    312          * Parameters: 
    313          *  str - string to test 
    314          * 
    315          * Returns: 
    316          *  TRUE if the string has an operator in it, FALSE otherwise 
     250         * Determines if the string has an arithmetic operator in it. 
     251         * 
     252         * @param  string $str 
     253         * @return boolean 
    317254         */ 
    318255        public function has_operator($str) 
    … …  
    322259 
    323260        /** 
    324          * Method: escape 
    325          *  Escapes a value for a query. 
    326          * 
    327          * Parameters: 
    328          *  value - value to escape 
    329          * 
    330          * Returns: 
    331          *  An escaped version of the value 
     261         * Escapes any input value 
     262         * 
     263         * @param  mixed $value 
     264         * @return string 
    332265         */ 
    333266        public function escape($value) 
    … …  
    350283 
    351284        /** 
    352          * Method: escape_str 
    353          *  Escapes a string for a query. 
    354          * 
    355          * Parameters: 
    356          *  str - string to escape 
    357          * 
    358          * Returns: 
    359          *  An escaped version of the string 
     285         * Escapes a string for a query 
     286         * 
     287         * @param  mixed $str but most likely string 
     288         * @return mixed but most likely string 
    360289         */ 
    361290        abstract public function escape_str($str); 
    362291 
    363292        /** 
    364          * Method: list_tables 
    365          *  List all tables in the database. 
    366          * 
    367          * Returns: 
    368          *  An array of table names 
     293         * Lists all tables in the database 
     294         * 
     295         * @return array 
    369296         */ 
    370297        abstract public function list_tables(); 
    371298 
    372299        /** 
    373          * Method: show_error 
    374          *  Shows the last database error. 
    375          * 
    376          * Returns: 
    377          *  A string containing the error 
     300         * Returns the last database error 
     301         * 
     302         * @return string 
    378303         */ 
    379304        abstract public function show_error(); 
    380305 
    381306        /** 
    382          * Method: field_data 
    383          *  Returns field data about a table. 
    384          * 
    385          * Parameters: 
    386          *  table - table name 
    387          * 
    388          * Returns: 
    389          *  An array containing the field data or FALSE if the table doesn't exist. 
     307         * Returns field data about a table. 
     308         * 
     309         * @param  string $table 
     310         * @return array 
    390311         */ 
    391312        abstract public function field_data($table); 
    … …  
    393314        /** 
    394315         * Fetches SQL type information about a field, in a generic format. 
     316         * 
     317         * @param  string $str 
     318         * @return array 
    395319         */ 
    396320        protected function sql_type($str) 
    … …  
    449373 
    450374        /** 
    451          * Method: clear_cache 
    452          *  Clears the internal query cache 
    453          * 
    454          * Parameters: 
    455          *  sql - the sql command to clear, leave blank to clear entire cache 
     375         * Clears the internal query cache 
     376         * 
     377         * @param  string $sql 
    456378         */ 
    457379        public function clear_cache($sql = NULL) 
    … …  
    473395         * trims, and hashes. 
    474396         * 
    475          * Returns: 
    476          *  SHA1 hash 
     397         * @param  string $sql 
     398         * @return string 
    477399         */ 
    478400        protected function query_hash($sql) 
    … …  
    484406 
    485407/** 
    486  * Interface: Database_Result 
    487  *  Database Result API driver 
     408 * Database_Result 
    488409 * 
    489  * Kohana Source Code: 
    490  *  author    - Kohana Team 
    491  *  copyright - (c) 2007 Kohana Team 
    492  *  license   - <http://kohanaphp.com/license.html> 
    493410 */ 
    494411interface Database_Result { 
    495412 
    496413        /** 
    497          * Method: result 
    498          *  Prepares the query result. 
    499          * 
    500          * Parameters: 
    501          *  object - return objects or arrays 
    502          *  type   - array type to use (if using arrays) or class name (if using objects) 
    503          *  
    504          * Returns: 
    505          *  Database result object 
     414         * Prepares the query result. 
     415         * 
     416         * @param  bool  $object 
     417         * @param  mixed $type 
     418         * @return object 
    506419         */ 
    507420        public function result($object = TRUE, $type = FALSE); 
    508421 
    509422        /** 
    510          * Method: result_array 
    511          *  Builds an array of query results. 
    512          * 
    513          * Parameters: 
    514          *  object - return objects or arrays 
    515          *  type   - array type to use (if using arrays) or class name (if using objects) 
    516          *  
    517          * Returns: 
    518          *  Database result object 
     423         * Builds an array of query results. 
     424         * 
     425         * @param  bool  $object 
     426         * @param  mixed $type 
     427         * @return array 
    519428         */ 
    520429        public function result_array($object = NULL, $type = FALSE); 
    521430 
    522431        /** 
    523          * Method: insert_id 
    524          *  Gets the id of an INSERT statement. 
    525          *  
    526          * Returns: 
    527          *  The insert id number 
     432         * gets the ID of the last insert statement 
     433         * 
     434         * @return int 
    528435         */ 
    529436        public function insert_id(); 
    530437 
    531438        /** 
    532          * Method: list_fields 
    533          *  Gets the fields of an already run query 
    534          *  
    535          * Returns: 
    536          *  an array containing the fields 
     439         * Gets the fields of an already run query 
     440         * 
     441         * @return array 
    537442         */ 
    538443        public function list_fields(); 

  • trunk/system/libraries/drivers/Database_Mysql.php

    r1551 r1555  
    4949        } 
    5050 
    51         /** 
    52          * Connect to our database 
    53          * Returns FALSE on failure or a MySQL resource 
    54          * 
    55          * @return mixed 
    56          */ 
    5751        public function connect() 
    5852        { 
    … …  
    8175        } 
    8276 
    83         /** 
    84          * Perform a query based on a manually written query 
    85          * 
    86          * @param  string $sql 
    87          * @return Mysql_Result 
    88          */ 
    8977        public function query($sql) 
    9078        { 
    … …  
    10795        } 
    10896 
    109         /** 
    110          * Set the charset using 'SET NAMES <charset>' 
    111          * 
    112          * @param string $charset 
    113          */ 
    11497        public function set_charset($charset) 
    11598        { 
    … …  
    117100        } 
    118101 
    119         /** 
    120          * Wrap the tablename in backticks, has support for: table.field syntax. 
    121          * 
    122          * @param  string $table 
    123          * @return string 
    124          */ 
    125102        public function escape_table($table) 
    126103        { 
    … …  
    128105        } 
    129106 
    130         /** 
    131          * Escape a column/field name, has support for special commands. 
    132          * 
    133          * @param  string $column 
    134          * @return string 
    135          */ 
    136107        public function escape_column($column) 
    137108        { 
    … …  
    175146        } 
    176147 
    177         /** 
    178          * MySQL command 'REGEXP' 
    179          * 
    180          * @param  string  $field 
    181          * @param  string  $match 
    182          * @param  string  $type 
    183          * @param  integer $num_regexs 
    184          * @return string 
    185          */ 
    186148        public function regex($field, $match = '', $type = 'AND ', $num_regexs) 
    187149        { 
    … …  
    191153        } 
    192154 
    193         /** 
    194          * MySQL command 'NOT REGEXP' 
    195          * 
    196          * @param  string  $field 
    197          * @param  string  $match 
    198          * @param  string  $type 
    199          * @param  integer $num_regexs 
    200          * @return string 
    201          */ 
    202155        public function notregex($field, $match = '', $type = 'AND ', $num_regexs) 
    203156        { 
    … …  
    207160        } 
    208161 
    209         /** 
    210          * MySQL command 'REPLACE INTO ..' 
    211          * 
    212          * @param  string $table 
    213          * @param  array  $keys 
    214          * @param  array  $values 
    215          * @return string 
    216          */ 
    217162        public function merge($table, $keys, $values) 
    218163        { 
    … …  
    225170        } 
    226171 
    227         /** 
    228          * MySQL command 'LIMIT' 
    229          * 
    230          * @param  integer $limit 
    231          * @param  integer $offset 
    232          * @return string 
    233          */ 
    234172        public function limit($limit, $offset = 0) 
    235173        { 
    … …  
    237175        } 
    238176 
    239         /** 
    240          * Compile our select statement into a ready SQL query 
    241          * 
    242          * @param  array  $database 
    243          * @return string 
    244          */ 
    245177        public function compile_select($database) 
    246178        { 
    … …  
    293225        } 
    294226 
    295         /** 
    296          * Input escape, using mysql_real_escape_string() 
    297          * 
    298          * @param  mixed $str but most likely string 
    299          * @return mixed but most likely string 
    300          */ 
    301227        public function escape_str($str) 
    302228        { 
    … …  
    306232        } 
    307233 
    308         /** 
    309          * MySQL command 'SHOW TABLES FROM ..' 
    310          * 
    311          * @return array 
    312          */ 
    313234        public function list_tables() 
    314235        { 
    … …  
    325246        } 
    326247 
    327         /** 
    328          * Return the last error reported by mysql_error() 
    329          * 
    330          * @return string 
    331          */ 
    332248        public function show_error() 
    333249        { 
    … …  
    357273        } 
    358274 
    359         /** 
    360          * MySQL command 'SHOW COLUMNS FROM ..' 
    361          * 
    362          * @param  string $table 
    363          * @return array 
    364          */ 
    365275        public f