system/libraries/ORM.php

   1 <?php defined('SYSPATH') OR die('No direct access allowed.');
   2 /**
   3  * [Object Relational Mapping][ref-orm] (ORM) is a method of abstracting database
   4  * access to standard PHP calls. All table rows are represented as model objects,
   5  * with object properties representing row data. ORM in Kohana generally follows
   6  * the [Active Record][ref-act] pattern.
   7  *
   8  * [ref-orm]: http://wikipedia.org/wiki/Object-relational_mapping
   9  * [ref-act]: http://wikipedia.org/wiki/Active_record
  10  *
  11  * $Id: ORM.php 3917 2009-01-21 03:06:22Z zombor $
  12  *
  13  * @package    ORM
  14  * @author     Kohana Team
  15  * @copyright  (c) 2007-2008 Kohana Team
  16  * @license    http://kohanaphp.com/license.html
  17  */
  18 class ORM {
  19
  20         // Current relationships
  21         protected $has_one                 = array();
  22         protected $belongs_to              = array();
  23         protected $has_many                = array();
  24         protected $has_and_belongs_to_many = array();
  25
  26         // Relationships that should always be joined
  27         protected $load_with = array();
  28
  29         // Current object
  30         protected $object  = array();
  31         protected $changed = array();
  32         protected $related = array();
  33         protected $loaded  = FALSE;
  34         protected $saved   = FALSE;
  35         protected $sorting;
  36
  37         // Related objects
  38         protected $object_relations = array();
  39         protected $changed_relations = array();
  40
  41         // Model table information
  42         protected $object_name;
  43         protected $object_plural;
  44         protected $table_name;
  45         protected $table_columns;
  46         protected $ignored_columns;
  47
  48         // Table primary key and value
  49         protected $primary_key = 'id';
  50         protected $primary_val = 'name';
  51
  52         // Array of foreign key name overloads
  53         protected $foreign_key = array();
  54
  55         // Model configuration
  56         protected $table_names_plural = TRUE;
  57         protected $reload_on_wakeup   = TRUE;
  58
  59         // Database configuration
  60         protected $db = 'default';
  61         protected $db_applied = array();
  62
  63         // With calls already applied
  64         protected $with_applied = array();
  65
  66         // Stores column information for ORM models
  67         protected static $column_cache = array();
  68
  69         /**
  70          * Creates and returns a new model.
  71          *
  72          * @chainable
  73          * @param   string  model name
  74          * @param   mixed   parameter for find()
  75          * @return  ORM
  76          */
  77         public static function factory($model, $id = NULL)
  78         {
  79                 // Set class name
  80                 $model = ucfirst($model).'_Model';
  81
  82                 return new $model($id);
  83         }
  84
  85         /**
  86          * Prepares the model database connection and loads the object.
  87          *
  88          * @param   mixed  parameter for find or object to load
  89          * @return  void
  90          */
  91         public function __construct($id = NULL)
  92         {
  93                 // Set the object name and plural name
  94                 $this->object_name   = strtolower(substr(get_class($this), 0, -6));
  95                 $this->object_plural = inflector::plural($this->object_name);
  96
  97                 if (!isset($this->sorting))
  98                 {
  99                         // Default sorting
 100                         $this->sorting = array($this->primary_key => 'asc');
 101                 }
 102
 103                 // Initialize database
 104                 $this->__initialize();
 105
 106                 // Clear the object
 107                 $this->clear();
 108
 109                 if (is_object($id))
 110                 {
 111                         // Load an object
 112                         $this->load_values((array) $id);
 113                 }
 114                 elseif (!empty($id))
 115                 {
 116                         // Find an object
 117                         $this->find($id);
 118                 }
 119         }
 120
 121         /**
 122          * Prepares the model database connection, determines the table name,
 123          * and loads column information.
 124          *
 125          * @return  void
 126          */
 127         public function __initialize()
 128         {
 129                 if ( ! is_object($this->db))
 130                 {
 131                         // Get database instance
 132                         $this->db = Database::instance($this->db);
 133                 }
 134
 135                 if (empty($this->table_name))
 136                 {
 137                         // Table name is the same as the object name
 138                         $this->table_name = $this->object_name;
 139
 140                         if ($this->table_names_plural === TRUE)
 141                         {
 142                                 // Make the table name plural
 143                                 $this->table_name = inflector::plural($this->table_name);
 144                         }
 145                 }
 146
 147                 if (is_array($this->ignored_columns))
 148                 {
 149                         // Make the ignored columns mirrored = mirrored
 150                         $this->ignored_columns = array_combine($this->ignored_columns, $this->ignored_columns);
 151                 }
 152
 153                 // Load column information
 154                 $this->reload_columns();
 155         }
 156
 157         /**
 158          * Allows serialization of only the object data and state, to prevent
 159          * "stale" objects being unserialized, which also requires less memory.
 160          *
 161          * @return  array
 162          */
 163         public function __sleep()
 164         {
 165                 // Store only information about the object
 166                 return array('object_name', 'object', 'changed', 'loaded', 'saved', 'sorting');
 167         }
 168
 169         /**
 170          * Prepares the database connection and reloads the object.
 171          *
 172          * @return  void
 173          */
 174         public function __wakeup()
 175         {
 176                 // Initialize database
 177                 $this->__initialize();
 178
 179                 if ($this->reload_on_wakeup === TRUE)
 180                 {
 181                         // Reload the object
 182                         $this->reload();
 183                 }
 184         }
 185
 186         /**
 187          * Handles pass-through to database methods. Calls to query methods
 188          * (query, get, insert, update) are not allowed. Query builder methods
 189          * are chainable.
 190          *
 191          * @param   string  method name
 192          * @param   array   method arguments
 193          * @return  mixed
 194          */
 195         public function __call($method, array $args)
 196         {
 197                 if (method_exists($this->db, $method))
 198                 {
 199                         if (in_array($method, array('query', 'get', 'insert', 'update', 'delete')))
 200                                 throw new Kohana_Exception('orm.query_methods_not_allowed');
 201
 202                         // Method has been applied to the database
 203                         $this->db_applied[$method] = $method;
 204
 205                         // Number of arguments passed
 206                         $num_args = count($args);
 207
 208                         if ($method === 'select' AND $num_args > 3)
 209                         {
 210                                 // Call select() manually to avoid call_user_func_array
 211                                 $this->db->select($args);
 212                         }
 213                         else
 214                         {
 215                                 // We use switch here to manually call the database methods. This is
 216                                 // done for speed: call_user_func_array can take over 300% longer to
 217                                 // make calls. Most database methods are 4 arguments or less, so this
 218                                 // avoids almost any calls to call_user_func_array.
 219
 220                                 switch ($num_args)
 221                                 {
 222                                         case 0:
 223                                                 // Support for things like reset_select, reset_write, list_tables
 224                                                 return $this->db->$method();
 225                                         break;
 226                                         case 1:
 227                                                 $this->db->$method($args[0]);
 228                                         break;
 229                                         case 2:
 230                                                 $this->db->$method($args[0], $args[1]);
 231                                         break;
 232                                         case 3:
 233                                                 $this->db->$method($args[0], $args[1], $args[2]);
 234                                         break;
 235                                         case 4:
 236                                                 $this->db->$method($args[0], $args[1], $args[2], $args[3]);
 237                                         break;
 238                                         default:
 239                                                 // Here comes the snail...
 240                                                 call_user_func_array(array($this->db, $method), $args);
 241                                         break;
 242                                 }
 243                         }
 244
 245                         return $this;
 246                 }
 247                 else
 248                 {
 249                         throw new Kohana_Exception('core.invalid_method', $method, get_class($this));
 250                 }
 251         }
 252
 253         /**
 254          * Handles retrieval of all model values, relationships, and metadata.
 255          *
 256          * @param   string  column name
 257          * @return  mixed
 258          */
 259         public function __get($column)
 260         {
 261                 if (isset($this->ignored_columns[$column]))
 262                 {
 263                         return NULL;
 264                 }
 265                 elseif (array_key_exists($column, $this->object))
 266                 {
 267                         return $this->object[$column];
 268                 }
 269                 elseif (isset($this->related[$column]))
 270                 {
 271                         return $this->related[$column];
 272                 }
 273                 elseif ($column === 'primary_key_value')
 274                 {
 275                         return $this->object[$this->primary_key];
 276                 }
 277                 elseif ($model = $this->related_object($column))
 278                 {
 279                         // This handles the has_one and belongs_to relationships
 280
 281                         if (array_key_exists($column.'_'.$model->primary_key, $this->object))
 282                         {
 283                                 // Use the FK that exists in this model as the PK
 284                                 $where = array($model->table_name.'.'.$model->primary_key => $this->object[$column.'_'.$model->primary_key]);
 285                         }
 286                         else
 287                         {
 288                                 // Use this model PK as the FK
 289                                 $where = array($this->foreign_key() => $this->object[$this->primary_key]);
 290                         }
 291
 292                         // one<>alias:one relationship
 293                         return $this->related[$column] = $model->find($where);
 294                 }
 295                 elseif (isset($this->has_many[$column]))
 296                 {
 297                         // Load the "middle" model
 298                         $through = ORM::factory(inflector::singular($this->has_many[$column]));
 299
 300                         // Load the "end" model
 301                         $model = ORM::factory(inflector::singular($column));
 302
 303                         // Load JOIN info
 304                         $join_table = $through->table_name;
 305                         $join_col1  = $model->foreign_key(NULL, $join_table);
 306                         $join_col2  = $model->foreign_key(TRUE);
 307
 308                         // one<>alias:many relationship
 309                         return $this->related[$column] = $model
 310                                 ->join($join_table, $join_col1, $join_col2)
 311                                 ->where($this->foreign_key(NULL, $join_table), $this->object[$this->primary_key])
 312                                 ->find_all();
 313                 }
 314                 elseif (in_array($column, $this->has_many))
 315                 {
 316                         // one<>many relationship
 317                         return $this->related[$column] = ORM::factory(inflector::singular($column))
 318                                 ->where($this->foreign_key($column), $this->object[$this->primary_key])
 319                                 ->find_all();
 320                 }
 321                 elseif (in_array($column, $this->has_and_belongs_to_many))
 322                 {
 323                         // Load the remote model, always singular
 324                         $model = ORM::factory(inflector::singular($column));
 325
 326                         if ($this->has($model, TRUE))
 327                         {
 328                                 // many<>many relationship
 329                                 return $this->related[$column] = $model
 330                                         ->in($model->table_name.'.'.$model->primary_key, $this->changed_relations[$column])
 331                                         ->find_all();
 332                         }
 333                         else
 334                         {
 335                                 // empty many<>many relationship
 336                                 return $this->related[$column] = $model
 337                                         ->where($model->table_name.'.'.$model->primary_key, NULL)
 338                                         ->find_all();
 339                         }
 340                 }
 341                 elseif (in_array($column, array
 342                         (
 343                                 'object_name', 'object_plural', // Object
 344                                 'primary_key', 'primary_val', 'table_name', 'table_columns', // Table
 345                                 'loaded', 'saved', // Status
 346                                 'has_one', 'belongs_to', 'has_many', 'has_and_belongs_to_many', 'load_with' // Relationships
 347                         )))
 348                 {
 349                         // Model meta information
 350                         return $this->$column;
 351                 }
 352                 else
 353                 {
 354                         throw new Kohana_Exception('core.invalid_property', $column, get_class($this));
 355                 }
 356         }
 357
 358         /**
 359          * Handles setting of all model values, and tracks changes between values.
 360          *
 361          * @param   string  column name
 362          * @param   mixed   column value
 363          * @return  void
 364          */
 365         public function __set($column, $value)
 366         {
 367                 if (isset($this->ignored_columns[$column]))
 368                 {
 369                         return NULL;
 370                 }
 371                 elseif (isset($this->object[$column]) OR array_key_exists($column, $this->object))
 372                 {
 373                         if (isset($this->table_columns[$column]))
 374                         {
 375                                 // Data has changed
 376                                 $this->changed[$column] = $column;
 377
 378                                 // Object is no longer saved
 379                                 $this->saved = FALSE;
 380                         }
 381
 382                         $this->object[$column] = $this->load_type($column, $value);
 383                 }
 384                 elseif (in_array($column, $this->has_and_belongs_to_many) AND is_array($value))
 385                 {
 386                         // Load relations
 387                         $model = ORM::factory(inflector::singular($column));
 388
 389                         if ( ! isset($this->object_relations[$column]))
 390                         {
 391                                 // Load relations
 392                                 $this->has($model);
 393                         }
 394
 395                         // Change the relationships
 396                         $this->changed_relations[$column] = $value;
 397
 398                         if (isset($this->related[$column]))
 399                         {
 400                                 // Force a reload of the relationships
 401                                 unset($this->related[$column]);
 402                         }
 403                 }
 404                 else
 405                 {
 406                         throw new Kohana_Exception('core.invalid_property', $column, get_class($this));
 407                 }
 408         }
 409
 410         /**
 411          * Checks if object data is set.
 412          *
 413          * @param   string  column name
 414          * @return  boolean
 415          */
 416         public function __isset($column)
 417         {
 418                 return (isset($this->object[$column]) OR isset($this->related[$column]));
 419         }
 420
 421         /**
 422          * Unsets object data.
 423          *
 424          * @param   string  column name
 425          * @return  void
 426          */
 427         public function __unset($column)
 428         {
 429                 unset($this->object[$column], $this->changed[$column], $this->related[$column]);
 430         }
 431
 432         /**
 433          * Displays the primary key of a model when it is converted to a string.
 434          *
 435          * @return  string
 436          */
 437         public function __toString()
 438         {
 439                 return (string) $this->object[$this->primary_key];
 440         }
 441
 442         /**
 443          * Returns the values of this object as an array.
 444          *
 445          * @return  array
 446          */
 447         public function as_array()
 448         {
 449                 $object = array();
 450
 451                 foreach ($this->object as $key => $val)
 452                 {
 453                         // Reconstruct the array (calls __get)
 454                         $object[$key] = $this->$key;
 455                 }
 456
 457                 return $object;
 458         }
 459
 460         /**
 461          * Binds another one-to-one object to this model.  One-to-one objects
 462          * can be nested using 'object1:object2' syntax
 463          *
 464          * @param string $object
 465          * @return void
 466          */
 467         public function with($object)
 468         {
 469                 if (isset($this->with_applied[$object]))
 470                 {
 471                         // Don't join anything already joined
 472                         return $this;
 473                 }
 474
 475                 $prefix = $table = $object;
 476
 477                 // Split object parts
 478                 $objects = explode(':', $object);
 479                 $object  = $this;
 480                 foreach ($objects as $object_part)
 481                 {
 482                         // Go down the line of objects to find the given target
 483                         $parent = $object;
 484                         $object = $parent->related_object($object_part);
 485
 486                         if ( ! $object)
 487                         {
 488                                 // Can't find related object
 489                                 return $this;
 490                         }
 491                 }
 492
 493                 $table = $object_part;
 494
 495                 if ($this->table_names_plural)
 496                 {
 497                         $table = inflector::plural($table);
 498                 }
 499
 500                 // Pop-off top object to get the parent object (user:photo:tag's parent is user:photo)
 501                 array_pop($objects);
 502                 $parent_prefix = implode(':', $objects);
 503
 504                 if (empty($parent_prefix))
 505                 {
 506                         // Use this table name itself for the parent prefix
 507                         $parent_prefix = $this->table_name;
 508                 }
 509                 else
 510                 {
 511                         if( ! isset($this->with_applied[$parent_prefix]))
 512                         {
 513                                 // If the parent object hasn't been joined yet, do it first (otherwise LEFT JOINs fail)
 514                                 $this->with($parent_prefix);
 515                         }
 516                 }
 517
 518                 // Add to with_applied to prevent duplicate joins
 519                 $this->with_applied[$prefix] = TRUE;
 520
 521                 // Use the keys of the empty object to determine the columns
 522                 $select = array_keys($object->as_array());
 523                 foreach ($select as $i => $column)
 524                 {
 525                         // Add the prefix so that load_result can determine the relationship
 526                         $select[$i] = $prefix.'.'.$column.' AS '.$prefix.':'.$column;
 527                 }
 528
 529                 // Select all of the prefixed keys in the object
 530                 $this->db->select($select);
 531
 532                 // Use last object part to generate foreign key
 533                 $foreign_key = $object_part.'_'.$object->primary_key;
 534
 535                 if (array_key_exists($foreign_key, $parent->object))
 536                 {
 537                         // Foreign key exists in the joined object's parent
 538                         $join_col1 = $object->foreign_key(TRUE, $prefix);
 539                         $join_col2 = $parent_prefix.'.'.$foreign_key;
 540                 }
 541                 else
 542                 {
 543                         $join_col1 = $parent->foreign_key(NULL, $prefix);
 544                         $join_col2 = $parent_prefix.'.'.$parent->primary_key;
 545                 }
 546
 547                 // Join the related object into the result
 548                 $this->db->join($object->table_name.' AS '.$this->db->table_prefix().$prefix, $join_col1, $join_col2, 'LEFT');
 549
 550                 return $this;
 551         }
 552
 553         /**
 554          * Finds and loads a single database row into the object.
 555          *
 556          * @chainable
 557          * @param   mixed  primary key or an array of clauses
 558          * @return  ORM
 559          */
 560         public function find($id = NULL)
 561         {
 562                 if ($id !== NULL)
 563                 {
 564                         if (is_array($id))
 565                         {
 566                                 // Search for all clauses
 567                                 $this->db->where($id);
 568                         }
 569                         else
 570                         {
 571                                 // Search for a specific column
 572                                 $this->db->where($this->table_name.'.'.$this->unique_key($id), $id);
 573                         }
 574                 }
 575
 576                 return $this->load_result();
 577         }
 578
 579         /**
 580          * Finds multiple database rows and returns an iterator of the rows found.
 581          *
 582          * @chainable
 583          * @param   integer  SQL limit
 584          * @param   integer  SQL offset
 585          * @return  ORM_Iterator
 586          */
 587         public function find_all($limit = NULL, $offset = NULL)
 588         {
 589                 if ($limit !== NULL AND ! isset($this->db_applied['limit']))
 590                 {
 591                         // Set limit
 592                         $this->limit($limit);
 593                 }
 594
 595                 if ($offset !== NULL AND ! isset($this->db_applied['offset']))
 596                 {
 597                         // Set offset
 598                         $this->offset($offset);
 599                 }
 600
 601                 return $this->load_result(TRUE);
 602         }
 603
 604         /**
 605          * Creates a key/value array from all of the objects available. Uses find_all
 606          * to find the objects.
 607          *
 608          * @param   string  key column
 609          * @param   string  value column
 610          * @return  array
 611          */
 612         public function select_list($key = NULL, $val = NULL)
 613         {
 614                 if ($key === NULL)
 615                 {
 616                         $key = $this->primary_key;
 617                 }
 618
 619                 if ($val === NULL)
 620                 {
 621                         $val = $this->primary_val;
 622                 }
 623
 624                 // Return a select list from the results
 625                 return $this->select($key, $val)->find_all()->select_list($key, $val);
 626         }
 627
 628         /**
 629          * Validates the current object. This method should generally be called
 630          * via the model, after the $_POST Validation object has been created.
 631          *
 632          * @param   object   Validation array
 633          * @return  boolean
 634          */
 635         public function validate(Validation $array, $save = FALSE)
 636         {
 637                 if ( ! $array->submitted())
 638                 {
 639                         $safe_array = $array->safe_array();
 640
 641                         foreach ($safe_array as $key => $value)
 642                         {
 643                                 // Get the value from this object
 644                                 $value = $this->$key;
 645
 646                                 if (is_object($value) AND $value instanceof ORM_Iterator)
 647                                 {
 648                                         // Convert the value to an array of primary keys
 649                                         $value = $value->primary_key_array();
 650                                 }
 651
 652                                 // Pre-fill data
 653                                 $array[$key] = $value;
 654                         }
 655                 }
 656
 657                 // Validate the array
 658                 if ($status = $array->validate())
 659                 {
 660                         $safe_array = $array->safe_array();
 661
 662                         foreach ($safe_array as $key => $value)
 663                         {
 664                                 // Set new data
 665                                 $this->$key = $value;
 666                         }
 667
 668                         if ($save === TRUE OR is_string($save))
 669                         {
 670                                 // Save this object
 671                                 $this->save();
 672
 673                                 if (is_string($save))
 674                                 {
 675                                         // Redirect to the saved page
 676                                         return url::redirect($save);
 677                                 }
 678                         }
 679                 }
 680
 681                 // Return validation status
 682                 return $status;
 683         }
 684
 685         /**
 686          * Saves the current object.
 687          *
 688          * @chainable
 689          * @return  ORM
 690          */
 691         public function save()
 692         {
 693                 if ( ! empty($this->changed))
 694                 {
 695                         $data = array();
 696                         foreach ($this->changed as $column)
 697                         {
 698                                 // Compile changed data
 699                                 $data[$column] = $this->object[$column];
 700                         }
 701
 702                         if ($this->loaded === TRUE)
 703                         {
 704                                 $query = $this->db
 705                                         ->where($this->primary_key, $this->object[$this->primary_key])
 706                                         ->update($this->table_name, $data);
 707
 708                                 // Object has been saved
 709                                 $this->saved = TRUE;
 710                         }
 711                         else
 712                         {
 713                                 $query = $this->db
 714                                         ->insert($this->table_name, $data);
 715
 716                                 if ($query->count() > 0)
 717                                 {
 718                                         if (empty($this->object[$this->primary_key]))
 719                                         {
 720                                                 // Load the insert id as the primary key
 721                                                 $this->object[$this->primary_key] = $query->insert_id();
 722                                         }
 723
 724                                         // Object is now loaded and saved
 725                                         $this->loaded = $this->saved = TRUE;
 726                                 }
 727                         }
 728
 729                         if ($this->saved === TRUE)
 730                         {
 731                                 // All changes have been saved
 732                                 $this->changed = array();
 733                         }
 734                 }
 735
 736                 if ($this->saved === TRUE AND ! empty($this->changed_relations))
 737                 {
 738                         foreach ($this->changed_relations as $column => $values)
 739                         {
 740                                 // All values that were added
 741                                 $added = array_diff($values, $this->object_relations[$column]);
 742
 743                                 // All values that were saved
 744                                 $removed = array_diff($this->object_relations[$column], $values);
 745
 746                                 if (empty($added) AND empty($removed))
 747                                 {
 748                                         // No need to bother
 749                                         continue;
 750                                 }
 751
 752                                 // Clear related columns
 753                                 unset($this->related[$column]);
 754
 755                                 // Load the model
 756                                 $model = ORM::factory(inflector::singular($column));
 757
 758                                 if (($join_table = array_search($column, $this->has_and_belongs_to_many)) === FALSE)
 759                                         continue;
 760
 761                                 if (is_int($join_table))
 762                                 {
 763                                         // No "through" table, load the default JOIN table
 764                                         $join_table = $model->join_table($this->table_name);
 765                                 }
 766
 767                                 // Foreign keys for the join table
 768                                 $object_fk  = $this->foreign_key(NULL);
 769                                 $related_fk = $model->foreign_key(NULL);
 770
 771                                 if ( ! empty($added))
 772                                 {
 773                                         foreach ($added as $id)
 774                                         {
 775                                                 // Insert the new relationship
 776                                                 $this->db->insert($join_table, array
 777                                                 (
 778                                                         $object_fk  => $this->object[$this->primary_key],
 779                                                         $related_fk => $id,
 780                                                 ));
 781                                         }
 782                                 }
 783
 784                                 if ( ! empty($removed))
 785                                 {
 786                                         $this->db
 787                                                 ->where($object_fk, $this->object[$this->primary_key])
 788                                                 ->in($related_fk, $removed)
 789                                                 ->delete($join_table);
 790                                 }
 791
 792                                 // Clear all relations for this column
 793                                 unset($this->object_relations[$column], $this->changed_relations[$column]);
 794                         }
 795                 }
 796
 797                 return $this;
 798         }
 799
 800         /**
 801          * Deletes the current object from the database. This does NOT destroy
 802          * relationships that have been created with other objects.
 803          *
 804          * @chainable
 805          * @return  ORM
 806          */
 807         public function delete($id = NULL)
 808         {
 809                 if ($id === NULL AND $this->loaded)
 810                 {
 811                         // Use the the primary key value
 812                         $id = $this->object[$this->primary_key];
 813                 }
 814
 815                 // Delete this object
 816                 $this->db->where($this->primary_key, $id)->delete($this->table_name);
 817
 818                 return $this->clear();
 819         }
 820
 821         /**
 822          * Delete all objects in the associated table. This does NOT destroy
 823          * relationships that have been created with other objects.
 824          *
 825          * @chainable
 826          * @param   array  ids to delete
 827          * @return  ORM
 828          */
 829         public function delete_all($ids = NULL)
 830         {
 831                 if (is_array($ids))
 832                 {
 833                         // Delete only given ids
 834                         $this->db->in($this->primary_key, $ids);
 835                 }
 836                 elseif (is_null($ids))
 837                 {
 838                         // Delete all records
 839                         $this->db->where(TRUE);
 840                 }
 841                 else
 842                 {
 843                         // Do nothing - safeguard
 844                         return $this;
 845                 }
 846
 847                 // Delete all objects
 848                 $this->db->delete($this->table_name);
 849
 850                 return $this->clear();
 851         }
 852
 853         /**
 854          * Unloads the current object and clears the status.
 855          *
 856          * @chainable
 857          * @return  ORM
 858          */
 859         public function clear()
 860         {
 861                 // Create an array with all the columns set to NULL
 862                 $columns = array_keys($this->table_columns);
 863                 $values  = array_combine($columns, array_fill(0, count($columns), NULL));
 864
 865                 // Replace the current object with an empty one
 866                 $this->load_values($values);
 867
 868                 return $this;
 869         }
 870
 871         /**
 872          * Reloads the current object from the database.
 873          *
 874          * @chainable
 875          * @return  ORM
 876          */
 877         public function reload()
 878         {
 879                 return $this->find($this->object[$this->primary_key]);
 880         }
 881
 882         /**
 883          * Reload column definitions.
 884          *
 885          * @chainable
 886          * @param   boolean  force reloading
 887          * @return  ORM
 888          */
 889         public function reload_columns($force = FALSE)
 890         {
 891                 if ($force === TRUE OR empty($this->table_columns))
 892                 {
 893                         if (isset(self::$column_cache[$this->object_name]))
 894                         {
 895                                 // Use cached column information
 896                                 $this->table_columns = self::$column_cache[$this->object_name];
 897                         }
 898                         else
 899                         {
 900                                 // Load table columns
 901                                 self::$column_cache[$this->object_name] = $this->table_columns = $this->db->list_fields($this->table_name, TRUE);
 902                         }
 903                 }
 904
 905                 return $this;
 906         }
 907
 908         /**
 909          * Tests if this object has a relationship to a different model.
 910          *
 911          * @param   object   related ORM model
 912          * @param   boolean  check for any relations to given model
 913          * @return  boolean
 914          */
 915         public function has(ORM $model, $any = FALSE)
 916         {
 917                 $related = $model->object_plural;
 918
 919                 if (($join_table = array_search($related, $this->has_and_belongs_to_many)) === FALSE)
 920                         return FALSE;
 921
 922                 if (is_int($join_table))
 923                 {
 924                         // No "through" table, load the default JOIN table
 925                         $join_table = $model->join_table($this->table_name);
 926                 }
 927
 928                 if ( ! isset($this->object_relations[$related]))
 929                 {
 930                         // Load the object relationships
 931                         $this->changed_relations[$related] = $this->object_relations[$related] = $this->load_relations($join_table, $model);
 932                 }
 933
 934                 if ( ! $model->empty_primary_key())
 935                 {
 936                         // Check if a specific object exists
 937                         return in_array($model->primary_key_value, $this->changed_relations[$related]);
 938                 }
 939                 elseif ($any)
 940                 {
 941                         // Check if any relations to given model exist
 942                         return ! empty($this->changed_relations[$related]);
 943                 }
 944                 else
 945                 {
 946                         return FALSE;
 947                 }
 948         }
 949
 950         /**
 951          * Adds a new relationship to between this model and another.
 952          *
 953          * @param   object   related ORM model
 954          * @return  boolean
 955          */
 956         public function add(ORM $model)
 957         {
 958                 if ($this->has($model))
 959                         return TRUE;
 960
 961                 // Get the faked column name
 962                 $column = $model->object_plural;
 963
 964                 // Add the new relation to the update
 965                 $this->changed_relations[$column][] = $model->primary_key_value;
 966
 967                 if (isset($this->related[$column]))
 968                 {
 969                         // Force a reload of the relationships
 970                         unset($this->related[$column]);
 971                 }
 972
 973                 return TRUE;
 974         }
 975
 976         /**
 977          * Adds a new relationship to between this model and another.
 978          *
 979          * @param   object   related ORM model
 980          * @return  boolean
 981          */
 982         public function remove(ORM $model)
 983         {
 984                 if ( ! $this->has($model))
 985                         return FALSE;
 986
 987                 // Get the faked column name
 988                 $column = $model->object_plural;
 989
 990                 if (($key = array_search($model->primary_key_value, $this->changed_relations[$column])) === FALSE)
 991                         return FALSE;
 992
 993                 // Remove the relationship
 994                 unset($this->changed_relations[$column][$key]);
 995
 996                 if (isset($this->related[$column]))
 997                 {
 998                         // Force a reload of the relationships
 999                         unset($this->related[$column]);
1000                 }
1001
1002                 return TRUE;
1003         }
1004
1005         /**
1006          * Count the number of records in the table.
1007          *
1008          * @return  integer
1009          */
1010         public function count_all()
1011         {
1012                 // Return the total number of records in a table
1013                 return $this->db->count_records($this->table_name);
1014         }
1015
1016         /**
1017          * Count the number of records in the last query, without LIMIT or OFFSET applied.
1018          *
1019          * @return  integer
1020          */
1021         public function count_last_query()
1022         {
1023                 if ($sql = $this->db->last_query())
1024                 {
1025                         if (stripos($sql, 'LIMIT') !== FALSE)
1026                         {
1027                                 // Remove LIMIT from the SQL
1028                                 $sql = preg_replace('/\sLIMIT\s+[^a-z]+/i', ' ', $sql);
1029                         }
1030
1031                         if (stripos($sql, 'OFFSET') !== FALSE)
1032                         {
1033                                 // Remove OFFSET from the SQL
1034                                 $sql = preg_replace('/\sOFFSET\s+\d+/i', '', $sql);
1035                         }
1036
1037                         // Get the total rows from the last query executed
1038                         $result = $this->db->query
1039                         (
1040                                 'SELECT COUNT(*) AS '.$this->db->escape_column('total_rows').' '.
1041                                 'FROM ('.trim($sql).') AS '.$this->db->escape_table('counted_results')
1042                         );
1043
1044                         // Return the total number of rows from the query
1045                         return (int) $result->current()->total_rows;
1046                 }
1047
1048                 return FALSE;
1049         }
1050
1051         /**
1052          * Proxy method to Database list_fields.
1053          *
1054          * @param   string  table name
1055          * @return  array
1056          */
1057         public function list_fields($table)
1058         {
1059                 // Proxy to database
1060                 return $this->db->list_fields($table);
1061         }
1062
1063         /**
1064          * Proxy method to Database field_data.
1065          *
1066          * @param   string  table name
1067          * @return  array
1068          */
1069         public function field_data($table)
1070         {
1071                 // Proxy to database
1072                 return $this->db->field_data($table);
1073         }
1074
1075         /**
1076          * Proxy method to Database last_query.
1077          *
1078          * @return  string
1079          */
1080         public function last_query()
1081         {
1082                 // Proxy to database
1083                 return $this->db->last_query();
1084         }
1085
1086         /**
1087          * Proxy method to Database field_data.
1088          *
1089          * @chainable
1090          * @param   string  SQL query to clear
1091          * @return  ORM
1092          */
1093         public function clear_cache($sql = NULL)
1094         {
1095                 // Proxy to database
1096                 $this->db->clear_cache($sql);
1097
1098                 return $this;
1099         }
1100
1101         /**
1102          * Returns the unique key for a specific value. This method is expected
1103          * to be overloaded in models if the model has other unique columns.
1104          *
1105          * @param   mixed   unique value
1106          * @return  string
1107          */
1108         public function unique_key($id)
1109         {
1110                 return $this->primary_key;
1111         }
1112
1113         /**
1114          * Determines the name of a foreign key for a specific table.
1115          *
1116          * @param   string  related table name
1117          * @param   string  prefix table name (used for JOINs)
1118          * @return  string
1119          */
1120         public function foreign_key($table = NULL, $prefix_table = NULL)
1121         {
1122                 if ($table === TRUE)
1123                 {
1124                         if (is_string($prefix_table))
1125                         {
1126                                 // Use prefix table name and this table's PK
1127                                 return $prefix_table.'.'.$this->primary_key;
1128                         }
1129                         else
1130                         {
1131                                 // Return the name of this table's PK
1132                                 return $this->table_name.'.'.$this->primary_key;
1133                         }
1134                 }
1135
1136                 if (is_string($prefix_table))
1137                 {
1138                         // Add a period for prefix_table.column support
1139                         $prefix_table .= '.';
1140                 }
1141
1142                 if (isset($this->foreign_key[$table]))
1143                 {
1144                         // Use the defined foreign key name, no magic here!
1145                         $foreign_key = $this->foreign_key[$table];
1146                 }
1147                 else
1148                 {
1149                         if ( ! is_string($table) OR ! isset($this->object[$table.'_'.$this->primary_key]))
1150                         {
1151                                 // Use this table
1152                                 $table = $this->table_name;
1153
1154                                 if (strpos($table, '.') !== FALSE)
1155                                 {
1156                                         // Hack around support for PostgreSQL schemas
1157                                         list ($schema, $table) = explode('.', $table, 2);
1158                                 }
1159
1160                                 if ($this->table_names_plural === TRUE)
1161                                 {
1162                                         // Make the key name singular
1163                                         $table = inflector::singular($table);
1164                                 }
1165                         }
1166
1167                         $foreign_key = $table.'_'.$this->primary_key;
1168                 }
1169
1170                 return $prefix_table.$foreign_key;
1171         }
1172
1173         /**
1174          * This uses alphabetical comparison to choose the name of the table.
1175          *
1176          * Example: The joining table of users and roles would be roles_users,
1177          * because "r" comes before "u". Joining products and categories would
1178          * result in categories_products, because "c" comes before "p".
1179          *
1180          * Example: zoo > zebra > robber > ocean > angel > aardvark
1181          *
1182          * @param   string  table name
1183          * @return  string
1184          */
1185         public function join_table($table)
1186         {
1187                 if ($this->table_name > $table)
1188                 {
1189                         $table = $table.'_'.$this->table_name;
1190                 }
1191                 else
1192                 {
1193                         $table = $this->table_name.'_'.$table;
1194                 }
1195
1196                 return $table;
1197         }
1198
1199         /**
1200          * Returns an ORM model for the given object name;
1201          *
1202          * @param   string  object name
1203          * @return  ORM
1204          */
1205         protected function related_object($object)
1206         {
1207                 if (isset($this->has_one[$object]))
1208                 {
1209                         $object = ORM::factory($this->has_one[$object]);
1210                 }
1211                 elseif (isset($this->belongs_to[$object]))
1212                 {
1213                         $object = ORM::factory($this->belongs_to[$object]);
1214                 }
1215                 elseif (in_array($object, $this->has_one) OR in_array($object, $this->belongs_to))
1216                 {
1217                         $object = ORM::factory($object);
1218                 }
1219                 else
1220                 {
1221                         return FALSE;
1222                 }
1223
1224                 return $object;
1225         }
1226
1227         /**
1228          * Loads an array of values into into the current object.
1229          *
1230          * @chainable
1231          * @param   array  values to load
1232          * @return  ORM
1233          */
1234         public function load_values(array $values)
1235         {
1236                 if (array_key_exists($this->primary_key, $values))
1237                 {
1238                         // Replace the object and reset the object status
1239                         $this->object = $this->changed = $this->related = array();
1240
1241                         // Set the loaded and saved object status based on the primary key
1242                         $this->loaded = $this->saved = ($values[$this->primary_key] !== NULL);
1243                 }
1244
1245                 // Related objects
1246                 $related = array();
1247
1248                 foreach ($values as $column => $value)
1249                 {
1250                         if (strpos($column, ':') === FALSE)
1251                         {
1252                                 if (isset($this->table_columns[$column]))
1253                                 {
1254                                         // The type of the value can be determined, convert the value
1255                                         $value = $this->load_type($column, $value);
1256                                 }
1257
1258                                 $this->object[$column] = $value;
1259                         }
1260                         else
1261                         {
1262                                 list ($prefix, $column) = explode(':', $column, 2);
1263
1264                                 $related[$prefix][$column] = $value;
1265                         }
1266                 }
1267
1268                 if ( ! empty($related))
1269                 {
1270                         foreach ($related as $object => $values)
1271                         {
1272                                 // Load the related objects with the values in the result
1273                                 $this->related[$object] = $this->related_object($object)->load_values($values);
1274                         }
1275                 }
1276
1277                 return $this;
1278         }
1279
1280         /**
1281          * Loads a value according to the types defined by the column metadata.
1282          *
1283          * @param   string  column name
1284          * @param   mixed   value to load
1285          * @return  mixed
1286          */
1287         protected function load_type($column, $value)
1288         {
1289                 if (is_object($value) OR is_array($value) OR ! isset($this->table_columns[$column]))
1290                         return $value;
1291
1292                 // Load column data
1293                 $column = $this->table_columns[$column];
1294
1295                 if ($value === NULL AND ! empty($column['null']))
1296                         return $value;
1297
1298                 if ( ! empty($column['binary']) AND ! empty($column['exact']) AND (int) $column['length'] === 1)
1299                 {
1300                         // Use boolean for BINARY(1) fields
1301                         $column['type'] = 'boolean';
1302                 }
1303
1304                 switch ($column['type'])
1305                 {
1306                         case 'int':
1307                                 if ($value === '' AND ! empty($column['null']))
1308                                 {
1309                                         // Forms will only submit strings, so empty integer values must be null
1310                                         $value = NULL;
1311                                 }
1312                                 elseif ((float) $value > PHP_INT_MAX)
1313                                 {
1314                                         // This number cannot be represented by a PHP integer, so we convert it to a string
1315                                         $value = (string) $value;
1316                                 }
1317                                 else
1318                                 {
1319                                         $value = (int) $value;
1320                                 }
1321                         break;
1322                         case 'float':
1323                                 $value = (float) $value;
1324                         break;
1325                         case 'boolean':
1326                                 $value = (bool) $value;
1327                         break;
1328                         case 'string':
1329                                 $value = (string) $value;
1330                         break;
1331                 }
1332
1333                 return $value;
1334         }
1335
1336         /**
1337          * Loads a database result, either as a new object for this model, or as
1338          * an iterator for multiple rows.
1339          *
1340          * @chainable
1341          * @param   boolean       return an iterator or load a single row
1342          * @return  ORM           for single rows
1343          * @return  ORM_Iterator  for multiple rows
1344          */
1345         protected function load_result($array = FALSE)
1346         {
1347                 if ($array === FALSE)
1348                 {
1349                         // Only fetch 1 record
1350                         $this->db->limit(1);
1351                 }
1352
1353                 if ( ! isset($this->db_applied['select']))
1354                 {
1355                         // Select all columns by default
1356                         $this->db->select($this->table_name.'.*');
1357                 }
1358
1359                 if ( ! empty($this->load_with))
1360                 {
1361                         foreach ($this->load_with as $object)
1362                         {
1363                                 // Join each object into the results
1364                                 $this->with($object);
1365                         }
1366                 }
1367
1368                 if ( ! isset($this->db_applied['orderby']) AND ! empty($this->sorting))
1369                 {
1370                         $sorting = array();
1371                         foreach ($this->sorting as $column => $direction)
1372                         {
1373                                 if (strpos($column, '.') === FALSE)
1374                                 {
1375                                         // Keeps sorting working properly when using JOINs on
1376                                         // tables with columns of the same name
1377                                         $column = $this->table_name.'.'.$column;
1378                                 }
1379
1380                                 $sorting[$column] = $direction;
1381                         }
1382
1383                         // Apply the user-defined sorting
1384                         $this->db->orderby($sorting);
1385                 }
1386
1387                 // Load the result
1388                 $result = $this->db->get($this->table_name);
1389
1390                 if ($array === TRUE)
1391                 {
1392                         // Return an iterated result
1393                         return new ORM_Iterator($this, $result);
1394                 }
1395
1396                 if ($result->count() === 1)
1397                 {
1398                         // Load object values
1399                         $this->load_values($result->result(FALSE)->current());
1400                 }
1401                 else
1402                 {
1403                         // Clear the object, nothing was found
1404                         $this->clear();
1405                 }
1406
1407                 return $this;
1408         }
1409
1410         /**
1411          * Return an array of all the primary keys of the related table.
1412          *
1413          * @param   string  table name
1414          * @param   object  ORM model to find relations of
1415          * @return  array
1416          */
1417         protected function load_relations($table, ORM $model)
1418         {
1419                 // Save the current query chain (otherwise the next call will clash)
1420                 $this->db->push();
1421
1422                 $query = $this->db
1423                         ->select($model->foreign_key(NULL).' AS id')
1424                         ->from($table)
1425                         ->where($this->foreign_key(NULL, $table), $this->object[$this->primary_key])
1426                         ->get()
1427                         ->result(TRUE);
1428
1429                 $this->db->pop();
1430
1431                 $relations = array();
1432                 foreach ($query as $row)
1433                 {
1434                         $relations[] = $row->id;
1435                 }
1436
1437                 return $relations;
1438         }
1439
1440         /**
1441          * Returns whether or not primary key is empty
1442          *
1443          * @return bool
1444          */
1445         protected function empty_primary_key()
1446         {
1447                 return (empty($this->object[$this->primary_key]) AND $this->object[$this->primary_key] !== '0');
1448         }
1449
1450 } // End ORM