/fuel/modules/fuel/core/MY_Model.php

Large files files are truncated, but you can click here to view the full file

<?php if (!defined('BASEPATH')) exit('No direct script access allowed');
/**
 * FUEL CMS
 * http://www.getfuelcms.com
 *
 * An open source Content Management System based on the 
 * Codeigniter framework (http://codeigniter.com)
 *
 * @package		FUEL CMS
 * @author		David McReynolds @ Daylight Studio
 * @copyright	Copyright (c) 2018, Daylight Studio LLC.
 * @license		http://docs.getfuelcms.com/general/license
 * @link		http://www.getfuelcms.com
 */

// ------------------------------------------------------------------------

/**
 * MY_Model class
 * 
 * An extension of the Model class to map data operations to a table.
 * Depends upon the Validator library, date helper and the string helper.
 * 
 * Inspired from this post here Developer13:
 * http://codeigniter.com/forums/viewthread/88769/
 * 
 * @package		FUEL CMS
 * @subpackage	Libraries
 * @category	Libraries
 * @author		David McReynolds @ Daylight Studio
 * @link		http://docs.getfuelcms.com/libraries/my_model
 * @prefix		$this->example_model->
 */


class MY_Model extends CI_Model {
	
	public $auto_validate = TRUE; // use auto-validation before saving
	public $return_method = 'auto'; // object, array, query, auto
	
	 // fields to auto validate
	public $auto_validate_fields = array(
		'email|email_address' => 'valid_email',
		'phone|phone_number' => 'valid_phone'
		);
	public $required = array(); // an array of required fields. If a key => val is provided, the key is name of the field and the value is the error message to display
	public $default_required_message = "Please fill out the required field '%1s'"; // the default required validator message
	public $auto_date_add = array('date_added', 'entry_date'); // field names to automatically set the date when the value is NULL
	public $auto_date_update = array('last_modified', 'last_updated'); // field names to automatically set the date on updates
	public $date_use_gmt = FALSE; // determines whether to use GMT time when storing dates and times
	public $default_date = 0; // default date value that get's passed to the model on save. Using 0000-00-00 will not work if it is a required field since it is not seen as an empty value
	public $auto_trim = TRUE; // will trim on clean
	public $auto_encode_entities = TRUE; // determines whether to automatically encode html entities. An array can be set instead of a boolean value for the names of the fields to perform the safe_htmlentities on
	public $xss_clean = FALSE; // determines whether automatically run the xss_clean. An array can be set instead of a boolean value for the names of the fields to perform the xss_clean on
	public $readonly = FALSE; // sets the model to readonly mode where you can't save or delete data
	public $hidden_fields = array(); // fields to hide when creating a form
	public $unique_fields = array(); // fields that are not IDs but are unique. Can also be an array of arrays for compound keys
	public $linked_fields = array(); // fields that are linked meaning one value helps to determine another. Key is the field, value is a function name to transform it. (e.g. array('slug' => 'title'), or array('slug' => array('name' => 'strtolower')));
	public $serialized_fields = array(); // fields that contain serialized data. This will automatically serialize before saving and unserialize data upon retrieving
	public $default_serialization_method = 'json'; // the default serialization method. Options are 'json' and 'serialize'
	public $boolean_fields = array(); // fields that are tinyint and should be treated as boolean
	public $suffix = '_model'; // the suffix used for the data record class
	public $foreign_keys = array(); // map foreign keys to table models
	public $has_many = array(); // keys are model, which can be a key value pair with the key being the module and the value being the model, module (if not specified in model parameter), relationships_model, foreign_key, candidate_key
	public $belongs_to = array(); // keys are model, which can be a key value pair with the key being the module and the value being the model, module (if not specified in model parameter), relationships_model, foreign_key, candidate_key
	public $representatives = array(); // an array of fields that have arrays or regular expression values to match against different field types (e.g. 'number'=>'bigint|smallint|tinyint|int')
	public $custom_fields = array(); // an array of field names/types that map to a specific class
	public $formatters = array(); // an array of helper formatter functions related to a specific field type (e.g. string, datetime, number), or name (e.g. title, content) that can augment field results

	/**
	 * @var CI_DB_query_builder CI database query builder
	 */
	protected $db;

	protected $table_name; // the table name to associate the model with
	protected $key_field = 'id'; // usually the tables primary key(s)... can be an array if compound key
	protected $normalized_save_data = NULL; // the saved data before it is cleaned
	protected $cleaned_data = NULL; // data after it is cleaned
	protected $dsn = ''; // the DSN string to connect to the database... if blank it will pull in from database config file
	protected $has_auto_increment = TRUE; // does the table have auto_increment?
	protected $record_class = ''; // the name of the record class (if it can't be determined)
	protected $friendly_name = ''; // a friendlier name of the group of objects
	protected $singular_name = ''; // a friendly singular name of the object
	protected $rules = array(); // validation rules
	protected $fields = array(); // fields in the table
	protected $use_common_query = TRUE; // include the _common_query method for each query
	protected $validator = NULL; // the validator object
	protected $clear_related_on_save = 'AUTO'; // clears related records before saving
	protected $_tables = array(); // an array of table names with the key being the alias and the value being the actual table
	protected $_last_saved = NULL; // a reference to the last saved object / ID of record;
	protected $_nested_errors = array(); // used for capturing errors when saving multiple records (an array of records) on a single save method call
	

	/**
	 * Constructor - Sets MY_Model preferences
	 *
	 * The constructor can be passed an array of config values
	 */
	public function __construct($table = NULL, $params = array())
	{
		parent::__construct();
		
		$this->load->library('validator');
		$this->load->helper('string');
		$this->load->helper('date');
		$this->load->helper('security');
		$this->load->helper('inflector');
		$this->load->helper('language');


		$this->load->module_language(FUEL_FOLDER, 'model');
		$this->initialize($table, $params);
    }

	// --------------------------------------------------------------------
	
	/**
	 * Initialize the user preferences
	 *
	 * Accepts an associative array as input, containing display preferences
	 *
	 * @access	public
	 * @param	string	the table name
	 * @param	array	config preferences
	 * @return	void
	 */	
	public function initialize($table = NULL, $params = array())
	{
		if (!empty($table))
		{
			$this->table_name = $table;
		} 
		else 
		{
			$this->table_name = strtolower(get_class($this));
		}
		
		if (!empty($params))
		{
			foreach ($params as $key => $val)
			{
				if (isset($this->$key))
				{
					$this->$key = $val;
				}
			}
		}
		
		// if a DSN property is set,then we will load that database in
		if (!empty($this->dsn))
		{
			$this->set_db($this->load->database($this->dsn, TRUE, TRUE));
		}
		else
		{
			// else we use the database set on the CI object
			if (empty($this->db))
			{
				$this->load->database($this->dsn);
			}
			$CI =& get_instance();
			if (isset($CI->db))
			{
				// create a copy of the DB object to prevent cross model interference
				unset($this->db);
				$db = clone $CI->db;
				$this->set_db($db);
			}
			else
			{
				$CI->load->language('db');
				show_error(lang('db_unable_to_connect'));
			}
		}
		$this->validator = new Validator();
		$this->validator->register_to_global_errors = FALSE;

		// load any additional classes needed for custom fields
		$this->load_custom_field_classes();

	}

	// --------------------------------------------------------------------
	
	/**
	 * Sets the database object for a model
	 *
	 <code>
	$db = $CI->db;
	$this->examples_model->set_db($db); 
	</code>
	 *
	 * @access	public
	 * @return	array
	 */	
	public function set_db($db)
	{
		$this->db = $db;
		return $this;
	}

	// --------------------------------------------------------------------
	
	/**
	 * Returns the database object
	 *
	 <code>
	$db = $this->examples_model->db(); 
	</code>
	 *
	 * @access	public
	 * @return	array
	 */	
	public function &db()
	{
 		//$this->_check_readonly();
		return $this->db;
	}
	
	// --------------------------------------------------------------------
	
	/**
	 * Gets the short name minus the suffix
	 *
	 <code>
	echo $this->examples_model->short_name(TRUE); 
	// examples
	</code>
	 *
	 * @access	public
	 * @param	boolean	lower case the name (optional)
	 * @param	boolean return the record class name (optional)
	 * @return	array
	 */	
	public function short_name($lower = FALSE, $record_class = FALSE)
	{
		$class_name = ($record_class) ? $this->record_class_name() : get_class($this);
		$end_index = strlen($class_name) - strlen($this->suffix);
		$short_name = substr($class_name, 0, $end_index);
		if ($lower)
		{
			return strtolower($short_name);
		}
		else
		{
			return $short_name;
		}
	}

	// --------------------------------------------------------------------
	
	/**
	 * Gets the name of the model object. By default it will be the same as the short_name(FALSE, FALSE) if no "friendly_name" value is specified on the model
	 *
	 <code>
	echo $this->examples_model->friendly_name(TRUE); 
	// examples
	</code>
	 *
	 * @access	public
	 * @param	boolean	lower case the name (optional)
	 * @return	array
	 */	
	public function friendly_name($lower = FALSE)
	{
		if (!empty($this->friendly_name))
		{
			if ($lower)
			{
				return strtolower($this->friendly_name);
			}
			return $this->friendly_name;
		}
		$friendly_name = $this->short_name($lower, FALSE);
		$friendly_name = ucfirst(str_replace('_', ' ', $friendly_name));
		return $friendly_name;
	}

	// --------------------------------------------------------------------
	
	/**
	 * Gets the singular name of the model object. By default it will be the same as the short_name(FALSE, TRUE) if no "singular_name" value is specified on the model
	 *
	 <code>
	echo $this->examples_model->singular_name(TRUE); 
	// example
	</code>
	 *
	 * @access	public
	 * @param	boolean	lower case the name (optional)
	 * @return	array
	 */	
	public function singular_name($lower = FALSE)
	{
		if (!empty($this->singular_name))
		{
			if ($lower)
			{
				return strtolower($this->singular_name);
			}
			return $this->singular_name;
		}

		$singular_name = $this->short_name($lower, TRUE);
		$singular_name = ucfirst(str_replace('_', ' ', $singular_name));
		return $singular_name;
	}

	// --------------------------------------------------------------------
	
	/**
	 * Get the table name
	 *
	 <code>
	echo $this->examples_model->table_name(); 
	// examples
	</code>
	 *
	 * @access	public
	 * @return	array
	 */	
	public function table_name()
	{
		return $this->table_name;
	}

	// --------------------------------------------------------------------
	
	/**
	 * Returns whether the model uses auto_increment or not
	 *
	 <code>
	echo $this->examples_model->has_auto_increment(); 
	// TRUE
	</code>
	 *
	 * @access	public
	 * @return	boolean
	 */	
	public function has_auto_increment()
	{
		return $this->has_auto_increment;
	}

	// --------------------------------------------------------------------
	
	/**
	 * Sets the aliases to table(s) that you can use in your queries
	 *
	 <code>
	$my_tables = array('mytable' => 'my_table');
	$this->examples_model->set_tables($my_tables); 
	</code>
	 *
	 * @access	public
	 * @param	array	an array of tables
	 * @return	void
	 */	
	public function set_tables($tables)
	{
		$this->_tables = array_merge($this->_tables, $tables);
	}

	// --------------------------------------------------------------------
	
	/**
	 * Gets the table(s) name based on the configuration
	 *
	 <code>
	$table_name = $this->examples_model->tables('my_table'); 
	</code>
	 *
	 * @access	public
	 * @param	string	the table name (optional)
	 * @return	string|array|null
	 */	
	public function tables($table = NULL)
	{
		if (!empty($table))
		{
			if (isset($this->_tables[$table]))
			{
				return $this->_tables[$table];
			}
			else
			{
				return NULL;
			}
		}
		else
		{
			return $this->_tables;
		}
	}

	// --------------------------------------------------------------------
	
	/**
	 * Get the key field(s)
	 *
	 <code>
	$fields = $this->examples_model->key_field(); 
	</code>
	 *
	 * @access	public
	 * @return	array
	 */	
	public function key_field()
	{
		return $this->key_field;
	}
	
	// --------------------------------------------------------------------
	
	/**
	 * Get the fields of the table
	 *
	 <code>
	 $fields = $this->examples_model->fields(); 
	 foreach($fields as $field)
	{
		echo $field; // field name
	}
	</code>
	 *
	 * @access	public
	 * @return	array
	 */	
	public function fields()
	{
		if (empty($this->fields)) $this->fields = $this->db->list_fields($this->table_name);
		return $this->fields;
	}

	// --------------------------------------------------------------------
	
	/**
	 * Get the results of the query
	 *
	 <code>
	$rows = $this->examples_model->get(TRUE, 'object', FALSE); 
	foreach($rows->result() as $row)
	{
	    echo $row->name;
	}
	
	// The third parameter is the column name to be used as the array key value (if <dfn>$force_array</dfn> is set to <dfn>TRUE</dfn>)
	$rows = $this->examples_model->get(TRUE, 'object', 'id'); 
	foreach($rows->result() as $id => $row)
	{
	    echo $id;
	}
	</code>
	 *
	 * @access	public
	 * @param	boolean	return multiple records (optional)
	 * @param	string	method return type (object, array, query, auto) (optional)
	 * @param	string	the column to use for an associative key array (optional)
	 * @param	boolean	determine whether to use the _common_query method in the query (optional)
	 * @return	array
	 */	
	public function get($force_array = TRUE, $return_method = NULL, $assoc_key = NULL, $use_common_query = NULL){

		if (!empty($this->return_method) AND empty($return_method)) $return_method = $this->return_method;
		//$this->fields();
		
		if (!isset($use_common_query)) $use_common_query =  $this->use_common_query;
		
		// common query if exists
		if (method_exists($this, '_common_query') AND $use_common_query)
		{
			$this->_common_query();
		}
		
		if (!$this->db->has_select())
		{
			$this->db->select($this->table_name.'.*'); // make select table specific
		}
		
		//Get the data out of the database
		$query = $this->db->get($this->table_name);
		
		if (empty($query)) $query = ($this->db->dbdriver == 'mysql') ? new MY_DB_mysql_result($this->db) : new MY_DB_mysqli_result($this->db);
		
		if ($this->return_method == 'query') 
		{
			return $query;
		}
		
		if ($return_method == 'array' OR !class_exists($this->record_class_name()))
		{
			if ($return_method == 'object')
			{
				$result_objects = (!empty($assoc_key)) ? $query->result_assoc($assoc_key) : $query->result() ;
			}
			else
			{
				$result_objects = (!empty($assoc_key)) ? $query->result_assoc_array($assoc_key) : $query->result_array();
			}
			$this->last_data_set = new Data_set($result_objects, $force_array);
		}
		else
		{
			$result_objects = $this->map_query_records($query, $assoc_key);
			$this->last_data_set = new Data_set($result_objects, $force_array);
		}
		$query->free_result();
		
		//This array holds all result data
		return $this->last_data_set;
	}
	
	// --------------------------------------------------------------------
	
	/**
	 * Maps a query result object to an array of record objects
	 *
	 <code>
	...
	$query = $this->db->query('SELECT * FROM USERS');
	$users = $this->examples_model->map_query_records($query, 'id');
	foreach($users as $id => $user)
	{
	    echo $user->name;
	}
	</code>
	 *
	 * @access	public
	 * @param	object	the query object
	 * @param	string	the field name to be used the key value (optional)
	 * @return	array
	 */	
	public function map_query_records($query, $assoc_key = NULL)
	{
		$result = $query->result_array(); 
		$result_objects = array();
		if (!empty($result))
		{
			foreach ($result as $row) 
			{
				$record = $this->map_to_record_class($row);
				if (!empty($assoc_key))
				{
					$result_objects[$row[$assoc_key]] = $record;
				}
				else
				{
					$result_objects[] = $record;
				}
			}
		}
		return $result_objects;	
	}
	
	// --------------------------------------------------------------------
	
	/**
	 * Maps an associative record array to a record object
	 *
	 <code>
	$my_user['id'] = 1;
	$my_user['name'] = 'Darth Vader';
	$my_user['email'] = 'darth@deathstar.com';
	$my_custom_record = $this->examples_model->map_to_record_class($my_user); 
	echo $my_custom_record->name;
	</code>
	 *
	 * @access	public
	 * @param	array	field values
	 * @param	array	all the fields available for the object (optional)
	 * @return	array
	 */	
	public function map_to_record_class($row, $fields = NULL)
	{
		if (empty($fields))
		{
			$fields = array_keys($row);
		}
		$record_class = $this->record_class_name();
		$record = new $record_class();
		$record->initialize($this, $fields);
		$record->fill($row);
		return $record;
	}
	
	// --------------------------------------------------------------------
	
	/**
	 * Get the results of the query
	 *
	 <code>
	$examples = $this->examples_model->find_all(array('published' => 'yes'), 'date_added desc'); 
	</code>
	 *
	 * @access	public
	 * @param	string	the type of find to perform. Options are "key", "one", "options", "all" and find_"{your_method}". By default it will perform a find_all (optional)
	 * @param	mixed	an array or string containing the where parameters of a query (optional)
	 * @param	string	the order by of the query (optional)
	 * @param	int		the number of records to limit in the results (optional)
	 * @param	int		the offset value for the results (optional)
	 * @param	string	return type (object, array, query, auto) (optional)
	 * @param	string	the column to use for an associative key array (optional)
	 * @return	array
	 */	
	public function find($find = 'all', $where = NULL, $order = NULL, $limit = NULL, $offset = NULL, $return_method = NULL, $assoc_key = NULL)
	{
		// allows for just a single parameter of arrays to be passed
		if (is_array($find))
		{
			extract($find);
		}

		$data = array();
		if ($find === 'key')
		{
			$data = $this->find_by_key($where, $return_method);
		}
		else if ($find === 'one')
		{
			$data = $this->find_one($where, $order, $return_method);
		}
		else if ($find === 'options')
		{
			$data = $this->options_list(NULL, NULL, $where, $order);
		}
		else
		{
			if (empty($find) OR $find == 'all')
			{
				$data = $this->find_all($where, $order, $limit, $offset, $return_method, $assoc_key);
			}
			else
			{
				$method = 'find_'.$find;
				if (is_callable(array($this, $method)))
				{
					$args = func_get_args();
					array_shift($args);
					$data = call_user_func_array(array($this, $method), $args);
				}
				else
				{
					return FALSE;
				}

			}
		}
		return $data;
	}

	// --------------------------------------------------------------------
	
	/**
	 * Get one record result based on the key value
	 *
	 <code>
	$id = 1;
	$example = $this->examples_model->find_by_key($id, 'object'); 
	</code>
	 *
	 * @access	public
	 * @param	string	the key value to find a single record
	 * @param	mixed	return type (object, array, query, auto) (optional)
	 * @return	array
	 */	
	public function find_by_key($key_val, $return_method = NULL)
	{
		$where = array();
		if (is_array($key_val))
		{
			$key_field = (array) $this->key_field;
			foreach($key_field as $val)
			{
				if (is_array($key_val))
				{
					foreach($key_val as $key2 => $val2)
					{
						if ($key2 == $val)
						{
							$where[$val] = $val2;
						}
					}
				}
			}
		}
		else
		{
			$where[$this->table_name.'.'.$this->key_field] = $key_val;
		}
		return $this->find_one($where, NULL, $return_method);
	}
	
	// --------------------------------------------------------------------

	/**
	 * Get one record result
	 *
	 <code>
	$example = $this->examples_model->find_one(array('published' => 'yes'), ''asc');
	</code>
	 *
	 * @access	public
	 * @param	mixed	an array or string containing the where parameters of a query (optional)
	 * @param	string	the order by of the query (optional)
	 * @param	string	return type (object, array, query, auto) (optional)
	 * @return	array
	 */
	public function find_one($where = array(), $order_by = NULL, $return_method = NULL)
	{
		$where = $this->_safe_where($where);
		$this->_handle_where($where);
		if (!empty($order_by)) $this->db->order_by($order_by);
		$this->db->limit(1);
		$query = $this->get(FALSE, $return_method);
		if ($return_method == 'query') return $query;

		$data = $query->result();

		// unserialize any data
		if ($return_method == 'array')
		{
			$data = $this->unserialize_field_values($data);
		}
		return $data;
	}

	// --------------------------------------------------------------------
	
	/**
	 * Get one record result as an array
	 *
	 <code>
	$examples = $this->examples_model->find_one_array(array('published' => 'yes'), 'date_added desc'); 
	</code>
	 *
	 * @access	public
	 * @param	mixed	an array or string containing the where parameters of a query
	 * @param	string	the order by of the query (optional)
	 * @return	array
	 */	
	public function find_one_array($where, $order_by = NULL)
	{
		return $this->find_one($where, $order_by, 'array');
	}
	
	// --------------------------------------------------------------------

	/**
	 * Get the results of the query
	 *
	 <code>
	$examples = $this->examples_model->find_all(array('published' => 'yes'), 'date_added desc');
	</code>
	 *
	 * @access	public
	 * @param	mixed	an array or string containing the where parameters of a query (optional)
	 * @param	string	the order by of the query (optional)
	 * @param	int		the number of records to limit in the results (optional)
	 * @param	int		the offset value for the results (optional)
	 * @param	string	return type (object, array, query, auto) (optional)
	 * @param	string	the column to use for an associative key array (optional)
	 * @return	array
	 */
	public function find_all($where = array(), $order_by = NULL, $limit = NULL, $offset = NULL, $return_method = NULL, $assoc_key = NULL)
	{
		$where = $this->_safe_where($where);

		$this->_handle_where($where);

		// set order
		if (!empty($order_by)) $this->db->order_by($order_by);

		// set limit
		if (isset($limit))
		{
			$limit = (int) $limit;	
			$this->db->limit($limit);
		}
			
		// set offset
		if (isset($offset))
		{
			$offset = (int) $offset;	
			$this->db->offset($offset);
		}

		$query = $this->get(TRUE, $return_method, $assoc_key);
		if ($return_method == 'query') return $query;

		$data = $query->result();

		// unserialize any data if the return method is an array. If it is a custom object, then we let the object take care of it
		if ($return_method == 'array')
		{
			$data = $this->unserialize_field_values($data);
		}
		return $data;
	}

	// --------------------------------------------------------------------
	
	/**
	 * Get the results of the query as an array
	 *
	 <code>
	$examples = $this->examples_model->find_all_array(array('published' => 'yes'), 'date_added desc'); 
	</code>
	 *
	 * @access	public
	 * @param	mixed	an array or string containing the where parameters of a query (optional)
	 * @param	string	the order by of the query (optional)
	 * @param	int		the number of records to limit in the results (optional)
	 * @param	int		the offset value for the results (optional)
	 * @return	array
	 */	
	public function find_all_array($where = array(), $order_by = NULL, $limit = NULL, $offset = NULL)
	{
		return $this->find_all($where, $order_by, $limit, $offset, 'array');
	}

	// --------------------------------------------------------------------
	
	/**
	 * Get the results of the query returned as a keyed array of objects
	 *
	 <code>
	$examples = $this->examples_model->find_all_assoc(array('published' => 'yes'), 'date_added desc'); 
	</code>
	 *
	 * @access	public
	 * @param	string	the column to use for an associative key array (optional)
	 * @param	mixed	an array or string containing the where parameters of a query (optional)
	 * @param	string	the order by of the query (optional)
	 * @param	int		the number of records to limit in the results (optional)
	 * @param	int		the offset value for the results (optional)
	 * @return	array
	 */	
	public function find_all_assoc($assoc_key = 'id', $where = array(), $order_by = NULL, $limit = NULL, $offset = NULL)
	{
		return $this->find_all($where, $order_by, $limit, $offset, 'object', $assoc_key);
	}

	// --------------------------------------------------------------------
	
	/**
	 * Get the results of the query returned as a keyed array of arrays
	 *
	 <code>
	$examples = $this->examples_model->find_all_assoc(array('published' => 'yes'), 'date_added desc'); 
	</code>
	 *
	 * @access	public
	 * @param	string	the column to use for an associative key array (optional)
	 * @param	mixed	an array or string containing the where parameters of a query (optional)
	 * @param	string	the order by of the query (optional)
	 * @param	int		the number of records to limit in the results (optional)
	 * @param	int		the offset value for the results (optional)
	 * @return	array
	 */	
	public function find_all_array_assoc($assoc_key = 'id', $where = array(), $order_by = NULL, $limit = NULL, $offset = NULL)
	{
		return $this->find_all($where, $order_by, $limit, $offset, 'array', $assoc_key);
	}

	// --------------------------------------------------------------------
	
	/**
	 * Get the results of a query from within a select group of key field values. Results are sorted by the order from within the group.
	 *
	 <code>
	$examples = $this->examples_model->find_within(array(1, 2, 3, 4), array('published' => 'yes'), 'date_added desc'); 
	</code>
	 *
	 * @access	public
	 * @param	group	an array of keys to limit the search results to
	 * @param	mixed	an array or string containing the where parameters of a query (optional)
	 * @param	int		the number of records to limit in the results (optional)
	 * @param	int		the offset value for the results (optional)
	 * @param	string	return type (object, array, query, auto) (optional)
	 * @param	string	the column to use for an associative key array (optional)
	 * @return	array
	 */	
	public function find_within($group, $where = array(), $limit = NULL, $offset = NULL, $return_method = NULL, $assoc_key = NULL)
	{
		if (empty($group) OR !is_array($group))
		{
			return array();
		}

		// setup wherein for the group
		$this->db->where_in($this->table_name.'.'.$this->key_field(), $group);

		// escape group
		foreach($group as $key => $val)
		{
			$group[$key] = $this->db->escape($val);
		}

		// remove any cached order by
		$this->db->ar_cache_orderby = array();

		$this->db->order_by('FIELD('.$this->table_name.'.'.$this->key_field().', '.implode(', ', $group).')', '', FALSE);

		// do a normal find all
		$data = $this->find_all($where, NULL, $limit, $offset, $return_method, $assoc_key);
		return $data;
	}

	// --------------------------------------------------------------------
	
	/**
	 * This method takes an associative array with the key values that map to CodeIgniter active record methods and returns a query result object.
	 * 
	 * For more advanced, use CI Active Record. Below are the key values you can pass:
	<ul>
		<li><strong>select</strong></li>
		<li><strong>from</strong></li>
		<li><strong>join</strong></li>
		<li><strong>where</strong></li>
		<li><strong>or_where</strong></li>
		<li><strong>where_in</strong></li>
		<li><strong>or_where_in</strong></li>
		<li><strong>where_not_in</strong></li>
		<li><strong>or_where_not_in</strong></li>
		<li><strong>like</strong></li>
		<li><strong>or_like</strong></li>
		<li><strong>not_like</strong></li>
		<li><strong>or_not_like</strong></li>
		<li><strong>group_by</strong></li>
		<li><strong>order_by</strong></li>
		<li><strong>limit</strong></li>
		<li><strong>offset</strong></li>
	</ul>
	
	 *
	 <code>
	$where['select'] = 'id, name, published';
	$where['where'] = array('published' => 'yes');
	$where['order_by'] = 'name asc';
	$where['limit'] = 10;

	$query = $this->examples_model->query($where); 
	$results = $query->result(); 
	</code>
	 *
	 * @access	public
	 * @param	array	an array of parameters to create a query (optional)
	 * @param	boolean	determines whether to execute the query and return the results or not
	 * @return	array
	 */	
	public function query($params = array(), $exec = TRUE)
	{
		if (is_array($params))
		{
			$defaults = array(
				'select'          => $this->table_name.'.*',
				'from'            => $this->table_name,
				'join'            => array(),
				'where'           => array(),
				'or_where'        => array(),
				'where_in'        => array(),
				'or_where_in'     => array(),
				'where_not_in'    => array(),
				'or_where_not_in' => array(),
				'like'            => array(),
				'or_like'         => array(),
				'not_like'        => array(),
				'or_not_like'     => array(),
				'group_by'        => NULL,
				'order_by'        => NULL,
				'limit'           => NULL,
				'offset'          => NULL
				);

			$defaults2 = array(
				'join',
				'from',
				'where',
				'or_where',
				'where_in',
				'or_where_in',
				'where_not_in',
				'or_where_not_in',
				'like',
				'or_like',
				'not_like',
				'or_not_like'
				);

			// merge params with defaults
			$params = array_merge($defaults, $params);
			
			// add joins
			if (!empty($params['join'][0]))
			{
				$join_select = '';
				if (is_array($params['join'][0]))
				{
					foreach($params['join'] as $join)
					{
						if (empty($join[2]))
						{
							$join[2] = 'left';
						}
						$this->db->join($join[0], $join[1], $join[2]);
						$join_select .= ', '.$this->db->safe_select($join[0]);
					}
				} 
				else 
				{
					if (empty($params['join'][2]))
					{
						$params['join'][2] = 'left';
					}
					$this->db->join($params['join'][0], $params['join'][1], $params['join'][2]);
					$join_select .= ', '.$this->db->safe_select($params['join'][0]);
				}

				//if (empty($params['select'])) $params['select'] = $join_select;
				$params['select'] = $params['select'].$join_select;
			}

			// select
			if (!empty($params['select'])) $this->db->select($params['select'], FALSE);
			if (!empty($params['join_select'])) $this->db->select($join_select, FALSE);

			// from
			if ($params['from'] != $this->table_name)
			{
				$this->db->from($params['from']);
			}

			// loop through list above to set params
			foreach($defaults2 as $val)
			{
				if ($val == 'where_in' OR $val == 'or_where_in' OR $val == 'where_not_in' OR $val == 'or_where_not_in')
				{
					foreach($params[$val] as $key => $val2)
					{
						$this->db->$val($key, $val2);
					}
				}
				else if ($val != 'join' AND $val != 'from' AND $val != 'order_by')
				{
					if (!empty($params[$val])) 
					{
						if (is_array($params[$val]))
						{
							$this->db->$val($params[$val]);
						}
						else
						{
							$this->db->$val($params[$val]);
						}
					}
				}
			}

			// group by
			if (!empty($params['group_by'])) $this->db->group_by($params['group_by']);

			//order by
			if (!empty($params['order_by'])) 
			{
				if (is_array($params['order_by'])) 
				{
					foreach($params['order_by'] as $val) 
					{
						$order_by = explode(' ', trim($val));
						$this->db->order_by($order_by[0], $order_by[1]);
					}
				} 
				else 
				{
					$this->db->order_by($params['order_by']);
				}
			}
			
			if ( ! empty($params['limit']))
			{
				$this->db->limit($params['limit']);
			}
			if ( ! empty($params['offset']))
			{
				$this->db->offset($params['offset']);
			}

			if ($exec === FALSE)
			{
				return;
			}

			$results = $this->get();

		} 
		else 
		{
			$results = $this->get();
		}
		return $results;
	}
	
	// --------------------------------------------------------------------
	
	/**
	 * Get the results of a query as an associative array... good for form option lists
	 *
	 <code>
	$where['published'] = 'yes'; 
	$order = 'name, desc'; 
	$examples_list = $this->examples_model->options_list('id', 'name', $where, $order); 
	</code>
	 *
	 * @access	public
	 * @param	string	the column to use for the value (optional)
	 * @param	string	the column to use for the label (optional)
	 * @param	mixed	an array or string containing the where parameters of a query (optional)
	 * @param	mixed	the order by of the query. Defaults to TRUE which means it will sort by $val asc (optional)
	 * @return	array
	 */	
	public function options_list($key = NULL, $val = NULL, $where = array(), $order = TRUE)
	{
		if (empty($key))
		{
			if (!is_array($this->key_field))
			{
				$key = $this->key_field;
			}
		}
		if (strpos($key, '.') === FALSE AND strpos($key, '(') === FALSE)
		{
			$key = $this->table_name().'.'.$key;
		}

		if (empty($val))
		{
			$fields = $this->fields();
			$val = $fields[1];
		}
		
		if (strpos($val, '.') === FALSE AND strpos($val, '(') === FALSE)
		{
			$val = $this->table_name().'.'.$val;
		}

		// don't need extra model sql stuff so just use normal active record'
		if (!empty($order) AND is_bool($order))
		{
			$this->db->order_by($val, 'asc');
		} 
		else if (!empty($order) AND is_string($order))
		{
			if (strpos($order, ' ') === FALSE) $order .= ' asc';
			$this->db->order_by($order);
		}
		$this->db->select($key.', '.$val, FALSE);
		
		if (!empty($where))
		{
			$this->db->where($where);
		}
		
		$query = $this->db->get($this->table_name);
		
		$key_arr = explode('.', $key);
		$clean_key = $key_arr[(count($key_arr) - 1)];
		if (!empty($query))
		{
			$results = $query->result_assoc_array($clean_key);
			return $results;
		}
		return FALSE;
	}
	
	// --------------------------------------------------------------------
	
	/**
	 * Determine if a record exists in the database
	 *
	 <code>
	$where['type'] = 'A'; 
	if ($this->examples_model->record_exists($where))
	{
		echo 'record exists';
	} 
	</code>
	 *
	 * @access	public
	 * @param	mixed	an array or string containing the where parameters of a query
	 * @return	boolean
	 */	
	public function record_exists($where)
	{
		$query = $this->db->get_where($this->table_name, $where);
		return ($query->num_rows() != 0);
	}
	
	// --------------------------------------------------------------------
	
	/**
	 * Create a new record if a custom record object exists
	 *
	 <code>
	$example = $this->examples_model->create($_POST); // Be sure to always clean your $_POST variables before using them
	</code>
	 *
	 * @access	public
	 * @param	mixed	the record oject associated with this class (optional)
	 * @return	boolean
	 */	
	public function create($values = array())
	{
		$record_class = $this->record_class_name();
		if (class_exists($record_class))
		{
			$record = new $record_class();
			$record->initialize($this, $this->table_info());

			// call on_create hook
			$values = $this->on_create($values);
			if (!empty($values)) $record->fill($values);
			return $record;
		}
		else
		{
			throw new Exception(lang('error_could_not_find_record_class', get_class($this)));
		}
	}
	
	// --------------------------------------------------------------------
	
	/**
	 * Will first look for a record with the past values and if it doesn't exist, will create a new one
	 *
	 <code>
	$example = $this->examples_model->find_or_create(array('slug' => 'the-force'));
	</code>
	 *
	 * @access	public
	 * @param	array	an array of values to first search for and if they don't exist, will create a new record
	 * @return	boolean
	 */	
	public function find_or_create($values = array())
	{
		$record = $this->find_one($values);
		$key_field = $this->key_field();
		if (!isset($record->$key_field))
		{
			$record = $this->create($values);
		}
		return $record;
	}

	// --------------------------------------------------------------------
	
	/**
	 * Clean the data before saving
	 *
	 <code>
	$cleaned_data = $this->examples_model->clean($_POST); // Be sure to always clean your $_POST variables before using them
	</code>
	 *
	 * @access	public
	 * @param	mixed	an array of values to be saved (optional)
	 * @param	boolean	run on_before_clean hook or not (optional)
	 * @return	array
	 */	
	public function clean($values = array(), $run_hook = FALSE)
	{
		$CI =& get_instance();
		if (empty($values)) $values = $CI->input->post();

		$original_values = $values;

		// run clean hook
		if ($run_hook)
		{
			$values = $this->on_before_clean($values);
		}
		
		// get table information to clean against
		$fields = $this->table_info();

		$clean = array();
		$values = array();
		foreach($fields as $key => $val)
		{
			if (is_array($original_values) AND array_key_exists($key, $original_values))
			{
				$values[$key] = ($this->auto_trim AND is_string($original_values[$key])) ? trim($original_values[$key]) : $original_values[$key];
			}
			// add the date fields if they don't exist to the values array
			elseif(is_array($original_values) AND !array_key_exists($key, $original_values) AND (in_array($key, $this->auto_date_add) OR in_array($key, $this->auto_date_update)))
			{
				$values[$key] = NULL;
			}
		}
		
		// process linked fields
		$values = $this->process_linked($values);
		
		foreach ($values as $key => $field)
		{
			$field = $fields[$key];

			if ($field['type'] == 'date' OR $field['type'] == 'datetime')
			{
				if (empty($values[$key]) OR (int)$values[$key] == 0) $values[$key] = $this->default_date;
				if (!empty($values[$key]) AND !is_date_db_format($values[$key])) $values[$key] = english_date_to_db_format($values[$key]);
			}

			$date_func = ($this->date_use_gmt) ? 'gmdate' : 'date';

			// create dates for date added and last updated fields automatically
			$is_date_field_type = ($field['type'] == 'datetime' OR $field['type'] == 'timestamp' OR $field['type'] == 'date');
			if ($is_date_field_type AND in_array($key, $this->auto_date_add))
			{
				$test_date = (isset($values[$key])) ? (int) $values[$key] : 0;
				
				// if no key field then we assume it is a new save and so we add the date if it's empty'
				if (!$this->_has_key_field_value($values) AND empty($test_date))
				{
					$values[$key] = ($field['type'] == 'date') ? $date_func('Y-m-d') : $date_func('Y-m-d H:i:s');
				}
			} 
			else if ($is_date_field_type AND in_array($key, $this->auto_date_update))
			{
				$values[$key] = ($field['type'] == 'date') ? $date_func('Y-m-d') : $date_func('Y-m-d H:i:s');
			}
			
			if (is_array($values) AND array_key_exists($key, $values))
			{
				
				// format dates
				if (!in_array($key, $this->auto_date_add))
				{	
					if ($field['type'] == 'datetime' OR $field['type'] == 'timestamp' OR $field['type'] == 'date')
					{
						if (isset($values[$key]) AND strncmp($values[$key], '0000', 4) !== 0)
						{
							if ($field['type'] == 'date')
							{
								$values[$key] = ($values[$key] != 'invalid') ? $date_func('Y-m-d', strtotime($values[$key])) : $this->default_date;
							}
							else
							{
								$values[$key] = ($values[$key] != 'invalid') ? $date_func('Y-m-d H:i:s', strtotime($values[$key])) : $this->default_date;
							}
						}

						
						// set it to an empty string an not a 0 so that it will work with the required validator
						if (empty($values[$key]))
						{
							$values[$key] = NULL;
						}

					} 
				}
				
				// safe_htmlspecialchars is buggy for unserialize so we use the encode_and_clean
				if (is_string($values[$key]))
				{
					$values[$key] = $this->encode_and_clean($values[$key], NULL, $key);
				}
				else if (is_array($values[$key]))
				{
					array_walk_recursive($values[$key], array($this, 'encode_and_clean'), $key);
				}

				
				$clean[$key] = $values[$key];
			}
		}
		$this->cleaned_data = $clean;
		return $clean;
	}

	public function encode_and_clean(&$val, $k, $key = NULL)
	{
		if (empty($key))
		{
			$key = $k;
		}

		if (is_string($val))
		{
			if ($this->auto_encode_entities)
			{
				if ((is_array($this->auto_encode_entities) AND in_array($key, $this->auto_encode_entities))
					OR (is_string($this->auto_encode_entities) AND $key == $this->auto_encode_entities)
					OR ($this->auto_encode_entities === TRUE)
				)
				{
					$val = safe_htmlentities($val);
				}
			}

			if ($this->xss_clean)
			{
				if ((is_array($this->xss_clean) AND in_array($key, $this->xss_clean))
					OR (is_string($this->xss_clean) AND $key == $this->xss_clean)
					OR ($this->xss_clean === TRUE)
				)
				{
					$val = xss_clean(($val));
				}
			}
		}
		return $val;
	}
	
	// --------------------------------------------------------------------
	
	/**
	 * Get the cleaned data 
	 *
	 <code>
	$cleaned_data = $this->examples_model->cleaned_data();
	</code>
	 *
	 * @access	public
	 * @return	array
	 */	
	public function cleaned_data()
	{
		return $this->cleaned_data;
	}

	// --------------------------------------------------------------------

	/**
	 * Returns number of query results
	 *
	 <code>
	$where['published'] = 'yes';
	echo $this->examples_model->record_count($where); // displays the number of records
	</code>
	 *
	 * @access	public
	 * @param	mixed	where condition (optional)
	 * @return	int
	 */
	public function record_count($where = array())
	{
		$this->_handle_where($where);
		$query = $this->db->get($this->table_name);
		return $query->num_rows();
	}

	// --------------------------------------------------------------------
	
	/**
	 * Returns number of records in the table
	 *
	 <code>
	$total_count = $this->examples_model->total_record_count();
	</code>
	 *
	 * @access	public
	 * @return	int
	 */	
	public function total_record_count()
	{
		return $this->db->count_all($this->table_name);
	}
	
	// --------------------------------------------------------------------
	
	/**
	 * Saves record object, or array of data to the database
	 *
	 <code>
	$this->examples_model->save($_POST, TRUE, TRUE); // Be sure to always clean your $_POST variables before using them
	</code>
	 *
	 * @access	public
	 * @param	mixed	an array or object to save to the database
	 * @param	boolean	validate the data before saving
	 * @param	boolean	ignore duplicate records on insert
	 * @return	mixed
	 */	
	public function save($record = NULL, $validate = TRUE, $ignore_on_insert = TRUE, $clear_related = NULL)
	{
		$this->_check_readonly();
		$CI =& get_instance();
		if (!isset($record)) $record = $CI->input->post();
		if ($this->_is_nested_array($record))
		{
			$saved = TRUE;
			foreach($record as $rec)
			{
				if(!$this->save($rec, $validate, $ignore_on_insert, $clear_related))
				{
					$saved = FALSE;
					$this->_nested_errors = $this->get_errors();
				}
			}
			
			if (!empty($this->_nested_errors))
			{
				$this->add_error($this->_nested_errors);
			}

			return $saved;
		}
		else
		{
			$fields = array();
			
			$old_clear_related_on_save = $this->clear_related_on_save;

			if (isset($clear_related))
			{
				$this->clear_related_on_save = $clear_related;
			}

			$values = $this->normalize_save_values($record);

			// reset validator here so that all validation set with hooks will not be lost
			$this->validator->reset();
			
			// clean the data before saving. on_before_clean hook now runs in the clean() method
			$values = $this->on_before_clean($values);
			$values = $this->clean($values);
			$values = $this->on_before_validate($values);

			// now validate. on_before_validate hook now runs inside validate() method
			$validated = ($validate) ? $this->validate($values) : TRUE;

			if ($validated AND !empty($values))
			{
				// now clean the data to be ready for database saving
				$this->db->set($values);
				
				if ($ignore_on_insert)
				{
					// execute on_before_insert/update hook methods
					$values = $this->on_before_save($values);
					
					// process serialized values
					$values = $this->serialize_field_values($values);
					
					if (!$this->_has_key_field_value($values))
					{
						$values = $this->on_before_insert($values);
					}
					else
					{
						$values = $this->on_before_update($values);
					}
					$insert_key = ($this->has_auto_increment) ? $this->key_field : NULL;
					
					$this->db->insert_ignore($this->table_name, $values, $insert_key);

					// execute on_insert/update hook methods
					$no_key = FALSE;
					$insert_id = $this->db->insert_id();
					if (!$this->_has_key_field_value($values) AND $insert_id)
					{
						$no_key = TRUE;
						if (is_string($this->key_field))
						{
							$values[$this->key_field] = $insert_id;
						}
						$this->on_after_insert($values);
					}
					else
					{
						$this->on_after_update($values);
					}

					// execute on_insert/update hook methods on the Date_record model if exists
					if (is_object($record) AND ($record instanceof Data_record))
					{
						if ($no_key)
						{
							$record->on_after_insert($values);
						}
						else
						{
							$record->on_after_update($values);
						}
					}
				}
				else if (!$this->_has_key_field_value($values))
				{           	
					// execute on_before_insert/update hook methods
					$values = $this->on_before_save($values);
					$values = $this->on_before_insert($values);
					
					// process serialized values
					$values = $this->serialize_field_values($values);
					
					$this->db->insert($this->table_name, $values);
					$insert_id = $this->db->insert_id();
					if (is_string($this->key_field))
					{
						$values[$this->key_field] = $insert_id;
					}
					$this->on_after_insert($values);
					if ($record instanceof Data_record)
					{
						$record->on_after_insert($values);
					}
				}
				else
				{
					$key_field = (array) $this->key_field;
					foreach($key_field as $key)
					{
						$this->db->where($key, $values[$key]);
					}
					
					$values = $this->on_before_save($values);
					$values = $this->on_before_update($values);
					
					// process serialized values
					$values = $this->serialize_field_values($values);
					
					$this->db->update($this->table_name, $values);
					$this->on_after_update($values);
					if ($record instanceof Data_record)
					{
						$record->on_after_update();
					}
				}
			} 
			else
			{
				return FALSE;
			}
			
			// returns the key value of the record upon save
			if (isset($insert_id) AND ! empty($insert_id))
			{
				$return = $insert_id;
				$this->_last_saved_id = $insert_id;
			}
			else
			{
				if ($record instanceof Data_record)
				{
					$key_field = $this->key_field;
					if (is_string($this->key_field))
					{
						$return = $record->$key_field;
					}
					else
					{
						$return = array();
						foreach($key_field as $key)
						{
							$return[$key] = $record->$key;
						}
					}
				} 
				else if (is_string($this->key_field) AND !empty($values[$this->key_field]))
				{
					$return = $values[$this->key_field];
				}
				else if (is_array($this->key_field))
				{
					$return = array();
					foreach($key_field as $key)
					{
						$return[$key] = $values[$key_field];
					}
				}
				else
				{
					$return = TRUE;
					// not valid test because a save could happen and no data is changed
					//return (bool)($this->db->affected_rows()) ? TRUE : FALSE;
				}
			}

			$this->on_after_save($values);

			// set this back to the old value
			$this->clear_related_on_save = $old_clear_related_on_save;

			// check for errors here in case some are thrown in the hooks
			if ($this->has_error())
			{
				return FALSE;
			}
			return $return;
		}
	}

	// --------------------------------------------------------------------
	
	/**
	 * Returns the last saved record
	 *
	 <code>
	 $this->examples_model->save($values);
	 $record = $this->saved();
	</code>
	 *
	 * @access public
	 * @return object
	 */
	public function saved()
	{
		if (!empty($this->_last_saved))
		{
			if (!is_object($this->_last_saved) AND !is_array($this->_last_saved))
			{
				$this->_last_saved = $this->find_by_key($this->_last_saved);	
			}
			return $this->_last_saved;
		}
	}

	// --------------------------------------------------------------------
	
	/**
	 * Save related data to a many to many table. To be used in on_after_save hook
	 *
	 <code>
	$this->examples_model->save_related('examples_to_categories', array('example_id' => $obj->id), array('categories_id' => $_POST['categories']));
	</code>
	 *
	 * @access	public
	 * @param	mixed	the model to save to
	 * @param	array	key is the column name, and value is the value to save
	 * @param	array	key is the column name, and the array of data to iterate over and save
	 * @return	boolean
	 */	
	public function save_related($model, $key_field, $data)
	{
		$this->_check_readonly();
		
		$CI =& get_instance();
		$model = $this->load_model($model);

		$id = current($key_field);
		$key_field = key($key_field);

		$other_field = key($data);
		$data = current($data);
		
		// first remove all the articles
		$CI->$model->delete(array($key_field => $id));
		
		// then read them
		$return = TRUE;
		foreach($data as $val)
		{
			$d = $CI->$model->create();
			$d->$key_field = $id;
			$d->$other_field = $val;
			if ($d->save())
			{
				$return = FALSE;
			}
		}
		return $return;
	}

	// --------------------------------------------------------------------
	
	/**
	 * Handles grabbing of the related data's keys
	 *
	 <code>
	</code>
	 *
	 * @access public
	 * @param array $values
	 * @param string $related_model
	 * @param string $mode, has_many or belongs_to (optional)
	 * @return array
	 */
	public function get_related_keys($related_field, $values, $related_model, $mode = 'has_many', $rel_config = '')
	{
		$CI =& get_instance();
		$use_rel_tbl = $this->is_using_relationship_table($rel_config);
		$fields = $this->relat…