diff options
Diffstat (limited to 'vendor/j4mie/idiorm/idiorm.php')
| -rw-r--r-- | vendor/j4mie/idiorm/idiorm.php | 2539 |
1 files changed, 2539 insertions, 0 deletions
diff --git a/vendor/j4mie/idiorm/idiorm.php b/vendor/j4mie/idiorm/idiorm.php new file mode 100644 index 000000000..2b1f38ca0 --- /dev/null +++ b/vendor/j4mie/idiorm/idiorm.php @@ -0,0 +1,2539 @@ +<?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($values) + * @method \ORM selectManyExpr($values) + * @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|array $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); + } + } + + /** + * Close and delete all registered PDO objects in _db array. + */ + public static function reset_db() { + self::$_db = null; + + 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. + * + * The join_operator should be one of INNER, LEFT OUTER, CROSS etc - this + * will be prepended to JOIN. + * + * The table should be the name of the table to join to. + * + * The constraint may be either a string or an array with three elements. If it + * is a string, it will be compiled into the query as-is, with no escaping. The + * recommended way to supply the constraint is as an array with three elements: + * + * first_column, operator, second_column + * + * Example: array('user.id', '=', 'profile.user_id') + * + * will compile to + * + * ON `user`.`id` = `profile`.`user_id` + * + * The final (optional) argument specifies an alias for the joined table. + */ + protected function _add_join_source($join_operator, $table, $constraint, $table_alias=null) { + + $join_operator = trim("{$join_operator} JOIN"); + + $table = $this->_quote_identifier($table); + + // Add table alias if present + if (!is_null($table_alias)) { + $table_alias = $this->_quote_identifier($table_alias); + $table .= " {$table_alias}"; + } + + // Build the constraint + if (is_array($constraint)) { + list($first_column, $operator, $second_column) = $constraint; + $first_column = $this->_quote_identifier($first_column); + $second_column = $this->_quote_identifier($second_column); + $constraint = "{$first_column} {$operator} {$second_column}"; + } + + $this->_join_sources[] = "{$join_operator} {$table} ON {$constraint}"; + return $this; + } + + /** + * Add a RAW JOIN source to the query + */ + public function raw_join($table, $constraint, $table_alias, $parameters = array()) { + // Add table alias if present + if (!is_null($table_alias)) { + $table_alias = $this->_quote_identifier($table_alias); + $table .= " {$table_alias}"; + } + + $this->_values = array_merge($this->_values, $parameters); + + // Build the constraint + if (is_array($constraint)) { + list($first_column, $operator, $second_column) = $constraint; + $first_column = $this->_quote_identifier($first_column); + $second_column = $this->_quote_identifier($second_column); + $constraint = "{$first_column} {$operator} {$second_column}"; + } + + $this->_join_sources[] = "{$table} ON {$constraint}"; + return $this; + } + + /** + * Add a simple JOIN source to the query + */ + public function join($table, $constraint, $table_alias=null) { + return $this->_add_join_source("", $table, $constraint, $table_alias); + } + + /** + * Add an INNER JOIN souce to the query + */ + public function inner_join($table, $constraint, $table_alias=null) { + return $this->_add_join_source("INNER", $table, $constraint, $table_alias); + } + + /** + * Add a LEFT OUTER JOIN souce to the query + */ + public function left_outer_join($table, $constraint, $table_alias=null) { + return $this->_add_join_source("LEFT OUTER", $table, $constraint, $table_alias); + } + + /** + * Add an RIGHT OUTER JOIN souce to the query + */ + public function right_outer_join($table, $constraint, $table_alias=null) { + return $this->_add_join_source("RIGHT OUTER", $table, $constraint, $table_alias); + } + + /** + * Add an FULL OUTER JOIN souce to the query + */ + public function full_outer_join($table, $constraint, $table_alias=null) { + return $this->_add_join_source("FULL OUTER", $table, $constraint, $table_alias); + } + + /** + * Internal method to add a HAVING condition to the query + */ + protected function _add_having($fragment, $values=array()) { + return $this->_add_condition('having', $fragment, $values); + } + + /** + * Internal method to add a HAVING condition to the query + */ + protected function _add_simple_having($column_name, $separator, $value) { + return $this->_add_simple_condition('having', $column_name, $separator, $value); + } + + /** + * Internal method to add a HAVING clause with multiple values (like IN and NOT IN) + */ + public function _add_having_placeholder($column_name, $separator, $values) { + if (!is_array($column_name)) { + $data = array($column_name => $values); + } else { + $data = $column_name; + } + $result = $this; + foreach ($data as $key => $val) { + $column = $result->_quote_identifier($key); + $placeholders = $result->_create_placeholders($val); + $result = $result->_add_having("{$column} {$separator} ({$placeholders})", $val); + } + return $result; + } + + /** + * Internal method to add a HAVING clause with no parameters(like IS NULL and IS NOT NULL) + */ + public function _add_having_no_value($column_name, $operator) { + $conditions = (is_array($column_name)) ? $column_name : array($column_name); + $result = $this; + foreach($conditions as $column) { + $column = $this->_quote_identifier($column); + $result = $result->_add_having("{$column} {$operator}"); + } + return $result; + } + + /** + * Internal method to add a WHERE condition to the query + */ + protected function _add_where($fragment, $values=array()) { + return $this->_add_condition('where', $fragment, $values); + } + + /** + * Internal method to add a WHERE condition to the query + */ + protected function _add_simple_where($column_name, $separator, $value) { + return $this->_add_simple_condition('where', $column_name, $separator, $value); + } + + /** + * Add a WHERE clause with multiple values (like IN and NOT IN) + */ + public function _add_where_placeholder($column_name, $separator, $values) { + if (!is_array($column_name)) { + $data = array($column_name => $values); + } else { + $data = $column_name; + } + $result = $this; + foreach ($data as $key => $val) { + $column = $result->_quote_identifier($key); + $placeholders = $result->_create_placeholders($val); + $result = $result->_add_where("{$column} {$separator} ({$placeholders})", $val); + } + return $result; + } + + /** + * Add a WHERE clause with no parameters(like IS NULL and IS NOT NULL) + */ + public function _add_where_no_value($column_name, $operator) { + $conditions = (is_array($column_name)) ? $column_name : array($column_name); + $result = $this; + foreach($conditions as $column) { + $column = $this->_quote_identifier($column); + $result = $result->_add_where("{$column} {$operator}"); + } + return $result; + } + + /** + * Internal method to add a HAVING or WHERE condition to the query + */ + protected function _add_condition($type, $fragment, $values=array()) { + $conditions_class_property_name = "_{$type}_conditions"; + if (!is_array($values)) { + $values = array($values); + } + array_push($this->$conditions_class_property_name, array( + self::CONDITION_FRAGMENT => $fragment, + self::CONDITION_VALUES => $values, + )); + return $this; + } + + /** + * Helper method to compile a simple COLUMN SEPARATOR VALUE + * style HAVING or WHERE condition into a string and value ready to + * be passed to the _add_condition method. Avoids duplication + * of the call to _quote_identifier + * + * If column_name is an associative array, it will add a condition for each column + */ + protected function _add_simple_condition($type, $column_name, $separator, $value) { + $multiple = is_array($column_name) ? $column_name : array($column_name => $value); + $result = $this; + + foreach($multiple as $key => $val) { + // Add the table name in case of ambiguous columns + if (count($result->_join_sources) > 0 && strpos($key, '.') === false) { + $table = $result->_table_name; + if (!is_null($result->_table_alias)) { + $table = $result->_table_alias; + } + + $key = "{$table}.{$key}"; + } + $key = $result->_quote_identifier($key); + $result = $result->_add_condition($type, "{$key} {$separator} ?", $val); + } + return $result; + } + + /** + * Return a string containing the given number of question marks, + * separated by commas. Eg "?, ?, ?" + */ + protected function _create_placeholders($fields) { + if(!empty($fields)) { + $db_fields = array(); + foreach($fields as $key => $value) { + // Process expression fields directly into the query + if(array_key_exists($key, $this->_expr_fields)) { + $db_fields[] = $value; + } else { + $db_fields[] = '?'; + } + } + return implode(', ', $db_fields); + } + } + + /** + * Helper method that filters a column/value array returning only those + * columns that belong to a compound primary key. + * + * If the key contains a column that does not exist in the given array, + * a null value will be returned for it. + */ + protected function _get_compound_id_column_values($value) { + $filtered = array(); + foreach($this->_get_id_column_name() as $key) { + $filtered[$key] = isset($value[$key]) ? $value[$key] : null; + } + return $filtered; + } + + /** + * Helper method that filters an array containing compound column/value + * arrays. + */ + protected function _get_compound_id_column_values_array($values) { + $filtered = array(); + foreach($values as $value) { + $filtered[] = $this->_get_compound_id_column_values($value); + } + return $filtered; + } + + /** + * Add a WHERE column = value clause to your query. Each time + * this is called in the chain, an additional WHERE will be + * added, and these will be ANDed together when the final query + * is built. + * + * If you use an array in $column_name, a new clause will be + * added for each element. In this case, $value is ignored. + */ + public function where($column_name, $value=null) { + return $this->where_equal($column_name, $value); + } + + /** + * More explicitly named version of for the where() method. + * Can be used if preferred. + */ + public function where_equal($column_name, $value=null) { + return $this->_add_simple_where($column_name, '=', $value); + } + + /** + * Add a WHERE column != value clause to your query. + */ + public function where_not_equal($column_name, $value=null) { + return $this->_add_simple_where($column_name, '!=', $value); + } + + /** + * Special method to query the table by its primary key + * + * If primary key is compound, only the columns that + * belong to they key will be used for the query + */ + public function where_id_is($id) { + return (is_array($this->_get_id_column_name())) ? + $this->where($this->_get_compound_id_column_values($id), null) : + $this->where($this->_get_id_column_name(), $id); + } + + /** + * Allows adding a WHERE clause that matches any of the conditions + * specified in the array. Each element in the associative array will + * be a different condition, where the key will be the column name. + * + * By default, an equal operator will be used against all columns, but + * it can be overriden for any or every column using the second parameter. + * + * Each condition will be ORed together when added to the final query. + */ + public function where_any_is($values, $operator='=') { + $data = array(); + $query = array("(("); + $first = true; + foreach ($values as $value) { + if ($first) { + $first = false; + } else { + $query[] = ") OR ("; + } + $firstsub = true; + foreach($value as $key => $item) { + $op = is_string($operator) ? $operator : (isset($operator[$key]) ? $operator[$key] : '='); + if ($firstsub) { + $firstsub = false; + } else { + $query[] = "AND"; + } + $query[] = $this->_quote_identifier($key); + $data[] = $item; + $query[] = $op . " ?"; + } + } + $query[] = "))"; + return $this->where_raw(join(' ', $query), $data); + } + + /** + * Similar to where_id_is() but allowing multiple primary keys. + * + * If primary key is compound, only the columns that + * belong to they key will be used for the query + */ + public function where_id_in($ids) { + return (is_array($this->_get_id_column_name())) ? + $this->where_any_is($this->_get_compound_id_column_values_array($ids)) : + $this->where_in($this->_get_id_column_name(), $ids); + } + + /** + * Add a WHERE ... LIKE clause to your query. + */ + public function where_like($column_name, $value=null) { + return $this->_add_simple_where($column_name, 'LIKE', $value); + } + + /** + * Add where WHERE ... NOT LIKE clause to your query. + */ + public function where_not_like($column_name, $value=null) { + return $this->_add_simple_where($column_name, 'NOT LIKE', $value); + } + + /** + * Add a WHERE ... > clause to your query + */ + public function where_gt($column_name, $value=null) { + return $this->_add_simple_where($column_name, '>', $value); + } + + /** + * Add a WHERE ... < clause to your query + */ + public function where_lt($column_name, $value=null) { + return $this->_add_simple_where($column_name, '<', $value); + } + + /** + * Add a WHERE ... >= clause to your query + */ + public function where_gte($column_name, $value=null) { + return $this->_add_simple_where($column_name, '>=', $value); + } + + /** + * Add a WHERE ... <= clause to your query + */ + public function where_lte($column_name, $value=null) { + return $this->_add_simple_where($column_name, '<=', $value); + } + + /** + * Add a WHERE ... IN clause to your query + */ + public function where_in($column_name, $values) { + return $this->_add_where_placeholder($column_name, 'IN', $values); + } + + /** + * Add a WHERE ... NOT IN clause to your query + */ + public function where_not_in($column_name, $values) { + return $this->_add_where_placeholder($column_name, 'NOT IN', $values); + } + + /** + * Add a WHERE column IS NULL clause to your query + */ + public function where_null($column_name) { + return $this->_add_where_no_value($column_name, "IS NULL"); + } + + /** + * Add a WHERE column IS NOT NULL clause to your query + */ + public function where_not_null($column_name) { + return $this->_add_where_no_value($column_name, "IS NOT NULL"); + } + + /** + * Add a raw WHERE clause to the query. The clause should + * contain question mark placeholders, which will be bound + * to the parameters supplied in the second argument. + */ + public function where_raw($clause, $parameters=array()) { + return $this->_add_where($clause, $parameters); + } + + /** + * Add a LIMIT to the query + */ + public function limit($limit) { + $this->_limit = $limit; + return $this; + } + + /** + * Add an OFFSET to the query + */ + public function offset($offset) { + $this->_offset = $offset; + return $this; + } + + /** + * Add an ORDER BY clause to the query + */ + protected function _add_order_by($column_name, $ordering) { + $column_name = $this->_quote_identifier($column_name); + $this->_order_by[] = "{$column_name} {$ordering}"; + return $this; + } + + /** + * Add an ORDER BY column DESC clause + */ + public function order_by_desc($column_name) { + return $this->_add_order_by($column_name, 'DESC'); + } + + /** + * Add an ORDER BY column ASC clause + */ + public function order_by_asc($column_name) { + return $this->_add_order_by($column_name, 'ASC'); + } + + /** + * Add an unquoted expression as an ORDER BY clause + */ + public function order_by_expr($clause) { + $this->_order_by[] = $clause; + return $this; + } + + /** + * Add a column to the list of columns to GROUP BY + */ + public function group_by($column_name) { + $column_name = $this->_quote_identifier($column_name); + $this->_group_by[] = $column_name; + return $this; + } + + /** + * Add an unquoted expression to the list of columns to GROUP BY + */ + public function group_by_expr($expr) { + $this->_group_by[] = $expr; + return $this; + } + + /** + * Add a HAVING column = value clause to your query. Each time + * this is called in the chain, an additional HAVING will be + * added, and these will be ANDed together when the final query + * is built. + * + * If you use an array in $column_name, a new clause will be + * added for each element. In this case, $value is ignored. + */ + public function having($column_name, $value=null) { + return $this->having_equal($column_name, $value); + } + + /** + * More explicitly named version of for the having() method. + * Can be used if preferred. + */ + public function having_equal($column_name, $value=null) { + return $this->_add_simple_having($column_name, '=', $value); + } + + /** + * Add a HAVING column != value clause to your query. + */ + public function having_not_equal($column_name, $value=null) { + return $this->_add_simple_having($column_name, '!=', $value); + } + + /** + * Special method to query the table by its primary key. + * + * If primary key is compound, only the columns that + * belong to they key will be used for the query + */ + public function having_id_is($id) { + return (is_array($this->_get_id_column_name())) ? + $this->having($this->_get_compound_id_column_values($id), null) : + $this->having($this->_get_id_column_name(), $id); + } + + /** + * Add a HAVING ... LIKE clause to your query. + */ + public function having_like($column_name, $value=null) { + return $this->_add_simple_having($column_name, 'LIKE', $value); + } + + /** + * Add where HAVING ... NOT LIKE clause to your query. + */ + public function having_not_like($column_name, $value=null) { + return $this->_add_simple_having($column_name, 'NOT LIKE', $value); + } + + /** + * Add a HAVING ... > clause to your query + */ + public function having_gt($column_name, $value=null) { + return $this->_add_simple_having($column_name, '>', $value); + } + + /** + * Add a HAVING ... < clause to your query + */ + public function having_lt($column_name, $value=null) { + return $this->_add_simple_having($column_name, '<', $value); + } + + /** + * Add a HAVING ... >= clause to your query + */ + public function having_gte($column_name, $value=null) { + return $this->_add_simple_having($column_name, '>=', $value); + } + + /** + * Add a HAVING ... <= clause to your query + */ + public function having_lte($column_name, $value=null) { + return $this->_add_simple_having($column_name, '<=', $value); + } + + /** + * Add a HAVING ... IN clause to your query + */ + public function having_in($column_name, $values=null) { + return $this->_add_having_placeholder($column_name, 'IN', $values); + } + + /** + * Add a HAVING ... NOT IN clause to your query + */ + public function having_not_in($column_name, $values=null) { + return $this->_add_having_placeholder($column_name, 'NOT IN', $values); + } + + /** + * Add a HAVING column IS NULL clause to your query + */ + public function having_null($column_name) { + return $this->_add_having_no_value($column_name, 'IS NULL'); + } + + /** + * Add a HAVING column IS NOT NULL clause to your query + */ + public function having_not_null($column_name) { + return $this->_add_having_no_value($column_name, 'IS NOT NULL'); + } + + /** + * Add a raw HAVING clause to the query. The clause should + * contain question mark placeholders, which will be bound + * to the parameters supplied in the second argument. + */ + public function having_raw($clause, $parameters=array()) { + return $this->_add_having($clause, $parameters); + } + + /** + * Build a SELECT statement based on the clauses that have + * been passed to this instance by chaining method calls. + */ + protected function _build_select() { + // If the query is raw, just set the $this->_values to be + // the raw query parameters and return the raw query + if ($this->_is_raw_query) { + $this->_values = $this->_raw_parameters; + return $this->_raw_query; + } + + // Build and return the full SELECT statement by concatenating + // the results of calling each separate builder method. + return $this->_join_if_not_empty(" ", array( + $this->_build_select_start(), + $this->_build_join(), + $this->_build_where(), + $this->_build_group_by(), + $this->_build_having(), + $this->_build_order_by(), + $this->_build_limit(), + $this->_build_offset(), + )); + } + + /** + * Build the start of the SELECT statement + */ + protected function _build_select_start() { + $fragment = 'SELECT '; + $result_columns = join(', ', $this->_result_columns); + + if (!is_null($this->_limit) && + self::$_config[$this->_connection_name]['limit_clause_style'] === ORM::LIMIT_STYLE_TOP_N) { + $fragment .= "TOP {$this->_limit} "; + } + + if ($this->_distinct) { + $result_columns = 'DISTINCT ' . $result_columns; + } + + $fragment .= "{$result_columns} FROM " . $this->_quote_identifier($this->_table_name); + + if (!is_null($this->_table_alias)) { + $fragment .= " " . $this->_quote_identifier($this->_table_alias); + } + return $fragment; + } + + /** + * Build the JOIN sources + */ + protected function _build_join() { + if (count($this->_join_sources) === 0) { + return ''; + } + + return join(" ", $this->_join_sources); + } + + /** + * Build the WHERE clause(s) + */ + protected function _build_where() { + return $this->_build_conditions('where'); + } + + /** + * Build the HAVING clause(s) + */ + protected function _build_having() { + return $this->_build_conditions('having'); + } + + /** + * Build GROUP BY + */ + protected function _build_group_by() { + if (count($this->_group_by) === 0) { + return ''; + } + return "GROUP BY " . join(", ", $this->_group_by); + } + + /** + * Build a WHERE or HAVING clause + * @param string $type + * @return string + */ + protected function _build_conditions($type) { + $conditions_class_property_name = "_{$type}_conditions"; + // If there are no clauses, return empty string + if (count($this->$conditions_class_property_name) === 0) { + return ''; + } + + $conditions = array(); + foreach ($this->$conditions_class_property_name as $condition) { + $conditions[] = $condition[self::CONDITION_FRAGMENT]; + $this->_values = array_merge($this->_values, $condition[self::CONDITION_VALUES]); + } + + return strtoupper($type) . " " . join(" AND ", $conditions); + } + + /** + * Build ORDER BY + */ + protected function _build_order_by() { + if (count($this->_order_by) === 0) { + return ''; + } + return "ORDER BY " . join(", ", $this->_order_by); + } + + /** + * Build LIMIT + */ + protected function _build_limit() { + $fragment = ''; + if (!is_null($this->_limit) && + self::$_config[$this->_connection_name]['limit_clause_style'] == ORM::LIMIT_STYLE_LIMIT) { + if (self::get_db($this->_connection_name)->getAttribute(PDO::ATTR_DRIVER_NAME) == 'firebird') { + $fragment = 'ROWS'; + } else { + $fragment = 'LIMIT'; + } + $fragment .= " {$this->_limit}"; + } + return $fragment; + } + + /** + * Build OFFSET + */ + protected function _build_offset() { + if (!is_null($this->_offset)) { + $clause = 'OFFSET'; + if (self::get_db($this->_connection_name)->getAttribute(PDO::ATTR_DRIVER_NAME) == 'firebird') { + $clause = 'TO'; + } + return "$clause " . $this->_offset; + } + return ''; + } + + /** + * Wrapper around PHP's join function which + * only adds the pieces if they are not empty. + */ + protected function _join_if_not_empty($glue, $pieces) { + $filtered_pieces = array(); + foreach ($pieces as $piece) { + if (is_string($piece)) { + $piece = trim($piece); + } + if (!empty($piece)) { + $filtered_pieces[] = $piece; + } + } + return join($glue, $filtered_pieces); + } + + /** + * Quote a string that is used as an identifier + * (table names, column names etc). This method can + * also deal with dot-separated identifiers eg table.column + */ + protected function _quote_one_identifier($identifier) { + $parts = explode('.', $identifier); + $parts = array_map(array($this, '_quote_identifier_part'), $parts); + return join('.', $parts); + } + + /** + * Quote a string that is used as an identifier + * (table names, column names etc) or an array containing + * multiple identifiers. This method can also deal with + * dot-separated identifiers eg table.column + */ + protected function _quote_identifier($identifier) { + if (is_array($identifier)) { + $result = array_map(array($this, '_quote_one_identifier'), $identifier); + return join(', ', $result); + } else { + return $this->_quote_one_identifier($identifier); + } + } + + /** + * This method performs the actual quoting of a single + * part of an identifier, using the identifier quote + * character specified in the config (or autodetected). + */ + protected function _quote_identifier_part($part) { + if ($part === '*') { + return $part; + } + + $quote_character = self::$_config[$this->_connection_name]['identifier_quote_character']; + // double up any identifier quotes to escape them + return $quote_character . + str_replace($quote_character, + $quote_character . $quote_character, + $part + ) . $quote_character; + } + + /** + * Create a cache key for the given query and parameters. + */ + protected static function _create_cache_key($query, $parameters, $table_name = null, $connection_name = self::DEFAULT_CONNECTION) { + if(isset(self::$_config[$connection_name]['create_cache_key']) and is_callable(self::$_config[$connection_name]['create_cache_key'])){ + return call_user_func_array(self::$_config[$connection_name]['create_cache_key'], array($query, $parameters, $table_name, $connection_name)); + } + $parameter_string = join(',', $parameters); + $key = $query . ':' . $parameter_string; + return sha1($key); + } + + /** + * Check the query cache for the given cache key. If a value + * is cached for the key, return the value. Otherwise, return false. + */ + protected static function _check_query_cache($cache_key, $table_name = null, $connection_name = self::DEFAULT_CONNECTION) { + if(isset(self::$_config[$connection_name]['check_query_cache']) and is_callable(self::$_config[$connection_name]['check_query_cache'])){ + return call_user_func_array(self::$_config[$connection_name]['check_query_cache'], array($cache_key, $table_name, $connection_name)); + } elseif (isset(self::$_query_cache[$connection_name][$cache_key])) { + return self::$_query_cache[$connection_name][$cache_key]; + } + return false; + } + + /** + * Clear the query cache + */ + public static function clear_cache($table_name = null, $connection_name = self::DEFAULT_CONNECTION) { + self::$_query_cache = array(); + if(isset(self::$_config[$connection_name]['clear_cache']) and is_callable(self::$_config[$connection_name]['clear_cache'])){ + return call_user_func_array(self::$_config[$connection_name]['clear_cache'], array($table_name, $connection_name)); + } + } + + /** + * Add the given value to the query cache. + */ + protected static function _cache_query_result($cache_key, $value, $table_name = null, $connection_name = self::DEFAULT_CONNECTION) { + if(isset(self::$_config[$connection_name]['cache_query_result']) and is_callable(self::$_config[$connection_name]['cache_query_result'])){ + return call_user_func_array(self::$_config[$connection_name]['cache_query_result'], array($cache_key, $value, $table_name, $connection_name)); + } elseif (!isset(self::$_query_cache[$connection_name])) { + self::$_query_cache[$connection_name] = array(); + } + self::$_query_cache[$connection_name][$cache_key] = $value; + } + + /** + * Execute the SELECT query that has been built up by chaining methods + * on this class. Return an array of rows as associative arrays. + */ + protected function _run() { + $query = $this->_build_select(); + $caching_enabled = self::$_config[$this->_connection_name]['caching']; + + if ($caching_enabled) { + $cache_key = self::_create_cache_key($query, $this->_values, $this->_table_name, $this->_connection_name); + $cached_result = self::_check_query_cache($cache_key, $this->_table_name, $this->_connection_name); + + if ($cached_result !== false) { + $this->_reset_idiorm_state(); + return $cached_result; + } + } + + self::_execute($query, $this->_values, $this->_connection_name); + $statement = self::get_last_statement(); + + $rows = array(); + while ($row = $statement->fetch(PDO::FETCH_ASSOC)) { + $rows[] = $row; + } + + if ($caching_enabled) { + self::_cache_query_result($cache_key, $rows, $this->_table_name, $this->_connection_name); + } + + $this->_reset_idiorm_state(); + return $rows; + } + + /** + * Reset the Idiorm instance state + */ + private function _reset_idiorm_state() { + $this->_values = array(); + $this->_result_columns = array('*'); + $this->_using_default_result_columns = true; + } + + /** + * Return the raw data wrapped by this ORM + * instance as an associative array. Column + * names may optionally be supplied as arguments, + * if so, only those keys will be returned. + */ + public function as_array() { + if (func_num_args() === 0) { + return $this->_data; + } + $args = func_get_args(); + return array_intersect_key($this->_data, array_flip($args)); + } + + /** + * Return the value of a property of this object (database row) + * or null if not present. + * + * If a column-names array is passed, it will return a associative array + * with the value of each column or null if it is not present. + */ + public function get($key) { + if (is_array($key)) { + $result = array(); + foreach($key as $column) { + $result[$column] = isset($this->_data[$column]) ? $this->_data[$column] : null; + } + return $result; + } else { + return isset($this->_data[$key]) ? $this->_data[$key] : null; + } + } + + /** + * Return the name of the column in the database table which contains + * the primary key ID of the row. + */ + protected function _get_id_column_name() { + if (!is_null($this->_instance_id_column)) { + return $this->_instance_id_column; + } + if (isset(self::$_config[$this->_connection_name]['id_column_overrides'][$this->_table_name])) { + return self::$_config[$this->_connection_name]['id_column_overrides'][$this->_table_name]; + } + return self::$_config[$this->_connection_name]['id_column']; + } + + /** + * Get the primary key ID of this object. + */ + public function id($disallow_null = false) { + $id = $this->get($this->_get_id_column_name()); + + if ($disallow_null) { + if (is_array($id)) { + foreach ($id as $id_part) { + if ($id_part === null) { + throw new Exception('Primary key ID contains null value(s)'); + } + } + } else if ($id === null) { + throw new Exception('Primary key ID missing from row or is null'); + } + } + + return $id; + } + + /** + * Set a property to a particular value on this object. + * To set multiple properties at once, pass an associative array + * as the first parameter and leave out the second parameter. + * Flags the properties as 'dirty' so they will be saved to the + * database when save() is called. + */ + public function set($key, $value = null) { + return $this->_set_orm_property($key, $value); + } + + /** + * Set a property to a particular value on this object. + * To set multiple properties at once, pass an associative array + * as the first parameter and leave out the second parameter. + * Flags the properties as 'dirty' so they will be saved to the + * database when save() is called. + * @param string|array $key + * @param string|null $value + */ + public function set_expr($key, $value = null) { + return $this->_set_orm_property($key, $value, true); + } + + /** + * Set a property on the ORM object. + * @param string|array $key + * @param string|null $value + * @param bool $raw Whether this value should be treated as raw or not + */ + protected function _set_orm_property($key, $value = null, $expr = false) { + if (!is_array($key)) { + $key = array($key => $value); + } + foreach ($key as $field => $value) { + $this->_data[$field] = $value; + $this->_dirty_fields[$field] = $value; + if (false === $expr and isset($this->_expr_fields[$field])) { + unset($this->_expr_fields[$field]); + } else if (true === $expr) { + $this->_expr_fields[$field] = true; + } + } + return $this; + } + + /** + * Check whether the given field has been changed since this + * object was saved. + */ + public function is_dirty($key) { + return array_key_exists($key, $this->_dirty_fields); + } + + /** + * Check whether the model was the result of a call to create() or not + * @return bool + */ + public function is_new() { + return $this->_is_new; + } + + /** + * Save any fields which have been modified on this object + * to the database. + */ + public function save() { + $query = array(); + + // remove any expression fields as they are already baked into the query + $values = array_values(array_diff_key($this->_dirty_fields, $this->_expr_fields)); + + if (!$this->_is_new) { // UPDATE + // If there are no dirty values, do nothing + if (empty($values) && empty($this->_expr_fields)) { + return true; + } + $query = $this->_build_update(); + $id = $this->id(true); + if (is_array($id)) { + $values = array_merge($values, array_values($id)); + } else { + $values[] = $id; + } + } else { // INSERT + $query = $this->_build_insert(); + } + + $success = self::_execute($query, $values, $this->_connection_name); + $caching_auto_clear_enabled = self::$_config[$this->_connection_name]['caching_auto_clear']; + if($caching_auto_clear_enabled){ + self::clear_cache($this->_table_name, $this->_connection_name); + } + // If we've just inserted a new record, set the ID of this object + if ($this->_is_new) { + $this->_is_new = false; + if ($this->count_null_id_columns() != 0) { + $db = self::get_db($this->_connection_name); + if($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'pgsql') { + // it may return several columns if a compound primary + // key is used + $row = self::get_last_statement()->fetch(PDO::FETCH_ASSOC); + foreach($row as $key => $value) { + $this->_data[$key] = $value; + } + } else { + $column = $this->_get_id_column_name(); + // if the primary key is compound, assign the last inserted id + // to the first column + if (is_array($column)) { + $column = reset($column); + } + $this->_data[$column] = $db->lastInsertId(); + } + } + } + + $this->_dirty_fields = $this->_expr_fields = array(); + return $success; + } + + /** + * Add a WHERE clause for every column that belongs to the primary key + */ + public function _add_id_column_conditions(&$query) { + $query[] = "WHERE"; + $keys = is_array($this->_get_id_column_name()) ? $this->_get_id_column_name() : array( $this->_get_id_column_name() ); + $first = true; + foreach($keys as $key) { + if ($first) { + $first = false; + } + else { + $query[] = "AND"; + } + $query[] = $this->_quote_identifier($key); + $query[] = "= ?"; + } + } + + /** + * Build an UPDATE query + */ + protected function _build_update() { + $query = array(); + $query[] = "UPDATE {$this->_quote_identifier($this->_table_name)} SET"; + + $field_list = array(); + foreach ($this->_dirty_fields as $key => $value) { + if(!array_key_exists($key, $this->_expr_fields)) { + $value = '?'; + } + $field_list[] = "{$this->_quote_identifier($key)} = $value"; + } + $query[] = join(", ", $field_list); + $this->_add_id_column_conditions($query); + return join(" ", $query); + } + + /** + * Build an INSERT query + */ + protected function _build_insert() { + $query[] = "INSERT INTO"; + $query[] = $this->_quote_identifier($this->_table_name); + $field_list = array_map(array($this, '_quote_identifier'), array_keys($this->_dirty_fields)); + $query[] = "(" . join(", ", $field_list) . ")"; + $query[] = "VALUES"; + + $placeholders = $this->_create_placeholders($this->_dirty_fields); + $query[] = "({$placeholders})"; + + if (self::get_db($this->_connection_name)->getAttribute(PDO::ATTR_DRIVER_NAME) == 'pgsql') { + $query[] = 'RETURNING ' . $this->_quote_identifier($this->_get_id_column_name()); + } + + return join(" ", $query); + } + + /** + * Delete this record from the database + */ + public function delete() { + $query = array( + "DELETE FROM", + $this->_quote_identifier($this->_table_name) + ); + $this->_add_id_column_conditions($query); + return self::_execute(join(" ", $query), is_array($this->id(true)) ? array_values($this->id(true)) : array($this->id(true)), $this->_connection_name); + } + + /** + * Delete many records from the database + */ + public function delete_many() { + // Build and return the full DELETE statement by concatenating + // the results of calling each separate builder method. + $query = $this->_join_if_not_empty(" ", array( + "DELETE FROM", + $this->_quote_identifier($this->_table_name), + $this->_build_where(), + )); + + return self::_execute($query, $this->_values, $this->_connection_name); + } + + // --------------------- // + // --- ArrayAccess --- // + // --------------------- // + + public function offsetExists($key) { + return array_key_exists($key, $this->_data); + } + + public function offsetGet($key) { + return $this->get($key); + } + + public function offsetSet($key, $value) { + if(is_null($key)) { + throw new InvalidArgumentException('You must specify a key/array index.'); + } + $this->set($key, $value); + } + + public function offsetUnset($key) { + unset($this->_data[$key]); + unset($this->_dirty_fields[$key]); + } + + // --------------------- // + // --- MAGIC METHODS --- // + // --------------------- // + public function __get($key) { + return $this->offsetGet($key); + } + + public function __set($key, $value) { + $this->offsetSet($key, $value); + } + + public function __unset($key) { + $this->offsetUnset($key); + } + + + public function __isset($key) { + return $this->offsetExists($key); + } + + /** + * Magic method to capture calls to undefined class methods. + * In this case we are attempting to convert camel case formatted + * methods into underscore formatted methods. + * + * This allows us to call ORM methods using camel case and remain + * backwards compatible. + * + * @param string $name + * @param array $arguments + * @return ORM + */ + public function __call($name, $arguments) + { + $method = strtolower(preg_replace('/([a-z])([A-Z])/', '$1_$2', $name)); + + if (method_exists($this, $method)) { + return call_user_func_array(array($this, $method), $arguments); + } else { + throw new IdiormMethodMissingException("Method $name() does not exist in class " . get_class($this)); + } + } + + /** + * Magic method to capture calls to undefined static class methods. + * In this case we are attempting to convert camel case formatted + * methods into underscore formatted methods. + * + * This allows us to call ORM methods using camel case and remain + * backwards compatible. + * + * @param string $name + * @param array $arguments + * @return ORM + */ + public static function __callStatic($name, $arguments) + { + $method = strtolower(preg_replace('/([a-z])([A-Z])/', '$1_$2', $name)); + + return call_user_func_array(array('ORM', $method), $arguments); + } + } + + /** + * A class to handle str_replace operations that involve quoted strings + * @example IdiormString::str_replace_outside_quotes('?', '%s', 'columnA = "Hello?" AND columnB = ?'); + * @example IdiormString::value('columnA = "Hello?" AND columnB = ?')->replace_outside_quotes('?', '%s'); + * @author Jeff Roberson <[email protected]> + * @author Simon Holywell <[email protected]> + * @link http://stackoverflow.com/a/13370709/461813 StackOverflow answer + */ + class IdiormString { + protected $subject; + protected $search; + protected $replace; + + /** + * Get an easy to use instance of the class + * @param string $subject + * @return \self + */ + public static function value($subject) { + return new self($subject); + } + + /** + * Shortcut method: Replace all occurrences of the search string with the replacement + * string where they appear outside quotes. + * @param string $search + * @param string $replace + * @param string $subject + * @return string + */ + public static function str_replace_outside_quotes($search, $replace, $subject) { + return self::value($subject)->replace_outside_quotes($search, $replace); + } + + /** + * Set the base string object + * @param string $subject + */ + public function __construct($subject) { + $this->subject = (string) $subject; + } + + /** + * Replace all occurrences of the search string with the replacement + * string where they appear outside quotes + * @param string $search + * @param string $replace + * @return string + */ + public function replace_outside_quotes($search, $replace) { + $this->search = $search; + $this->replace = $replace; + return $this->_str_replace_outside_quotes(); + } + + /** + * Validate an input string and perform a replace on all ocurrences + * of $this->search with $this->replace + * @author Jeff Roberson <[email protected]> + * @link http://stackoverflow.com/a/13370709/461813 StackOverflow answer + * @return string + */ + protected function _str_replace_outside_quotes(){ + $re_valid = '/ + # Validate string having embedded quoted substrings. + ^ # Anchor to start of string. + (?: # Zero or more string chunks. + "[^"\\\\]*(?:\\\\.[^"\\\\]*)*" # Either a double quoted chunk, + | \'[^\'\\\\]*(?:\\\\.[^\'\\\\]*)*\' # or a single quoted chunk, + | [^\'"\\\\]+ # or an unquoted chunk (no escapes). + )* # Zero or more string chunks. + \z # Anchor to end of string. + /sx'; + if (!preg_match($re_valid, $this->subject)) { + throw new IdiormStringException("Subject string is not valid in the replace_outside_quotes context."); + } + $re_parse = '/ + # Match one chunk of a valid string having embedded quoted substrings. + ( # Either $1: Quoted chunk. + "[^"\\\\]*(?:\\\\.[^"\\\\]*)*" # Either a double quoted chunk, + | \'[^\'\\\\]*(?:\\\\.[^\'\\\\]*)*\' # or a single quoted chunk. + ) # End $1: Quoted chunk. + | ([^\'"\\\\]+) # or $2: an unquoted chunk (no escapes). + /sx'; + return preg_replace_callback($re_parse, array($this, '_str_replace_outside_quotes_cb'), $this->subject); + } + + /** + * Process each matching chunk from preg_replace_callback replacing + * each occurrence of $this->search with $this->replace + * @author Jeff Roberson <[email protected]> + * @link http://stackoverflow.com/a/13370709/461813 StackOverflow answer + * @param array $matches + * @return string + */ + protected function _str_replace_outside_quotes_cb($matches) { + // Return quoted string chunks (in group $1) unaltered. + if ($matches[1]) return $matches[1]; + // Process only unquoted chunks (in group $2). + return preg_replace('/'. preg_quote($this->search, '/') .'/', + $this->replace, $matches[2]); + } + } + + /** + * A result set class for working with collections of model instances + * @author Simon Holywell <[email protected]> + * @method null setResults(array $results) + * @method array getResults() + */ + class IdiormResultSet implements Countable, IteratorAggregate, ArrayAccess, Serializable { + /** + * The current result set as an array + * @var array + */ + protected $_results = array(); + + /** + * Optionally set the contents of the result set by passing in array + * @param array $results + */ + public function __construct(array $results = array()) { + $this->set_results($results); + } + + /** + * Set the contents of the result set by passing in array + * @param array $results + */ + public function set_results(array $results) { + $this->_results = $results; + } + + /** + * Get the current result set as an array + * @return array + */ + public function get_results() { + return $this->_results; + } + + /** + * Get the current result set as an array + * @return array + */ + public function as_array() { + return $this->get_results(); + } + + /** + * Get the number of records in the result set + * @return int + */ + public function count() { + return count($this->_results); + } + + /** + * Get an iterator for this object. In this case it supports foreaching + * over the result set. + * @return \ArrayIterator + */ + public function getIterator() { + return new ArrayIterator($this->_results); + } + + /** + * ArrayAccess + * @param int|string $offset + * @return bool + */ + public function offsetExists($offset) { + return isset($this->_results[$offset]); + } + + /** + * ArrayAccess + * @param int|string $offset + * @return mixed + */ + public function offsetGet($offset) { + return $this->_results[$offset]; + } + + /** + * ArrayAccess + * @param int|string $offset + * @param mixed $value + */ + public function offsetSet($offset, $value) { + $this->_results[$offset] = $value; + } + + /** + * ArrayAccess + * @param int|string $offset + */ + public function offsetUnset($offset) { + unset($this->_results[$offset]); + } + + /** + * Serializable + * @return string + */ + public function serialize() { + return serialize($this->_results); + } + + /** + * Serializable + * @param string $serialized + * @return array + */ + public function unserialize($serialized) { + return unserialize($serialized); + } + + /** + * Call a method on all models in a result set. This allows for method + * chaining such as setting a property on all models in a result set or + * any other batch operation across models. + * @example ORM::for_table('Widget')->find_many()->set('field', 'value')->save(); + * @param string $method + * @param array $params + * @return \IdiormResultSet + */ + public function __call($method, $params = array()) { + foreach($this->_results as $model) { + if (method_exists($model, $method)) { + call_user_func_array(array($model, $method), $params); + } else { + throw new IdiormMethodMissingException("Method $method() does not exist in class " . get_class($this)); + } + } + return $this; + } + } + + /** + * A placeholder for exceptions eminating from the IdiormString class + */ + class IdiormStringException extends Exception {} + + class IdiormMethodMissingException extends Exception {} |