root/trunk/system/libraries/ORM.php

<?php defined('SYSPATH') or die('No direct script access.');
 /**
 * Object Relational Mapping (ORM) is a method of abstracting database
 * access to standard PHP calls. All table rows are represented as a model.
 *
 * @see http://en.wikipedia.org/wiki/Active_record
 * @see http://en.wikipedia.org/wiki/Object-relational_mapping
 *
 * $Id$
 *
 * @package    Core
 * @author     Kohana Team
 * @copyright  (c) 2007-2008 Kohana Team
 * @license    http://kohanaphp.com/license.html
 */
class ORM_Core {

    // Database field caching
    protected static $fields = array();

    // Database instance
    protected static $db;

    // Automatic saving on model destruction
    protected $auto_save = FALSE;

    // This table
    protected $class;
    protected $table;

    // SQL building status
    protected $select = FALSE;
    protected $where = FALSE;
    protected $from = FALSE;
    protected $order = FALSE;

    // Default sorting
    protected $sort = array('id', 'asc');

    // Currently loaded object
    protected $object;
    protected $object_related;
    protected $loaded = FALSE;
    protected $saved = FALSE;

    // Changed object keys
    protected $changed = array();
    protected $changed_related = array();

    // Object Relationships
    protected $has_one = array();
    protected $has_many = array();
    protected $belongs_to = array();
    protected $belongs_to_many = array();
    protected $has_and_belongs_to_many = array();

    /**
     * Factory method. Creates an instance of an ORM model and returns it.
     *
     * @param   string   model name
     * @param   mixed    id to load
     * @return  object
     */
    public static function factory($model = FALSE, $id = FALSE)
    {
        $model = empty($model) ? __CLASS__ : ucfirst($model).'_Model';
        return new $model($id);
    }

    /**
     * Initialize database, setup internal variables, find requested object.
     *
     * @return  void
     */
    public function __construct($id = FALSE)
    {
        // Fetch table name
        empty($this->class) and $this->class = strtolower(substr(get_class($this), 0, -6));
        empty($this->table) and $this->table = inflector::plural($this->class);

        // Connect to the database
        $this->connect();

        if (is_object($id))
        {
            // Preloaded object
            $this->object = $id;

            // Convert the value to the correct type
            $this->load_object_types();

            // Object is loaded
            $this->loaded = $this->saved = TRUE;
        }
        else
        {
            if (empty($id))
            {
                // Load an empty object
                $this->clear();
            }
            else
            {
                // Query and load object
                $this->find($id);
            }
        }
    }

    /**
     * Enables automatic saving of the object when the model is destroyed.
     *
     * @return  void
     */
    public function __destruct()
    {
        if ($this->auto_save == TRUE)
        {
            try
            {
                // Automatically save the model
                $this->save();
            }
            catch (Exception $e)
            {
                /// Log the error, rather than trying to display it, to avoid
                // "stack frame" errors. http://bugs.php.net/bug.php?id=33598
                Log::add('error', $e->getMessage());
            }
        }
    }

    /**
     * Reloads the database when the object is unserialized.
     *
     * @return  void
     */
    public function __wakeup()
    {
        // Connect to the database
        $this->connect();
    }

    /**
     * Magic method for getting object and model keys.
     *
     * @param   string  key name
     * @return  mixed
     */
    public function __get($key)
    {
        if (isset($this->object->$key))
        {
            return $this->object->$key;
        }
        elseif (in_array($key, $this->has_one) OR in_array($key, $this->belongs_to))
        {
            // Set the model name
            $model = ucfirst($key).'_Model';

            // Set the child id name
            $child_id = $key.'_id';

            $this->object->$key = new $model
            (
                isset($this->object->$child_id)
                // Get the foreign object using the key defined in this object
                ? $this->object->$child_id
                // Get the foreign object using the primary key of this object
                : array($this->class.'_id' => $this->object->id)
            );

            // Return the model
            return $this->object->$key;
        }
        elseif (in_array($key, $this->has_and_belongs_to_many))
        {
            if (empty($this->object_related[$key]['cur']))
            {
                // Create an array
                $this->object_related[$key]['cur'] = array();

                // Foreign key
                $fk = inflector::singular($key).'_id';

                // Query to find relationships
                $query = self::$db
                    ->select($fk)
                    ->from($this->related_table($key))
                    ->where($this->class.'_id', $this->id)
                    ->get();

                foreach ($query as $row)
                {
                    // Set relationships
                    $this->object_related[$key]['cur'][] = $row->$fk;
                }
            }

            // Return the current relationships
            return $this->object_related[$key]['cur'];
        }
        else
        {
            switch ($key)
            {
                case 'table_name':
                    return $this->table;
                break;
                case 'class_name':
                    return $this->class;
                break;
                case 'auto_save':
                    return $this->auto_save;
                break;
            }
        }
    }

    /**
     * Magic method for setting object and model keys.
     *
     * @param   string  key name
     * @param   mixed   value to set
     * @return  void
     */
    public function __set($key, $value)
    {
        if ($key != 'id' AND isset(self::$fields[$this->table][$key]))
        {
            // Force the value to the correct type
            $value = $this->set_value_type($key, $value);

            if ($this->object->$key !== $value)
            {
                // Set new value
                $this->object->$key = $value;

                // Data has changed
                $this->changed[$key] = $key;

                // Data has been changed
                $this->saved = FALSE;
            }
        }
        elseif (in_array($key, $this->has_and_belongs_to_many) AND is_array($value))
        {
            if (empty($this->object_related[$key]))
            {
                // Force a load of the relationship
                $this->$key;
            }

            // Set the new relationships
            $this->object_related[$key]['new'] = $value;

            // Relationships changed
            $this->changed_related[$key] = $key;
        }
        else
        {
            switch ($key)
            {
                case 'auto_save':
                    $this->auto_save = (bool) $value;
                break;
            }
        }
    }

    /**
     * Magic method for calling ORM methods. This handles:
     *  - as_array
     *  - find_by_*
     *  - find_all_by_*
     *  - find_related_*
     *  - has_*
     *  - add_*
     *  - remove_*
     *
     * @throws  Kohana_Exception
     * @param   string  method name
     * @param   array   method arguments
     * @return  mixed
     */
    public function __call($method, $args)
    {
        if ($method === 'as_array')
        {
            // Return all of the object data as an array
            return (array) $this->object;
        }

        if (substr($method, 0, 8) === 'find_by_' OR substr($method, 0, 12) === 'find_all_by_')
        {
            // Make a find_by call
            return $this->call_find_by($method, $args);
        }

        if (substr($method, 0, 13) === 'find_related_')
        {
            // Make a find_related call
            return $this->call_find_related(substr($method, 13), $args);
        }

        if (preg_match('/^(has|add|remove)_(.+)$/', $method, $matches))
        {
            if (empty($this->object->id))
            {
                // many<>many relationships only work when the object has been saved
                return FALSE;
            }

            // Make a has/add/remove call
            return $this->call_has_add_remove($method, $args, $matches);
        }

        if (method_exists(self::$db, $method))
        {
            // Do not allow query methods
            if (preg_match('/^(?:query|get|insert|update|list_fields|field_data)$/', $method))
                return $this;

            if ($method === 'select')
            {
                $this->select = TRUE;
            }
            elseif (preg_match('/where|like|in|regex/', $method))
            {
                $this->where = TRUE;
            }
            elseif ($method === 'from')
            {
                $this->from = TRUE;
            }
            elseif ($method === 'orderby')
            {
                $this->order = TRUE;
            }

            // Pass through to Database, manually calling up to 2 args, for speed.
            switch (count($args))
            {
                case 0:
                    return self::$db->$method();
                break;
                case 1:
                    self::$db->$method(current($args));
                break;
                case 2:
                    self::$db->$method(current($args), next($args));
                break;
                default:
                    call_user_func_array(array(self::$db, $method), $args);
                break;
            }

            return $this;
        }

        // Throw an exception to warn the user
        throw new Kohana_Exception('orm.method_not_implemented', $method, get_class($this));
    }

    /**
     * __call: find_by_*, find_all_by_*
     *
     * @param   string  method
     * @param   array   arguments
     * @return  object
     */
    protected function call_find_by($method, $args)
    {
        // Use ALL
        $ALL = (substr($method, 0, 12) === 'find_all_by_');

        // Method args
        $method = $ALL ? substr($method, 12) : substr($method, 8);

        // WHERE is manually set
        $this->where = TRUE;

        // split method name into $keys array by "_and_" or "_or_"
        if (is_array($keys = $this->find_keys($method)))
        {
            if (strpos($method, '_or_') === FALSE)
            {
                // Use AND WHERE
                self::$db->where(array_combine($keys, $args));
            }
            else
            {
                if (count($args) === 1)
                {
                    $val = current($args);
                    foreach ($keys as $key)
                    {
                        // Use OR WHERE, with a single value
                        self::$db->orwhere(array($key => $val));
                    }
                }
                else
                {
                    // Use OR WHERE, with multiple values
                    self::$db->orwhere(array_combine($keys, $args));
                }
            }
        }
        else
        {
            // Set WHERE
            self::$db->where(array($keys => current($args)));
        }

        if ($ALL)
        {
            // Array of results
            return $this->load_result(TRUE);
        }
        else
        {
            // Allow chains
            return $this->find();
        }
    }

    /**
     * __call: find_related_*
     *
     * @param   string   method name
     * @param   array    arguments
     * @return  object
     */
    protected function call_find_related($table, $args)
    {
        // Construct a new model
        $model = $this->load_model($table);

        // Remote reference to this object
        $remote = array($this->class.'_id' => $this->object->id);

        if (in_array($table, $this->has_one))
        {
            // Find one<>one relationships
            return $model->where($remote)->find();
        }
        elseif (in_array($table, $this->has_many))
        {
            // Find one<>many relationships
            $model->where($remote);
        }
        elseif (in_array($table, $this->has_and_belongs_to_many))
        {
            // Find many<>many relationships, via a JOIN
            $this->related_join($table);
        }
        elseif (in_array($table, $this->belongs_to_many))
        {
            // Use the foreign column name to check the relationship
            $id = $this->class.'_id';

            if ($model->$id === NULL)
            {
                // Find many<>many relationships, via a JOIN
                $this->related_join($table);
            }
            else
            {
                // Find one<>many relationships
                $model->where($remote);
            }
        }
        else
        {
            // This table does not have ownership
            return FALSE;
        }

        return $model->load_result(TRUE);
    }

    /**
     * __call: has_*, add_*, remove_*
     *
     * @param   string   method
     * @param   array    arguments
     * @param   array    action matches
     * @return  boolean
     */
    protected function call_has_add_remove($method, $args, $matches)
    {
        $action = $matches[1];
        $model  = (count($args) > 0 AND is_object($args[0])) ? $args[0] : $this->load_model($matches[2]);

        // Real foreign table name
        $table = $model->table_name;

        // Sanity check, make sure that this object has ownership
        if (in_array($matches[2], $this->has_one))
        {
            $ownership = 1;
        }
        elseif (in_array($table, $this->has_many))
        {
            $ownership = 2;
        }
        elseif (in_array($table, $this->has_and_belongs_to_many))
        {
            $ownership = 3;
        }
        else
        {
            // Model does not have ownership, abort now
            return FALSE;
        }

        // Primary key related to this object
        $primary = $this->class.'_id';

        // Related foreign key
        $foreign = $model->class_name.'_id';

        if ( ! is_object(current($args)))
        {
            if ($action === 'add' AND is_array(current($args)))
            {
                $arg = current($args);

                foreach ($arg as $key => $val)
                {
                    // Fill object with data from array
                    $model->$key = $val;
                }
            }
            else
            {
                if ($ownership === 1 OR $ownership === 2)
                {
                    // Make sure the related key matches this object id
                    self::$db->where($primary, $this->object->id);
                }

                // Load the related object
                $model->find(current($args));
            }
        }

        if ($ownership === 3)
        {
            // Save the model before finishing the action
            $model->save();

            // The many<>many relationship, via a joining table
            $relationship = array
            (
                $primary => $this->object->id,
                $foreign => $model