Show
Ignore:
Timestamp:
05/04/06 19:52:43 (6 years ago)
Author:
haas
Message:

many fixes, documentation improvements

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • trunk/trax/vendor/trax/active_record.php

    r198 r199  
    6363 
    6464    /** 
    65      *  Reference to the object returned by PEAR DB::Connect() 
    66      * 
     65     *  Reference to the database object 
     66     * 
     67     *  Reference to the database object returned by 
     68     *  {@link http://pear.php.net/manual/en/package.database.db.db.connect.php  PEAR DB::Connect()} 
    6769     *  @var object DB 
    68      *  <b>FIXME: static should be after private</b> 
    69      */ 
    70     static private $db = null; 
     70     *  see 
     71     *  {@link http://pear.php.net/manual/en/package.database.db.php PEAR DB} 
     72     */ 
     73    private static $db = null; 
    7174 
    7275    /** 
    … …  
    135138    # Table associations 
    136139    /** 
    137      *  @todo Document this API 
     140     *  @todo Document this variable 
    138141     *  @var string[] 
    139142     */ 
    … …  
    141144 
    142145    /** 
    143      *  @todo Document this API 
     146     *  @todo Document this variable 
    144147     *  @var string[] 
    145148     */ 
    … …  
    147150 
    148151    /** 
    149      *  @todo Document this API 
     152     *  @todo Document this variable 
    150153     *  @var string[] 
    151154     */ 
    … …  
    153156 
    154157    /** 
    155      *  @todo Document this API 
     158     *  @todo Document this variable 
    156159     *  @var string[] 
    157160     */ 
    … …  
    159162 
    160163    /** 
    161      *  @todo Document this API 
     164     *  @todo Document this variable 
    162165     *  @var string[] 
    163166     */ 
    … …  
    271274 
    272275    /** 
    273      *  @todo Document this API 
     276     *  @todo Document this variable 
    274277     */ 
    275278    public $display = 10; # Pagination how many numbers in the list << < 1 2 3 4 > >> 
    … …  
    302305 
    303306    /** 
    304      *  @todo Document this API 
     307     *  @todo Document this variable 
    305308     */ 
    306309    public $auto_save_habtm = true; # auto insert / update $has_and_belongs_to_many tables 
    307310 
    308311    /** 
    309      *  @todo Document this API 
     312     *  @todo Document this variable 
    310313     */     
    311314    public $auto_delete_habtm = true; # auto delete $has_and_belongs_to_many associations 
    … …  
    359362 
    360363    /** 
    361      *  @todo Document this API 
    362364     *  Override get() if they do $model->some_association->field_name 
    363365     *  dynamically load the requested contents from the database. 
     366     *  @todo Document this API 
    364367     *  @uses $belongs_to 
    365368     *  @uses get_association_type() 
    … …  
    437440 
    438441    /** 
    439      *  @todo Document this API 
    440442     *  Override call() to dynamically call the database associations 
     443     *  @todo Document this API 
    441444     *  @uses $aggregrations 
    442445     *  @uses aggregrate_all() 
    … …  
    494497 
    495498    /** 
    496      *  @todo Document this API 
    497499     *  Returns a the name of the join table that would be used for the two 
    498500     *  tables.  The join table name is decided from the alphabetical order 
    … …  
    501503     *  Parameters: $first_table, $second_table: the names of two database tables, 
    502504     *   e.g. "movies" and "genres" 
     505     *  @todo Document this API 
    503506     */ 
    504507    private function get_join_table_name($first_table, $second_table) { 
    … …  
    511514 
    512515    /** 
    513      *  @todo Document this API 
    514516     *  Find all records using a "has_and_belongs_to_many" relationship 
    515517     * (many-to-many with a join table in between).  Note that you can also 
    … …  
    523525     *                                 many rows you are interested in.  E.g. movies 
    524526     *  Returns: An array of ActiveRecord objects. (e.g. Movie objects) 
     527     *  @todo Document this API 
    525528     */ 
    526529    private function find_all_habtm($other_table_name, $parameters = null) { 
    … …  
    572575 
    573576    /** 
    574      *  @todo Document this API 
    575577     *  Find all records using a "has_many" relationship (one-to-many) 
    576578     * 
    … …  
    578580     *                                 many rows relating to this object's id. 
    579581     *  Returns: An array of ActiveRecord objects. (e.g. Contact objects) 
     582     *  @todo Document this API 
    580583     */ 
    581584    private function find_all_has_many($other_table_name, $parameters = null) { 
    … …  
    629632 
    630633    /** 
    631      *  @todo Document this API 
    632634     *  Find all records using a "has_one" relationship (one-to-one) 
    633635     *  (the foreign key being in the other table) 
    … …  
    635637     *                                 many rows relating to this object's id. 
    636638     *  Returns: An array of ActiveRecord objects. (e.g. Contact objects) 
     639     *  @todo Document this API 
    637640     */ 
    638641    private function find_one_has_one($other_object_name, $parameters = null) { 
    … …  
    660663 
    661664    /** 
    662      *  @todo Document this API 
    663665     *  Find all records using a "belongs_to" relationship (one-to-one) 
    664666     *  (the foreign key being in the table itself) 
    … …  
    667669     *                                  Customer class, then $other_object_name 
    668670     *                                  will be "customer". 
     671     *  @todo Document this API 
    669672     */ 
    670673    private function find_one_belongs_to($other_object_name, $parameters = null) { 
    … …  
    749752 
    750753   /** 
    751     *  @todo Document this API 
    752754    *  get the attributes for a specific column. 
    753755    *  @uses $content_columns 
     756    *  @todo Document this API 
    754757    */ 
    755758    function column_for_attribute($attribute) { 
    … …  
    810813 
    811814    /** 
    812      *  @todo Document this API 
    813815     * Only used if you want to do transactions and your db supports transactions 
    814816     * 
    815817     *  @uses $db 
     818     *  @todo Document this API 
    816819     */ 
    817820    function begin() { 
    … …  
    821824 
    822825    /** 
    823      *  @todo Document this API 
    824826     *  Only used if you want to do transactions and your db supports transactions 
    825827     * 
    826828     *  @uses $db 
     829     *  @todo Document this API 
    827830     */ 
    828831    function commit() { 
    … …  
    832835 
    833836    /** 
    834      *  @todo Document this API 
    835837     *  Only used if you want to do transactions and your db supports transactions 
    836838     * 
    837839     *  @uses $db 
     840     *  @todo Document this API 
    838841     */ 
    839842    function rollback() { 
    … …  
    845848     * 
    846849     *  @param string $sql  SQL for the query command 
    847      *  @return mixed {@link http://pear.php.net/manual/en/package.database.db.db-result.php object DB_result} 
     850     *  @return DB_result {@link http://pear.php.net/manual/en/package.database.db.db-result.php} 
    848851     *    Result set from query 
    849852     *  @uses $db 
    850853     *  @uses is_error() 
     854     *  @uses log_query() 
    851855     *  @throws {@link ActiveRecordError} 
    852856     */ 
    … …  
    927931     * 
    928932     *  If no rows match, an empty array is returned. 
    929      *  @param string $conditions SQL to use in the query.  If 
     933     *  @param string SQL to use in the query.  If 
    930934     *    $conditions contains "SELECT", then $orderings, $limit and 
    931935     *    $joins are ignored and the query is completely specified by 
    … …  
    935939     *    include "WHERE $conditions".  If $conditions is null, the 
    936940     *    entire table is returned. 
    937      *  @param string $orderings Argument to "ORDER BY" in query. 
     941     *  @param string Argument to "ORDER BY" in query. 
    938942     *    If specified, the query will include 
    939943     *    "ORDER BY $orderings". If omitted, no ordering will be 
    940944     *    applied.   
    941      *  @param integer[] $limit Page, rows per page??? 
     945     *  @param integer[] Page, rows per page??? 
     946     *  @param string ??? 
    942947     *  @todo Document the $limit and $joins parameters 
    943      *  @param string $joins ??? 
    944948     *  @uses $rows_per_page_default 
    945949     *  @uses $rows_per_page 
    … …  
    955959     *  @throws {@link ActiveRecordError} 
    956960     */ 
    957     function find_all($conditions = null, $orderings = null, $limit = null, $joins = null) { 
     961    function find_all($conditions = null, $orderings = null, 
     962                      $limit = null, $joins = null) { 
     963        //error_log("find_all(".(is_null($conditions)?'null':$conditions) 
     964        //          .', ' . (is_null($orderings)?'null':$orderings) 
     965        //          .', ' . (is_null($limit)?'null':var_export($limit,true)) 
     966        //          .', ' . (is_null($joins)?'null':$joins).')'); 
     967 
     968        //  Is output to be generated in pages? 
    958969        if (is_array($limit)) { 
    959             list(self::$page, self::$rows_per_page) = $limit; 
    960             if(self::$$page <= 0) self::$page = 1; 
     970 
     971            //  Yes, get next page number and rows per page from argument 
     972            list($this->page, $this->rows_per_page) = $limit; 
     973            if($this->page <= 0) { 
     974                $this->page = 1; 
     975            } 
    961976            # Default for rows_per_page: 
    962             if (self::$rows_per_page == null) self::$rows_per_page = self::$rows_per_page_default; 
     977            if ($this->rows_per_page == null) { 
     978                $this->rows_per_page = $this->rows_per_page_default; 
     979            } 
    963980            # Set the LIMIT string segment for the SQL in the find_all 
    964             self::$offset = (self::$page - 1) * self::$rows_per_page; 
     981            $this->offset = ($this->page - 1) * $this->rows_per_page; 
    965982            # mysql 3.23 doesn't support OFFSET 
    966983            //$limit = "$rows_per_page OFFSET $offset"; 
    967             $limit = self::$offset.", ".self::$rows_per_page; 
     984            $limit = $this->offset.", ".$this->rows_per_page; 
     985 
     986            //  Remember that we're generating output in pages 
     987            //  so $limit needs to be added to the query 
    968988            $set_pages = true; 
    969989        } 
    970990 
     991        //  Test source of SQL for query 
    971992        if(stristr($conditions, "SELECT")) { 
     993 
     994            //  SQL completely specified in argument so use it as is 
    972995            $sql = $conditions; 
    973996        } else { 
     997 
     998            //  SQL will be built from specifications in argument 
    974999            $sql  = "SELECT * FROM ".$this->table_name." "; 
     1000 
     1001            //  If join specified, include it 
    9751002            if(!is_null($joins)) { 
    9761003                if(substr($joins,0,4) != "LEFT") $sql .= ","; 
    9771004                $sql .= " $joins "; 
    9781005            } 
    979             if(!is_null($conditions)) $sql .= "WHERE $conditions "; 
    980             if(!is_null($orderings)) $sql .= "ORDER BY $orderings "; 
     1006 
     1007            //  If conditions specified, include them 
     1008            if(!is_null($conditions)) { 
     1009                $sql .= "WHERE $conditions "; 
     1010            } 
     1011 
     1012            //  If ordering specified, include it 
     1013            if(!is_null($orderings)) { 
     1014                $sql .= "ORDER BY $orderings "; 
     1015            } 
     1016 
     1017            //  If limit specified, divide into pages 
    9811018            if(!is_null($limit)) { 
     1019                //  FIXME: Isn't the  second test redundant? 
    9821020                if($set_pages) { 
    983                     //echo "ActiveRecord::find_all() - sql: $sql\n<br>"; 
    984                     if(self::$is_error($rs = self::query($sql))) { 
    985                         self::raise($rs->getMessage()); 
     1021 
     1022                    //  Send query to database 
     1023                    //echo "query: $sql\n"; 
     1024                    if($this->is_error($rs = $this->query($sql))) { 
     1025 
     1026                        //  Error returned, throw error exception 
     1027                        $this->raise($rs->getMessage()); 
     1028                        //  Execution doesn't return here 
    9861029                    } else { 
    987                         # Set number of total pages in result set without the LIMIT 
     1030 
     1031                        # Set number of total pages in result set  
     1032                        # without the LIMIT   
    9881033                        if($count = $rs->numRows()) 
    989                             self::$pages = (($count % self::$rows_per_page) == 0) ? $count / self::$rows_per_page : floor($count / self::$rows_per_page) + 1; 
     1034                            $this->pages = ( 
     1035                               ($count % $this->rows_per_page) == 0) 
     1036                                ? $count / $this->rows_per_page 
     1037                                : floor($count / $this->rows_per_page) + 1; 
    9901038                    } 
    9911039                } 
    … …  
    9951043 
    9961044        //echo "ActiveRecord::find_all() - sql: $sql\n<br>"; 
    997         if(self::is_error($rs = self::query($sql))) { 
    998             self::raise($rs->getMessage()); 
     1045        //echo "query: $sql\n"; 
     1046        if($this->is_error($rs = $this->query($sql))) { 
     1047            $this->raise($rs->getMessage()); 
    9991048        } 
    10001049 
    … …  
    11101159 
    11111160    /** 
    1112      *  @todo Document this API 
    11131161     *  Reloads the attributes of this object from the database. 
    11141162     *  @uses get_primary_key_conditions() 
     1163     *  @todo Document this API 
    11151164     */ 
    11161165    function reload($conditions = null) { 
    … …  
    11561205 
    11571206    /** 
    1158      *  @todo Document this API 
    11591207     *  Finds the record from the passed id, instantly saves it with the passed attributes  
    11601208     *  (if the validation permits it). Returns true on success and false on error. 
     1209     *  @todo Document this API 
    11611210     */ 
    11621211    function update($id, $attributes, $dont_validate = false) { 
    … …  
    11721221 
    11731222    /** 
    1174      *  @todo Document this API 
    11751223     *  Updates all records with the SET-part of an SQL update statement in updates and  
    11761224     *  returns an integer with the number of rows updates. A subset of the records can  
    … …  
    11811229     *  @uses query() 
    11821230     *  @throws {@link ActiveRecordError} 
     1231     *  @todo Document this API 
    11831232     */ 
    11841233    function update_all($updates, $conditions = null) { 
    … …  
    11931242 
    11941243    /** 
    1195      *  @todo Document this API 
    11961244     *  Save without valdiating anything. 
     1245     *  @todo Document this API 
    11971246     */ 
    11981247    function save_without_validation($attributes = null) { 
    … …  
    14121461     
    14131462    /** 
    1414      *  @todo Document this API 
    14151463     *  Saves any associations objects assigned to this instance 
    14161464     *  @uses $auto_save_associations 
     1465     *  @todo Document this API 
    14171466     */ 
    14181467    private function save_associations() {       
    … …  
    14351484     
    14361485    /** 
    1437      *  @todo Document this API 
    14381486     *  save the association to the database 
     1487     *  @todo Document this API 
    14391488     */ 
    14401489    private function save_association($object, $type) { 
    … …  
    14461495                    $foreign_key = Inflector::singularize($this->table_name)."_id"; 
    14471496                    $object->$foreign_key = $this->id;  
    1448                     echo "fk:$foreign_key = $this->id<br>"; 
     1497                    //echo "fk:$foreign_key = $this->id<br>"; 
    14491498                    break; 
    14501499            } 
    … …  
    14541503 
    14551504    /** 
    1456      *  @todo Document this API 
    14571505     *  Deletes the record with the given $id or if you have done a 
    14581506     *  $model = $model->find($id), then $model->delete() it will delete 
    … …  
    14601508     *  to delete(). If an array of ids is provided, all ids in array are deleted. 
    14611509     *  @uses $errors 
     1510     *  @todo Document this API 
    14621511     */ 
    14631512    function delete($id = null) { 
    … …  
    15261575 
    15271576    /** 
    1528      *  @todo Document this API 
    1529      *  
    15301577     *  @uses $has_and_belongs_to_many 
     1578     *  @todo Document this API 
    15311579     */ 
    15321580    private function set_habtm_attributes($attributes) { 
    … …  
    15591607    /** 
    15601608     * 
    1561      *  @todo Document this API 
    15621609     *  @uses is_error() 
    15631610     *  @uses query() 
    15641611     *  @throws {@link ActiveRecordError} 
     1612     *  @todo Document this API 
    15651613     */ 
    15661614    private function add_habtm_records($this_foreign_value) { 
    … …  
    15931641 
    15941642    /** 
    1595      *  @todo Document this API 
    15961643     * 
    15971644     *  @uses is_error() 
    15981645     *  @uses query() 
    15991646     *  @throws {@link ActiveRecordError} 
     1647     *  @todo Document this API 
    16001648     */ 
    16011649    private function delete_habtm_records($this_foreign_value) { 
    … …  
    18121860                $return[$key] = $value; 
    18131861            } 
    1814             //$return[$key] = self::$db->quoteSmart($value); 
     1862            //$return[$key] = $this->$db->quoteSmart($value); 
    18151863        } 
    18161864        return $return; 
    … …  
    21672215 
    21682216    /** 
    2169      *  @todo Document this API 
    21702217     *  Overwrite this method for validation checks on all saves and 
    21712218     *  use $this->errors[] = "My error message."; or 
    21722219     *  for invalid attributes $this->errors['attribute'] = "Attribute is invalid."; 
     2220     *  @todo Document this API 
    21732221     */ 
    21742222    function validate() {} 
    21752223 
    21762224    /** 
    2177      *  @todo Document this API 
    21782225     *  Override this method for validation checks used only on creation. 
     2226     *  @todo Document this API 
    21792227     */ 
    21802228    function validate_on_create() {} 
    21812229 
    21822230    /** 
    2183      *  @todo Document this API 
    21842231     *  Override this method for validation checks used only on updates. 
     2232     *  @todo Document this API 
    21852233     */ 
    21862234    function validate_on_update() {} 
    21872235 
    21882236    /** 
    2189      *  @todo Document this API 
    21902237     *  Is called before validate(). 
     2238     *  @todo Document this API 
    21912239     */ 
    21922240    function before_validation() {} 
    21932241 
    21942242    /** 
    2195      *  @todo Document this API 
    21962243     *  Is called after validate(). 
     2244     *  @todo Document this API 
    21972245     */ 
    21982246    function after_validation() {} 
    21992247 
    22002248    /** 
    2201      *  @todo Document this API 
    22022249     *  Is called before validate() on new objects that haven't been saved yet (no record exists). 
     2250     *  @todo Document this API 
    22032251     */ 
    22042252    function before_validation_on_create() {} 
    22052253 
    22062254    /** 
    2207      *  @todo Document this API 
    22082255     *  Is called after validate() on new objects that haven't been saved yet (no record exists). 
     2256     *  @todo Document this API 
    22092257     */ 
    22102258    function after_validation_on_create()  {} 
    22112259 
    22122260    /** 
    2213      *  @todo Document this API 
    22142261     *  Is called before validate() on existing objects that has a record. 
     2262     *  @todo Document this API 
    22152263     */ 
    22162264    function before_validation_on_update() {} 
    22172265 
    22182266    /** 
    2219      *  @todo Document this API 
    22202267     *  Is called after validate() on existing objects that has a record. 
     2268     *  @todo Document this API 
    22212269     */ 
    22222270    function after_validation_on_update()  {} 
    22232271 
    22242272    /** 
    2225      *  @todo Document this API 
    22262273     *  Is called before save() (regardless of whether its a create or update save) 
     2274     *  @todo Document this API 
    22272275     */ 
    22282276    function before_save() {} 
    22292277 
    22302278    /** 
    2231      *  @todo Document this API 
    22322279     *  Is called after save (regardless of whether its a create or update save). 
     2280     *  @todo Document this API 
    22332281     */ 
    22342282    function after_save() {} 
    22352283 
    22362284    /** 
    2237      *  @todo Document this API 
    22382285     *  Is called before save() on new objects that havent been saved yet (no record exists). 
     2286     *  @todo Document this API 
    22392287     */ 
    22402288    function before_create() {} 
    22412289 
    22422290    /** 
    2243      *  @todo Document this API 
    22442291     *  Is called after save() on new objects that havent been saved yet (no record exists). 
     2292     *  @todo Document this API 
    22452293     */ 
    22462294    function after_create() {} 
    22472295 
    22482296    /** 
    2249      *  @todo Document this API 
    22502297     *  Is called before save() on existing objects that has a record. 
     2298     *  @todo Document this API 
    22512299     */ 
    22522300    function before_update() {} 
    22532301 
    22542302    /** 
    2255      *  @todo Document this API 
    22562303     *  Is called after save() on existing objects that has a record. 
     2304     *  @todo Document this API 
    22572305     */ 
    22582306    function after_update() {} 
    22592307 
    22602308    /** 
    2261      *  @todo Document this API 
    22622309     *  Is called before delete(). 
     2310     *  @todo Document this API 
    22632311     */ 
    22642312    function before_delete() {} 
    22652313 
    22662314    /** 
    2267      *  @todo Document this API 
    22682315     *  Is called after delete(). 
     2316     *  @todo Document this API 
    22692317     */ 
    22702318    function after_delete() {} 
    22712319 
     2320    /** 
     2321     *  Log SQL query in development mode 
     2322     * 
     2323     *  If running in development mode, log the query to $GLOBAL 
     2324     *  @param string SQL to be logged 
     2325     */ 
    22722326    function log_query($sql) { 
    22732327        if(TRAX_MODE == "development" && $sql) { 
    … …  
    22772331 
    22782332    /** 
    2279      *  @todo Document this API 
    22802333     * Paging html functions 
     2334     *  @todo Document this API 
    22812335     */ 
    22822336    function limit_select($controller =null, $additional_query = null) { 
    … …  
    22992353     *  @todo Document this API 
    23002354     * 
     2355     *  @return string HTML to link to previous and next pages 
     2356     *  @uses $display 
     2357     *  @uses $page 
     2358     *  @uses $pages 
     2359     *  @uses $paging_extra_params 
     2360     *  @uses rows_per_page 
    23012361     */ 
    23022362    function page_list(){