<?php

/**

*

* Idiorm

*

* http://github.com/j4mie/idiorm/

*

* A single-class super-simple database abstraction layer for PHP.

* Provides (nearly) zero-configuration object-relational mapping

* and a fluent interface for building basic, commonly-used queries.

*

* BSD Licensed.

*

* Copyright (c) 2010, Jamie Matthews

* All rights reserved.

*

* Redistribution and use in source and binary forms, with or without

* modification, are permitted provided that the following conditions are met:

*

* * Redistributions of source code must retain the above copyright notice, this

* list of conditions and the following disclaimer.

*

* * Redistributions in binary form must reproduce the above copyright notice,

* this list of conditions and the following disclaimer in the documentation

* and/or other materials provided with the distribution.

*

* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE

* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR

* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER

* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*

*

* The methods documented below are magic methods that conform to PSR-1.

* This documentation exposes these methods to doc generators and IDEs.

* @see http://www.php-fig.org/psr/psr-1/

*

* @method static array|string getConfig($key = null, $connection_name = self::DEFAULT_CONNECTION)

* @method static null resetConfig()

* @method static \ORM forTable($table_name, $connection_name = self::DEFAULT_CONNECTION)

* @method static null setDb($db, $connection_name = self::DEFAULT_CONNECTION)

* @method static null resetDb()

* @method static null setupLimitClauseStyle($connection_name)

* @method static \PDO getDb($connection_name = self::DEFAULT_CONNECTION)

* @method static bool rawExecute($query, $parameters = array())

* @method static \PDOStatement getLastStatement()

* @method static string getLastQuery($connection_name = null)

* @method static array getQueryLog($connection_name = self::DEFAULT_CONNECTION)

* @method array getConnectionNames()

* @method $this useIdColumn($id_column)

* @method \ORM|bool findOne($id=null)

* @method array|\IdiormResultSet findMany()

* @method \IdiormResultSet findResultSet()

* @method array findArray()

* @method $this forceAllDirty()

* @method $this rawQuery($query, $parameters = array())

* @method $this tableAlias($alias)

* @method int countNullIdColumns()

* @method $this selectExpr($expr, $alias=null)

* @method \ORM selectMany()

* @method \ORM selectManyExpr()

* @method $this rawJoin($table, $constraint, $table_alias, $parameters = array())

* @method $this innerJoin($table, $constraint, $table_alias=null)

* @method $this leftOuterJoin($table, $constraint, $table_alias=null)

* @method $this rightOuterJoin($table, $constraint, $table_alias=null)

* @method $this fullOuterJoin($table, $constraint, $table_alias=null)

* @method $this whereEqual($column_name, $value=null)

* @method $this whereNotEqual($column_name, $value=null)

* @method $this whereIdIs($id)

* @method $this whereAnyIs($values, $operator='=')

* @method array|string whereIdIn($ids)

* @method $this whereLike($column_name, $value=null)

* @method $this whereNotLike($column_name, $value=null)

* @method $this whereGt($column_name, $value=null)

* @method $this whereLt($column_name, $value=null)

* @method $this whereGte($column_name, $value=null)

* @method $this whereLte($column_name, $value=null)

* @method $this whereIn($column_name, $values)

* @method $this whereNotIn($column_name, $values)

* @method $this whereNull($column_name)

* @method $this whereNotNull($column_name)

* @method $this whereRaw($clause, $parameters=array())

* @method $this orderByDesc($column_name)

* @method $this orderByAsc($column_name)

* @method $this orderByExpr($clause)

* @method $this groupBy($column_name)

* @method $this groupByExpr($expr)

* @method $this havingEqual($column_name, $value=null)

* @method $this havingNotEqual($column_name, $value=null)

* @method $this havingIdIs($id)

* @method $this havingLike($column_name, $value=null)

* @method $this havingNotLike($column_name, $value=null)

* @method $this havingGt($column_name, $value=null)

* @method $this havingLt($column_name, $value=null)

* @method $this havingGte($column_name, $value=null)

* @method $this havingLte($column_name, $value=null)

* @method $this havingIn($column_name, $values=null)

* @method $this havingNotIn($column_name, $values=null)

* @method $this havingNull($column_name)

* @method $this havingNotNull($column_name)

* @method $this havingRaw($clause, $parameters=array())

* @method static this clearCache($table_name = null, $connection_name = self::DEFAULT_CONNECTION)

* @method array asArray()

* @method bool setExpr($key, $value = null)

* @method bool isDirty($key)

* @method bool isNew()

*/

class ORM implements ArrayAccess {

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

// --- CLASS CONSTANTS --- //

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

// WHERE and HAVING condition array keys

const CONDITION_FRAGMENT = 0;

const CONDITION_VALUES = 1;

const DEFAULT_CONNECTION = 'default';

// Limit clause style

const LIMIT_STYLE_TOP_N = "top";

const LIMIT_STYLE_LIMIT = "limit";

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

// --- CLASS PROPERTIES --- //

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

// Class configuration

protected static $_default_config = array(

'connection_string' => 'sqlite::memory:',

'id_column' => 'id',

'id_column_overrides' => array(),

'error_mode' => PDO::ERRMODE_EXCEPTION,

'username' => null,

'password' => null,

'driver_options' => null,

'identifier_quote_character' => null, // if this is null, will be autodetected

'limit_clause_style' => null, // if this is null, will be autodetected

'logging' => false,

'logger' => null,

'caching' => false,

'caching_auto_clear' => false,

'return_result_sets' => false,

);

// Map of configuration settings

protected static $_config = array();

// Map of database connections, instances of the PDO class

protected static $_db = array();

// Last query run, only populated if logging is enabled

protected static $_last_query;

// Log of all queries run, mapped by connection key, only populated if logging is enabled

protected static $_query_log = array();

// Query cache, only used if query caching is enabled

protected static $_query_cache = array();

// Reference to previously used PDOStatement object to enable low-level access, if needed

protected static $_last_statement = null;

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

// --- INSTANCE PROPERTIES --- //

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

// Key name of the connections in self::$_db used by this instance

protected $_connection_name;

// The name of the table the current ORM instance is associated with

protected $_table_name;

// Alias for the table to be used in SELECT queries

protected $_table_alias = null;

// Values to be bound to the query

protected $_values = array();

// Columns to select in the result

protected $_result_columns = array('*');

// Are we using the default result column or have these been manually changed?

protected $_using_default_result_columns = true;

// Join sources

protected $_join_sources = array();

// Should the query include a DISTINCT keyword?

protected $_distinct = false;

// Is this a raw query?

protected $_is_raw_query = false;

// The raw query

protected $_raw_query = '';

// The raw query parameters

protected $_raw_parameters = array();

// Array of WHERE clauses

protected $_where_conditions = array();

// LIMIT

protected $_limit = null;

// OFFSET

protected $_offset = null;

// ORDER BY

protected $_order_by = array();

// GROUP BY

protected $_group_by = array();

// HAVING

protected $_having_conditions = array();

// The data for a hydrated instance of the class

protected $_data = array();

// Fields that have been modified during the

// lifetime of the object

protected $_dirty_fields = array();

// Fields that are to be inserted in the DB raw

protected $_expr_fields = array();

// Is this a new object (has create() been called)?

protected $_is_new = false;

// Name of the column to use as the primary key for

// this instance only. Overrides the config settings.

protected $_instance_id_column = null;

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

// --- STATIC METHODS --- //

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

/**

* Pass configuration settings to the class in the form of

* key/value pairs. As a shortcut, if the second argument

* is omitted and the key is a string, the setting is

* assumed to be the DSN string used by PDO to connect

* to the database (often, this will be the only configuration

* required to use Idiorm). If you have more than one setting

* you wish to configure, another shortcut is to pass an array

* of settings (and omit the second argument).

* @param string $key

* @param mixed $value

* @param string $connection_name Which connection to use

*/

public static function configure($key, $value = null, $connection_name = self::DEFAULT_CONNECTION) {

self::_setup_db_config($connection_name); //ensures at least default config is set

if (is_array($key)) {

// Shortcut: If only one array argument is passed,

// assume it's an array of configuration settings

foreach ($key as $conf_key => $conf_value) {

self::configure($conf_key, $conf_value, $connection_name);

}

} else {

if (is_null($value)) {

// Shortcut: If only one string argument is passed,

// assume it's a connection string

$value = $key;

$key = 'connection_string';

}

self::$_config[$connection_name][$key] = $value;

}

}

/**

* Retrieve configuration options by key, or as whole array.

* @param string $key

* @param string $connection_name Which connection to use

*/

public static function get_config($key = null, $connection_name = self::DEFAULT_CONNECTION) {

if ($key) {

return self::$_config[$connection_name][$key];

} else {

return self::$_config[$connection_name];

}

}

/**

* Delete all configs in _config array.

*/

public static function reset_config() {

self::$_config = array();

}

/**

* Despite its slightly odd name, this is actually the factory

* method used to acquire instances of the class. It is named

* this way for the sake of a readable interface, ie

* ORM::for_table('table_name')->find_one()-> etc. As such,

* this will normally be the first method called in a chain.

* @param string $table_name

* @param string $connection_name Which connection to use

* @return ORM

*/

public static function for_table($table_name, $connection_name = self::DEFAULT_CONNECTION) {

self::_setup_db($connection_name);

return new self($table_name, array(), $connection_name);

}

/**

* Set up the database connection used by the class

* @param string $connection_name Which connection to use

*/

protected static function _setup_db($connection_name = self::DEFAULT_CONNECTION) {

if (!array_key_exists($connection_name, self::$_db) ||

!is_object(self::$_db[$connection_name])) {

self::_setup_db_config($connection_name);

$db = new PDO(

self::$_config[$connection_name]['connection_string'],

self::$_config[$connection_name]['username'],

self::$_config[$connection_name]['password'],

self::$_config[$connection_name]['driver_options']

);

$db->setAttribute(PDO::ATTR_ERRMODE, self::$_config[$connection_name]['error_mode']);

self::set_db($db, $connection_name);

}

}

/**

* Ensures configuration (multiple connections) is at least set to default.

* @param string $connection_name Which connection to use

*/

protected static function _setup_db_config($connection_name) {

if (!array_key_exists($connection_name, self::$_config)) {

self::$_config[$connection_name] = self::$_default_config;

}

}

/**

* Set the PDO object used by Idiorm to communicate with the database.

* This is public in case the ORM should use a ready-instantiated

* PDO object as its database connection. Accepts an optional string key

* to identify the connection if multiple connections are used.

* @param PDO $db

* @param string $connection_name Which connection to use

*/

public static function set_db($db, $connection_name = self::DEFAULT_CONNECTION) {

self::_setup_db_config($connection_name);

self::$_db[$connection_name] = $db;

if(!is_null(self::$_db[$connection_name])) {

self::_setup_identifier_quote_character($connection_name);

self::_setup_limit_clause_style($connection_name);

}

}

/**

* Delete all registered PDO objects in _db array.

*/

public static function reset_db() {

self::$_db = array();

}

/**

* Detect and initialise the character used to quote identifiers

* (table names, column names etc). If this has been specified

* manually using ORM::configure('identifier_quote_character', 'some-char'),

* this will do nothing.

* @param string $connection_name Which connection to use

*/

protected static function _setup_identifier_quote_character($connection_name) {

if (is_null(self::$_config[$connection_name]['identifier_quote_character'])) {

self::$_config[$connection_name]['identifier_quote_character'] =

self::_detect_identifier_quote_character($connection_name);

}

}

/**

* Detect and initialise the limit clause style ("SELECT TOP 5" /

* "... LIMIT 5"). If this has been specified manually using

* ORM::configure('limit_clause_style', 'top'), this will do nothing.

* @param string $connection_name Which connection to use

*/

public static function _setup_limit_clause_style($connection_name) {

if (is_null(self::$_config[$connection_name]['limit_clause_style'])) {

self::$_config[$connection_name]['limit_clause_style'] =

self::_detect_limit_clause_style($connection_name);

}

}

/**

* Return the correct character used to quote identifiers (table

* names, column names etc) by looking at the driver being used by PDO.

* @param string $connection_name Which connection to use

* @return string

*/

protected static function _detect_identifier_quote_character($connection_name) {

switch(self::get_db($connection_name)->getAttribute(PDO::ATTR_DRIVER_NAME)) {

case 'pgsql':

case 'sqlsrv':

case 'dblib':

case 'mssql':

case 'sybase':

case 'firebird':

return '"';

case 'mysql':

case 'sqlite':

case 'sqlite2':

default:

return '`';

}

}

/**

* Returns a constant after determining the appropriate limit clause

* style

* @param string $connection_name Which connection to use

* @return string Limit clause style keyword/constant

*/

protected static function _detect_limit_clause_style($connection_name) {

switch(self::get_db($connection_name)->getAttribute(PDO::ATTR_DRIVER_NAME)) {

case 'sqlsrv':

case 'dblib':

case 'mssql':

return ORM::LIMIT_STYLE_TOP_N;

default:

return ORM::LIMIT_STYLE_LIMIT;

}

}

/**

* Returns the PDO instance used by the the ORM to communicate with

* the database. This can be called if any low-level DB access is

* required outside the class. If multiple connections are used,

* accepts an optional key name for the connection.

* @param string $connection_name Which connection to use

* @return PDO

*/

public static function get_db($connection_name = self::DEFAULT_CONNECTION) {

self::_setup_db($connection_name); // required in case this is called before Idiorm is instantiated

return self::$_db[$connection_name];

}

/**

* Executes a raw query as a wrapper for PDOStatement::execute.

* Useful for queries that can't be accomplished through Idiorm,

* particularly those using engine-specific features.

* @example raw_execute('SELECT `name`, AVG(`order`) FROM `customer` GROUP BY `name` HAVING AVG(`order`) > 10')

* @example raw_execute('INSERT OR REPLACE INTO `widget` (`id`, `name`) SELECT `id`, `name` FROM `other_table`')

* @param string $query The raw SQL query

* @param array $parameters Optional bound parameters

* @param string $connection_name Which connection to use

* @return bool Success

*/

public static function raw_execute($query, $parameters = array(), $connection_name = self::DEFAULT_CONNECTION) {

self::_setup_db($connection_name);

return self::_execute($query, $parameters, $connection_name);

}

/**

* Returns the PDOStatement instance last used by any connection wrapped by the ORM.

* Useful for access to PDOStatement::rowCount() or error information

* @return PDOStatement

*/

public static function get_last_statement() {

return self::$_last_statement;

}

/**

* Internal helper method for executing statments. Logs queries, and

* stores statement object in ::_last_statment, accessible publicly

* through ::get_last_statement()

* @param string $query

* @param array $parameters An array of parameters to be bound in to the query

* @param string $connection_name Which connection to use

* @return bool Response of PDOStatement::execute()

*/

protected static function _execute($query, $parameters = array(), $connection_name = self::DEFAULT_CONNECTION) {

$statement = self::get_db($connection_name)->prepare($query);

self::$_last_statement = $statement;

$time = microtime(true);

foreach ($parameters as $key => &$param) {

if (is_null($param)) {

$type = PDO::PARAM_NULL;

} else if (is_bool($param)) {

$type = PDO::PARAM_BOOL;

} else if (is_int($param)) {

$type = PDO::PARAM_INT;

} else {

$type = PDO::PARAM_STR;

}

$statement->bindParam(is_int($key) ? ++$key : $key, $param, $type);

}

$q = $statement->execute();

self::_log_query($query, $parameters, $connection_name, (microtime(true)-$time));

return $q;

}

/**

* Add a query to the internal query log. Only works if the

* 'logging' config option is set to true.

*

* This works by manually binding the parameters to the query - the

* query isn't executed like this (PDO normally passes the query and

* parameters to the database which takes care of the binding) but

* doing it this way makes the logged queries more readable.

* @param string $query

* @param array $parameters An array of parameters to be bound in to the query

* @param string $connection_name Which connection to use

* @param float $query_time Query time

* @return bool

*/

protected static function _log_query($query, $parameters, $connection_name, $query_time) {

// If logging is not enabled, do nothing

if (!self::$_config[$connection_name]['logging']) {

return false;

}

if (!isset(self::$_query_log[$connection_name])) {

self::$_query_log[$connection_name] = array();

}

if (empty($parameters)) {

$bound_query = $query;

} else {

// Escape the parameters

$parameters = array_map(array(self::get_db($connection_name), 'quote'), $parameters);

if (array_values($parameters) === $parameters) {

// ? placeholders

// Avoid %format collision for vsprintf

$query = str_replace("%", "%%", $query);

// Replace placeholders in the query for vsprintf

if(false !== strpos($query, "'") || false !== strpos($query, '"')) {

$query = IdiormString::str_replace_outside_quotes("?", "%s", $query);

} else {

$query = str_replace("?", "%s", $query);

}

// Replace the question marks in the query with the parameters

$bound_query = vsprintf($query, $parameters);

} else {

// named placeholders

foreach ($parameters as $key => $val) {

$query = str_replace($key, $val, $query);

}

$bound_query = $query;

}

}

self::$_last_query = $bound_query;

self::$_query_log[$connection_name][] = $bound_query;

if(is_callable(self::$_config[$connection_name]['logger'])){

$logger = self::$_config[$connection_name]['logger'];

$logger($bound_query, $query_time);

}

return true;

}

/**

* Get the last query executed. Only works if the

* 'logging' config option is set to true. Otherwise

* this will return null. Returns last query from all connections if

* no connection_name is specified

* @param null|string $connection_name Which connection to use

* @return string

*/

public static function get_last_query($connection_name = null) {

if ($connection_name === null) {

return self::$_last_query;

}

if (!isset(self::$_query_log[$connection_name])) {

return '';

}

return end(self::$_query_log[$connection_name]);

}

/**

* Get an array containing all the queries run on a

* specified connection up to now.

* Only works if the 'logging' config option is

* set to true. Otherwise, returned array will be empty.

* @param string $connection_name Which connection to use

*/

public static function get_query_log($connection_name = self::DEFAULT_CONNECTION) {

if (isset(self::$_query_log[$connection_name])) {

return self::$_query_log[$connection_name];

}

return array();

}

/**

* Get a list of the available connection names

* @return array

*/

public static function get_connection_names() {

return array_keys(self::$_db);

}

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

// --- INSTANCE METHODS --- //

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

/**

* "Private" constructor; shouldn't be called directly.

* Use the ORM::for_table factory method instead.

*/

protected function __construct($table_name, $data = array(), $connection_name = self::DEFAULT_CONNECTION) {

$this->_table_name = $table_name;

$this->_data = $data;

$this->_connection_name = $connection_name;

self::_setup_db_config($connection_name);

}

/**

* Create a new, empty instance of the class. Used

* to add a new row to your database. May optionally

* be passed an associative array of data to populate

* the instance. If so, all fields will be flagged as

* dirty so all will be saved to the database when

* save() is called.

*/

public function create($data=null) {

$this->_is_new = true;

if (!is_null($data)) {

return $this->hydrate($data)->force_all_dirty();

}

return $this;

}

/**

* Specify the ID column to use for this instance or array of instances only.

* This overrides the id_column and id_column_overrides settings.

*

* This is mostly useful for libraries built on top of Idiorm, and will

* not normally be used in manually built queries. If you don't know why

* you would want to use this, you should probably just ignore it.

*/

public function use_id_column($id_column) {

$this->_instance_id_column = $id_column;

return $this;

}

/**

* Create an ORM instance from the given row (an associative

* array of data fetched from the database)

*/

protected function _create_instance_from_row($row) {

$instance = self::for_table($this->_table_name, $this->_connection_name);

$instance->use_id_column($this->_instance_id_column);

$instance->hydrate($row);

return $instance;

}

/**

* Tell the ORM that you are expecting a single result

* back from your query, and execute it. Will return

* a single instance of the ORM class, or false if no

* rows were returned.

* As a shortcut, you may supply an ID as a parameter

* to this method. This will perform a primary key

* lookup on the table.

*/

public function find_one($id=null) {

if (!is_null($id)) {

$this->where_id_is($id);

}

$this->limit(1);

$rows = $this->_run();

if (empty($rows)) {

return false;

}

return $this->_create_instance_from_row($rows[0]);

}

/**

* Tell the ORM that you are expecting multiple results

* from your query, and execute it. Will return an array

* of instances of the ORM class, or an empty array if

* no rows were returned.

* @return array|\IdiormResultSet

*/

public function find_many() {

if(self::$_config[$this->_connection_name]['return_result_sets']) {

return $this->find_result_set();

}

return $this->_find_many();

}

/**

* Tell the ORM that you are expecting multiple results

* from your query, and execute it. Will return an array

* of instances of the ORM class, or an empty array if

* no rows were returned.

* @return array

*/

protected function _find_many() {

$rows = $this->_run();

return array_map(array($this, '_create_instance_from_row'), $rows);

}

/**

* Tell the ORM that you are expecting multiple results

* from your query, and execute it. Will return a result set object

* containing instances of the ORM class.

* @return \IdiormResultSet

*/

public function find_result_set() {

return new IdiormResultSet($this->_find_many());

}

/**

* Tell the ORM that you are expecting multiple results

* from your query, and execute it. Will return an array,

* or an empty array if no rows were returned.

* @return array

*/

public function find_array() {

return $this->_run();

}

/**

* Tell the ORM that you wish to execute a COUNT query.

* Will return an integer representing the number of

* rows returned.

*/

public function count($column = '*') {

return $this->_call_aggregate_db_function(__FUNCTION__, $column);

}

/**

* Tell the ORM that you wish to execute a MAX query.

* Will return the max value of the choosen column.

*/

public function max($column) {

return $this->_call_aggregate_db_function(__FUNCTION__, $column);

}

/**

* Tell the ORM that you wish to execute a MIN query.

* Will return the min value of the choosen column.

*/

public function min($column) {

return $this->_call_aggregate_db_function(__FUNCTION__, $column);

}

/**

* Tell the ORM that you wish to execute a AVG query.

* Will return the average value of the choosen column.

*/

public function avg($column) {

return $this->_call_aggregate_db_function(__FUNCTION__, $column);

}

/**

* Tell the ORM that you wish to execute a SUM query.

* Will return the sum of the choosen column.

*/

public function sum($column) {

return $this->_call_aggregate_db_function(__FUNCTION__, $column);

}

/**

* Execute an aggregate query on the current connection.

* @param string $sql_function The aggregate function to call eg. MIN, COUNT, etc

* @param string $column The column to execute the aggregate query against

* @return int

*/

protected function _call_aggregate_db_function($sql_function, $column) {

$alias = strtolower($sql_function);

$sql_function = strtoupper($sql_function);

if('*' != $column) {

$column = $this->_quote_identifier($column);

}

$result_columns = $this->_result_columns;

$this->_result_columns = array();

$this->select_expr("$sql_function($column)", $alias);

$result = $this->find_one();

$this->_result_columns = $result_columns;

$return_value = 0;

if($result !== false && isset($result->$alias)) {

if (!is_numeric($result->$alias)) {

$return_value = $result->$alias;

}

elseif((int) $result->$alias == (float) $result->$alias) {

$return_value = (int) $result->$alias;

} else {

$return_value = (float) $result->$alias;

}

}

return $return_value;

}

/**

* This method can be called to hydrate (populate) this

* instance of the class from an associative array of data.

* This will usually be called only from inside the class,

* but it's public in case you need to call it directly.

*/

public function hydrate($data=array()) {

$this->_data = $data;

return $this;

}

/**

* Force the ORM to flag all the fields in the $data array

* as "dirty" and therefore update them when save() is called.

*/

public function force_all_dirty() {

$this->_dirty_fields = $this->_data;

return $this;

}

/**

* Perform a raw query. The query can contain placeholders in

* either named or question mark style. If placeholders are

* used, the parameters should be an array of values which will

* be bound to the placeholders in the query. If this method

* is called, all other query building methods will be ignored.

*/

public function raw_query($query, $parameters = array()) {

$this->_is_raw_query = true;

$this->_raw_query = $query;

$this->_raw_parameters = $parameters;

return $this;

}

/**

* Add an alias for the main table to be used in SELECT queries

*/

public function table_alias($alias) {

$this->_table_alias = $alias;

return $this;

}

/**

* Internal method to add an unquoted expression to the set

* of columns returned by the SELECT query. The second optional

* argument is the alias to return the expression as.

*/

protected function _add_result_column($expr, $alias=null) {

if (!is_null($alias)) {

$expr .= " AS " . $this->_quote_identifier($alias);

}

if ($this->_using_default_result_columns) {

$this->_result_columns = array($expr);

$this->_using_default_result_columns = false;

} else {

$this->_result_columns[] = $expr;

}

return $this;

}

/**

* Counts the number of columns that belong to the primary

* key and their value is null.

*/

public function count_null_id_columns() {

if (is_array($this->_get_id_column_name())) {

return count(array_filter($this->id(), 'is_null'));

} else {

return is_null($this->id()) ? 1 : 0;

}

}

/**

* Add a column to the list of columns returned by the SELECT

* query. This defaults to '*'. The second optional argument is

* the alias to return the column as.

*/

public function select($column, $alias=null) {

$column = $this->_quote_identifier($column);

return $this->_add_result_column($column, $alias);

}

/**

* Add an unquoted expression to the list of columns returned

* by the SELECT query. The second optional argument is

* the alias to return the column as.

*/

public function select_expr($expr, $alias=null) {

return $this->_add_result_column($expr, $alias);

}

/**

* Add columns to the list of columns returned by the SELECT

* query. This defaults to '*'. Many columns can be supplied

* as either an array or as a list of parameters to the method.

*

* Note that the alias must not be numeric - if you want a

* numeric alias then prepend it with some alpha chars. eg. a1

*

* @example select_many(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5');

* @example select_many('column', 'column2', 'column3');

* @example select_many(array('column', 'column2', 'column3'), 'column4', 'column5');

*

* @return \ORM

*/

public function select_many() {

$columns = func_get_args();

if(!empty($columns)) {

$columns = $this->_normalise_select_many_columns($columns);

foreach($columns as $alias => $column) {

if(is_numeric($alias)) {

$alias = null;

}

$this->select($column, $alias);

}

}

return $this;

}

/**

* Add an unquoted expression to the list of columns returned

* by the SELECT query. Many columns can be supplied as either

* an array or as a list of parameters to the method.

*

* Note that the alias must not be numeric - if you want a

* numeric alias then prepend it with some alpha chars. eg. a1

*

* @example select_many_expr(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5')

* @example select_many_expr('column', 'column2', 'column3')

* @example select_many_expr(array('column', 'column2', 'column3'), 'column4', 'column5')

*

* @return \ORM

*/

public function select_many_expr() {

$columns = func_get_args();

if(!empty($columns)) {

$columns = $this->_normalise_select_many_columns($columns);

foreach($columns as $alias => $column) {

if(is_numeric($alias)) {

$alias = null;

}

$this->select_expr($column, $alias);

}

}

return $this;

}

/**

* Take a column specification for the select many methods and convert it

* into a normalised array of columns and aliases.

*

* It is designed to turn the following styles into a normalised array:

*

* array(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5'))

*

* @param array $columns

* @return array

*/

protected function _normalise_select_many_columns($columns) {

$return = array();

foreach($columns as $column) {

if(is_array($column)) {

foreach($column as $key => $value) {

if(!is_numeric($key)) {

$return[$key] = $value;

} else {

$return[] = $value;

}

}

} else {

$return[] = $column;

}

}

return $return;

}

/**

* Add a DISTINCT keyword before the list of columns in the SELECT query

*/

public function distinct() {

$this->_distinct = true;

return $this;

}

/**

* Internal method to add a JOIN source to the query.

*