Gumbo_Record





	
Generic Record Class
	
The Record Class represents a single database record from a table.  The methods  will provide access to the data of the record.  If the class contains a  database record, the values will be read only.  In order to change records,  the class must be extended.
Once the Record is loaded, the program will be able to access the internals of  the class.  This can be accomplished by calling the get method with the column  name or using the overloaded __get method.
In order to manipulate database records, the Gumbo_Record class must be extended.  The class will represent a database table.  The child class must define the table  structure to the Gumbo_Record parent.  It should also define get and set methods  for each column.  A 'getColumnName' method will return the value.  A 'setColumnName'  method will set the value, forcing the data to be validated and filtered as  necessary.  The only way to modify Gumbo_Records is through a child class.
Implementation for a get method:  
 public function get[Column] () {
 		return $this->get ("column_name");
Implementation for a set method:  
 public function setColumn ($val) {
 		// perform validation/filtering, throw necessary Exceptions
 		// do not set value if validation fails
 		...
 		$this->set ("column_name", $val);
 }
The Gumbo_Record class contains some very advanced features for accessing database  information.  These features are not necessary, but are very useful.  The first  step is to pass the value to the parent Constructor.  
 public function __construct ($id=null) {
 		parent::__construct ($id);
 		...
 }
The argument can be an integer or an array.  If an integer is passed, it will be  used as the primary key column value to run a single SELECT statement against the  database.  If an array is passed, it should be an associative array returned from  a database query.  The keys in the array are the column names. (ie. mysql_fetch_assoc ()).  This feature is useful when returning multiple rows of data, passing the associative  array into the Gumbo_Record object.  If returning multiple records, this feature will  avoid having to run a single query for each Gumbo_Record.
The child Record should instantiate a Prototype.  This will pass important setup information  about the child Class and the Database Table it represents.  The Prototype will define  the Table Name, the Primary Key, Table Columns, and more (see Gumbo_Abstract_Prototype).  The best implementation of this feature is to create a single Prototype object  during the programs lifetime.  This can be accomplished by defining the Prototype  as a Singleton, or setting a static prototype property inside the child  Record.  The child Record will then initialize the Prototype, passing the object to  the parent 'init' method.  (The implementation is if a Prototype is not a Singleton.  Make the appropriate substitution to retrieve a Prototype object for Singletons)  
 // Singleton
 class User_Prototype extends Gumbo_Record_Prototype implements Gumbo_Interface_Singleton {
 	...
 }

 // static property in Record
 class User extends Gumbo_Record {
 	private static $_prototype;

 	public function __construct ($id=null) {
 		...
 		if (User::$_prototype == null) {
 			User::$_prototype = new User_Prototype ();
 		}
 		$this->init (User::$_prototype);

 		$this->load (); // populates the Record
 	}
 	...
 }
The following features will help make the Record more dynamic.  This includes using  maps to transmit data, or loading data through XML.
COUNT COLUMN (optional)  This is a special feature, marking a registered column as a count column.  This is  a column whose value is an integer, used for counting.  For example, if a table  wants to track the number of times a record has been viewed 'view', the 'view'  column could be registered as COUNT COLUMN and use the increment/decrement methods  for easy changes.  Count Columns are defined by the Prototype.
CALLBACKS (optional)  The Gumbo_Record class performs four types of queries: "SELECT,INSERT,UPDATE,DELETE".  The four methods (_reload,create,save,kill) each have defined queries to perform the  single operation.  In some cases, a more advanced or specific query is required.  This  is where the CALLBACKS are useful.  The programmer can define more complex queries,  placing them in a separate method.  The Prototype would define the callback functions  for each operation.  If a callback is not defined, the Gumbo_Record class will use the  pre-programmed defaults.  (see Gumbo_Record_Prototype for more details)
MAPS (optional)  The Gumbo_Record class contains four predefined Maps.  This will associate the column names  with particular elements.  Maps are defined by the Prototype.  In order to use a map,  simple call the 'map' method, passing the appropriate data and which map to use.  This  is best used with Form Input.
JOIN QUERIES  There will be instances where accessing information from one table requires information from  another table by means of a join.  This complex query should be placed inside a callback  function.  The associative array returned will contain the columns from the table including  keys referencing the joined table data.  The Gumbo_Record class takes the extra columns  created by a join and places them in a special location called ColumnsExtra.  Extra JOIN  data will be read only.  The child class should define 'get' methods to access the information.  The parent get method just requires the column name and the value will be returned.
XML  The child constructor should define the parent XML element name in the constructor.  This will  be used to format an XML string or parse a supplied string.
The XML feature will accept an XML string containing the data to apply to the Gumbo_Record.  This  will be applied to the column 'xml' Map.  The method will require the name of the Parent XML  element name.  The parent element should contain an 'id' attribute with the value of the  primary column key.
The next part of the feature will return the object as a formatted XML string.  This will use  the 'xml' Map.  The formatted string will be surrounded by the parent XML value.







	
	
	

	
	
	
	
	
															
																
																
																									
				
			
Author(s):
												Michael Luster <mluster79@yahoo.com>

																																												

		
			
License:New BSD License

		
			
Copyright:Copyright (c) 2007, iBayou, Michael Luster

		
			
Link:http://sourceforge.net/projects/phpgumbo

		
			
Version:0.0.1

		







	
Implements interfaces:

	
	





	


	



	
	
Class Variables

	
	
	

		array $_columns = array ()		[line 174] 
		
		
			

	
	
	

		array $_columns_count = array ()		[line 180] 
		
		
			

	
	
	

		array $_columns_extra = array ()		[line 178] 
		
		
			

	
	
	

		array $_columns_mod = array ()		[line 176] 
		
		
			

	
	
	

		bool $_loaded =  false		[line 186] 
		
		
			

	
	
	

		Gumbo_Interface_Map[] $_maps = array ()		[line 183] 
		
		
			

	
	
	

		bool $_modified =  false		[line 188] 
		
		
			

	
	
	

		mixed $_primary_value		[line 171] 
		
		
			

	
	
	

		Gumbo_Record_Prototype $_prototype		[line 168] 
		
		
			

	
	
	

		bool $_read_only =  false		[line 190] 
		
		
			

	
	


	
	
Class Methods

	


	
	
	

		

			public Gumbo_Record __construct ( [int|array $val] )
			[line 198]
		

		
		
Constructor
		
					
Parameter(s):

			
    
							
  • 
				(int|array) $val
								
    • 
						

			

				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void add ( string $column, [int $num] )
			[line 757]
		

		
		
Adds (increments) to the current count columns value
		
					
Parameter(s):

			
    
							
  • 
				(string) $column
				 :: count column name				
    • 
							
  • 
				(int) $num
				 :: increases by the supplied number				
    • 
						

			

				
					
    
											
  • precondition:  _isColumnCount ($column)
    • 
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void addMap (  $map, [string $key], [bool $replace] )
			[line 1179]
		

		
		
Adds a Map (not used)
		
					
Parameter(s):

			
    
							
  • 
				(Gumbo_Interface_Map) $map
								
    • 
							
  • 
				(string) $key
				 :: reference string to the Map object (null is 'method')				
    • 
							
  • 
				(bool) $replace
				 :: replaces original if set				
    • 
						

			

				
					
    
											
  • postcondition:  remove all non-alphanumeric characters (including underscores) from the key
    • 
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public string asXML ( [string $parent] )
			[line 1005]
		

		
		
Returns the object as an XML formatted string
		
					
Parameter(s):

			
    
							
  • 
				(string) $parent
				 :: parent element name				
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void create (  )
			[line 585]
		

		
		
Creates a new record in the database
		
				
					
    
											
  • throws:  Gumbo_Exception
    • 
											
  • precondition:  !isReadOnly
    • 
											
  • precondition:  !isLoaded ()
    • 
											
  • precondition:  isModified ()
    • 
															
  • uses:  Gumbo_Query
    • 
						

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void decrement ( string $column, [int $num], [bool $allow_negative] )
			[line 850]
		

		
		
Wrapper to sub() method
		
					
Parameter(s):

			
    
							
  • 
				(string) $column
				 :: count column name				
    • 
							
  • 
				(int) $num
				 :: decreases by the supplied number				
    • 
							
  • 
				(bool) $allow_negative
				 :: allows negative values				
    • 
						

			

				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public mixed get ( string $column )
			[line 978]
		

		
		
Returns the value of a column
		
					
Parameter(s):

			
    
							
  • 
				(string) $column
								
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public array getAllColumns (  )
			[line 1044]
		

		
		
Returns the entire Columns array
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public array getAllColumnsCount (  )
			[line 1140]
		

		
		
Returns all the count columns
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public array getAllColumnsExtra (  )
			[line 1108]
		

		
		
Returns all the extra columns array
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public array getAllColumnsMod (  )
			[line 1076]
		

		
		
Returns all modified table columns array
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public Gumbo_Interface_Map getMap ( [string $key] )
			[line 1244]
		

		
		
Gets the selected Map (not used)
		
					
Parameter(s):

			
    
							
  • 
				(string) $key
				 :: (null is 'method')				
    • 
						

			

				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public string getPrimaryKey (  )
			[line 918]
		

		
		
Returns the primary key name
		
				
					
    
											
  • precondition:  getPrototype()
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public mixed getPrimaryValue (  )
			[line 941]
		

		
		
Returns the primary key value
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			protected Gumbo_Record_Prototype getPrototype (  )
			[line 897]
		

		
		
Returns the Prototype
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public string getTable (  )
			[line 906]
		

		
		
Returns the table name
		
				
					
    
											
  • precondition:  getPrototype()
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public string getXMLParent (  )
			[line 930]
		

		
		
Returns the XML parent element name
		
				
					
    
											
  • precondition:  getPrototype()
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void increment ( string $column, [int $num] )
			[line 790]
		

		
		
Wrapper to add() method
		
					
Parameter(s):

			
    
							
  • 
				(string) $column
				 :: count column name				
    • 
							
  • 
				(int) $num
				 :: increases by the supplied number				
    • 
						

			

				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			protected void init ( Gumbo_Record_Prototype $prototype )
			[line 294]
		

		
		
Initializes the Record by passing a Record_Prototype
		
					
Parameter(s):

			
			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public bool isLoaded (  )
			[line 949]
		

		
		
Returns if the records was loaded
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public bool isMap ( [string $key] )
			[line 1279]
		

		
		
Returns if the Map exists
		
					
Parameter(s):

			
    
							
  • 
				(string) $key
				 :: reference key string (null is 'method')				
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public bool isModified (  )
			[line 957]
		

		
		
Returns if the record was modified
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public bool isReadOnly (  )
			[line 965]
		

		
		
Returns if the record accesses the database
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void kill (  )
			[line 497]
		

		
		
Removes the record from the database
		
				
					
    
											
  • precondition:  !isReadOnly ()
    • 
											
  • throws:  Gumbo_Exception
    • 
											
  • precondition:  isLoaded ()
    • 
															
  • uses:  Gumbo_Query
    • 
						

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void load (  )
			[line 341]
		

		
		
Loads the record into memory
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void loadXML ( string $xml, [string $parent] )
			[line 354]
		

		
		
Loads an XML string, but only the first level of the parent
		
					
Parameter(s):

			
    
							
  • 
				(string) $xml
								
    • 
							
  • 
				(string) $parent
				 :: name of top level XML element				
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void map ( array $data, [string $key] )
			[line 1208]
		

		
		
Maps information into the Mapper
		
					
Parameter(s):

			
    
							
  • 
				(array) $data
				 :: where key=>"form field name", value=>user data				
    • 
							
  • 
				(string) $key
				 :: Map reference key (null is 'method')				
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
											
  • precondition:  isMap("method")
    • 
											
  • precondition:  isMap(key)
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void removeMap ( [string $key] )
			[line 1188]
		

		
		
Deletes a Map (not used)
		
					
Parameter(s):

			
    
							
  • 
				(string) $key
								
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void reset (  )
			[line 628]
		

		
		
Resets the object by removing the values from the modified array
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void resetMaps (  )
			[line 1196]
		

		
		
Clears all the Maps (not used)
		
				
					
    
											
  • postcondition:  no maps
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void save (  )
			[line 533]
		

		
		
Saves a modified record to the database
		
				
					
    
											
  • throws:  Gumbo_Exception
    • 
											
  • precondition:  !isReadOnly ()
    • 
											
  • precondition:  isLoaded ()
    • 
											
  • precondition:  isModified ()
    • 
															
  • uses:  Gumbo_Query
    • 
						

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			protected void set ( string $column, [mixed $val] )
			[line 722]
		

		
		
Sets the value of a table column
		
					
Parameter(s):

			
    
							
  • 
				(string) $column
				 :: table column name				
    • 
							
  • 
				(mixed) $val
				 :: primitive type value				
    • 
						

			

				
					
    
											
  • precondition:  !isReadOnly ()
    • 
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void setPrimaryValue ( mixed $val )
			[line 641]
		

		
		
Sets the primary key column value
		
					
Parameter(s):

			
    
							
  • 
				(mixed) $val
								
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void setReadOnly ( bool $val )
			[line 698]
		

		
		
Sets the object as read only
		
					
Parameter(s):

			
    
							
  • 
				(bool) $val
								
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void sub ( string $column, [int $num], [bool $allow_negative] )
			[line 802]
		

		
		
Subtracts (decrement) one from the count column value
		
					
Parameter(s):

			
    
							
  • 
				(string) $column
				 :: count column name				
    • 
							
  • 
				(int) $num
				 :: decreases by the supplied number				
    • 
							
  • 
				(bool) $allow_negative
				 :: allows negative values				
    • 
						

			

				
					
    
											
  • precondition:  _isColumnCount ($column)
    • 
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void unload ( [bool $erase_all] )
			[line 461]
		

		
		
Clears the object values, leaves the columns structure
		
					
Parameter(s):

			
    
							
  • 
				(bool) $erase_all
				 :: clears extra values from memory				
    • 
						

			

				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			private string|array _getCallback ( string $for )
			[line 868]
		

		
		
Returns the callback function/method
		
					
Parameter(s):

			
    
							
  • 
				(string) $for
				 :: type of query "select|update|insert|delete"				
    • 
						

			

				
					
    
											
  • precondition:  getPrototype()
    • 
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			private Gumbo_Interface_Map _getMap ( [string $key] )
			[line 1254]
		

		
		
Gets the selected Map
		
					
Parameter(s):

			
    
							
  • 
				(string) $key
				 :: (null is 'method')				
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			private bool _isColumn ( string $column )
			[line 1054]
		

		
		
Returns if the column exists
		
					
Parameter(s):

			
    
							
  • 
				(string) $column
				 :: table column name				
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			private bool _isColumnCount ( string $column )
			[line 1150]
		

		
		
Returns if the supplied column was marked as a Count Column
		
					
Parameter(s):

			
    
							
  • 
				(string) $column
								
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			private bool _isColumnExtra ( string $column )
			[line 1118]
		

		
		
Returns if the extra column key exists
		
					
Parameter(s):

			
    
							
  • 
				(string) $column
				 :: extra column key				
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			private bool _isColumnMod ( string $column )
			[line 1086]
		

		
		
Returns if the supplied column was modified
		
					
Parameter(s):

			
    
							
  • 
				(string) $column
				 :: modified key				
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			private void _reload (  )
			[line 415]
		

		
		
Loads new Record or refreshes the saved/created Item values
		
				
					
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			private void _setLoaded ( bool $val )
			[line 660]
		

		
		
Sets if the record was loaded
		
					
Parameter(s):

			
    
							
  • 
				(bool) $val
								
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			private void _setModified ( bool $val )
			[line 679]
		

		
		
Sets if the record was modified
		
					
Parameter(s):

			
    
							
  • 
				(bool) $val
								
    • 
						

			

				
					
    
											
  • throws:  Gumbo_Exception
    • 
										

				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public mixed __get ( string $column )
			[line 252]
		

		
		
Returns the raw value of the column name
		
					
Parameter(s):

			
    
							
  • 
				(string) $column
								
    • 
						

			

				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public bool __isset ( string $key )
			[line 274]
		

		
		
Returns if the column is set
		
					
Parameter(s):

			
    
							
  • 
				(string) $key
								
    • 
						

			

				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void __set ( string $key, mixed $val )
			[line 218]
		

		
		
Sets the value of a table column using 'key' map
		
					
Parameter(s):

			
    
							
  • 
				(string) $key
								
    • 
							
  • 
				(mixed) $val
								
    • 
						

			

				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public array __sleep (  )
			[line 206]
		

		
		
Serialized method
		
				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void __unset ( string $key )
			[line 238]
		

		
		
Unsets the value of the supplied table column
		
					
Parameter(s):

			
    
							
  • 
				(string) $key
								
    • 
						

			

				
				
				
		
				
		

		[ Top ]
	

	
	
	
	

		

			public void __wakeup (  )
			[line 211]
		

		
		
Unserialized method
		
				
				
				
		
				
		

		[ Top ]