[Solar-svn] Revision 2996

[pmjones at solarphp.com]

Solar_Sql_Model_Record: One BC break and several new features.

* [BRK] Method save() now uses a try/catch block internally to capture
  exceptions.  Instead of throwing exception on failure, save() now returns
  boolean false on failure (and boolean true on success).  To retrieve the
  thrown exception, use the new getSaveException() method.

* [CHG] Split saving logic into two separate methods, _save() and
  _saveRelated().

* [ADD] Added new hook methods _preSaveRelated() and _postSaveRelated().

* [ADD] Method addFilter() adds filter validation and sanitizing to *just 
  this instance* of the record.  The added filters are honored after the
  model filters when you run the filter() method.




Modified: trunk/Solar/Sql/Model/Record.php
===================================================================
--- trunk/Solar/Sql/Model/Record.php	2008-03-12 13:58:29 UTC (rev 2995)
+++ trunk/Solar/Sql/Model/Record.php	2008-03-13 01:04:38 UTC (rev 2996)
@@ -104,6 +104,25 @@
     
     /**
      * 
+     * If you call save() and an exception gets thrown, this stores that
+     * exception.
+     * 
+     * @var Solar_Exception
+     * 
+     */
+    protected $_save_exception;
+    
+    /**
+     * 
+     * Filters added for this one record object.
+     * 
+     * @var array
+     * 
+     */
+    protected $_filters = array();
+    
+    /**
+     * 
      * Magic getter for record properties; automatically calls __getColName()
      * methods when they exist.
      * 
@@ -485,6 +504,7 @@
     public function save($data = null)
     {
         $this->_checkDeleted();
+        $this->_save_exception = null;
         
         // load data at save-time?
         if ($data) {
@@ -492,15 +512,27 @@
             $this->setStatus('dirty');
         }
         
+        try {
+            $this->_save();
+            $this->_saveRelated();
+            return true;
+        } catch (Exception $e) {
+            $this->_save_exception = $e;
+            return false;
+        }
+    }
+    
+    protected function _save()
+    {
         // only save if we're not clean
         if ($this->_status != 'clean') {
-            
+        
             // pre-save routine
             $this->_preSave();
-            
+        
             // turn off lazy loading
             $this->_lazy_load = false;
-            
+        
             // insert or update based on primary key value
             $primary = $this->_model->primary_col;
             if (empty($this->$primary)) {
@@ -508,30 +540,37 @@
             } else {
                 $this->_update();
             }
-            
+        
             // turn on lazy-loading for post-save routines
             $this->_lazy_load = true;
-            
+        
             // post-save routine
             $this->_postSave();
         }
+    }
+    
+    protected function _saveRelated()
+    {
+        $this->_preSaveRelated();
         
         // now save each related, but only if instantiated
         foreach ($this->_model->related as $name => $info) {
-            
+        
             // use $this->_data[$name] **instead of** $this->$name,
             // to avoid lazy-loading the related record (which in turn
             // causes infinite recursion)
             if (empty($this->_data[$name])) {
                 continue;
             }
-            
+        
             if ($this->_data[$name] instanceof Solar_Sql_Model_Record ||
                 $this->_data[$name] instanceof Solar_Sql_Model_Collection) {
                 // is a record or collection, save them
                 $this->_data[$name]->save();
             }
         }
+        
+        $this->_postSaveRelated();
     }
     
     /**
@@ -556,6 +595,14 @@
     {
     }
     
+    protected function _preSaveRelated()
+    {
+    }
+    
+    protected function _postSaveRelated()
+    {
+    }
+    
     /**
      * 
      * Inserts the current record into the database, making calls to pre- and
@@ -728,6 +775,11 @@
             $filter->addChainFilters($key, $list);
         }
         
+        // set filters added to this record
+        foreach ($this->_filters as $key => $list) {
+            $filter->addChainFilters($key, $list);
+        }
+        
         // set which elements are required by the table itself
         foreach ($this->_model->table_cols as $key => $info) {
             if ($info['autoinc']) {
@@ -933,6 +985,11 @@
         return $this->_status;
     }
     
+    public function getSaveException()
+    {
+        return $this->_save_exception;
+    }
+    
     /**
      * 
      * Throws an exception if this record status is 'deleted'.
@@ -995,4 +1052,24 @@
         
         return $form;
     }
+    
+    /**
+     * 
+     * Adds a column filter to this record instance.
+     * 
+     * @param string $col The column name to filter.
+     * 
+     * @param string $method The filter method name, e.g. 'validateUnique'.
+     * 
+     * @args Remaining arguments are passed to the filter method.
+     * 
+     * @return void
+     * 
+     */
+    public function addFilter($col, $method)
+    {
+        $args = func_get_args();
+        array_shift($args); // the first param is $col
+        $this->_filters[$col][] = $args;
+    }
 }
\ No newline at end of file