Modules

Model_User
extends Model_Auth_User
extends ORM
extends Kohana_ORM
extends Model
extends Kohana_Model

Implements: Serializable

Default auth user

package
Kohana/Auth
author
Kohana Team
copyright
© 2007-2012 Kohana Team
license
http://kohanaframework.org/license

Class declared in MODPATH/orm/classes/model/user.php on line 3.

Properties

protected array $_belongs_to

"Belongs to" relationships

protected array $_cast_data

Data to be loaded into the model from a database call cast

protected array $_changed

protected static array $_column_cache

Stores column information for ORM models

array(0) 

protected string $_created_column

Auto-update columns for creation

protected Database $_db

Database Object

protected array $_db_applied

Database methods applied

protected Database_Query_Builder_Where $_db_builder

Database query builder

protected String $_db_group

Database config group

protected static array $_db_methods

Callable database methods

array(28) (
    0 => string(5) "where"
    1 => string(9) "and_where"
    2 => string(8) "or_where"
    3 => string(10) "where_open"
    4 => string(14) "and_where_open"
    5 => string(13) "or_where_open"
    6 => string(11) "where_close"
    7 => string(15) "and_where_close"
    8 => string(14) "or_where_close"
    9 => string(8) "distinct"
    10 => string(6) "select"
    11 => string(4) "from"
    12 => string(4) "join"
    13 => string(2) "on"
    14 => string(8) "group_by"
    15 => string(6) "having"
    16 => string(10) "and_having"
    17 => string(9) "or_having"
    18 => string(11) "having_open"
    19 => string(15) "and_having_open"
    20 => string(14) "or_having_open"
    21 => string(12) "having_close"
    22 => string(16) "and_having_close"
    23 => string(15) "or_having_close"
    24 => string(8) "order_by"
    25 => string(5) "limit"
    26 => string(6) "offset"
    27 => string(6) "cached"
    5405449521362 => bool TRUE
)

protected array $_db_pending

Database methods pending

protected bool $_db_reset

Reset builder

protected string $_foreign_key_suffix

Foreign key suffix

protected array $_has_many

Relationhips

protected array $_has_one

"Has one" relationships

protected array $_load_with

Relationships that should always be joined

protected bool $_loaded

protected array $_object

Current object

protected string $_object_name

Model name

protected string $_object_plural

Plural model name

protected string $_primary_key

Table primary key

protected mixed $_primary_key_value

Primary key value

protected static array $_properties

Members that have access methods

array(15) (
    0 => string(11) "object_name"
    1 => string(13) "object_plural"
    2 => string(6) "loaded"
    3 => string(5) "saved"
    4 => string(11) "primary_key"
    5 => string(10) "table_name"
    6 => string(13) "table_columns"
    7 => string(7) "has_one"
    8 => string(10) "belongs_to"
    9 => string(8) "has_many"
    10 => string(16) "has_many_through"
    11 => string(9) "load_with"
    12 => string(14) "updated_column"
    13 => string(14) "created_column"
    14 => string(10) "validation"
    5405449521362 => bool TRUE
)

protected bool $_reload_on_wakeup

Model configuration, reload on wakeup?

protected bool $_saved

protected array $_sorting

protected array $_table_columns

Table columns

protected string $_table_name

Table name

protected bool $_table_names_plural

Model configuration, table names plural?

protected string $_updated_column

Auto-update columns for updates

protected bool $_valid

protected Validation $_validation

Validation object created before saving/updating

protected array $_with_applied

With calls already applied

Methods

public complete_login( ) (defined in Model_Auth_User)

Complete the login for a user by incrementing the logins and saving login timestamp

Return Values

  • void

Source Code

public function complete_login()
{
	if ($this->_loaded)
	{
		// Update the number of logins
		$this->logins = new Database_Expression('logins + 1');

		// Set the last login date
		$this->last_login = time();

		// Save the user
		$this->update();
	}
}

public create_user( array $values , array $expected ) (defined in Model_Auth_User)

Create a new user

Example usage:

$user = ORM::factory('user')->create_user($_POST, array(
    'username',
    'password',
    'email',
);

Parameters

  • array $values required - $values
  • array $expected required - $expected

Tags

Source Code

public function create_user($values, $expected)
{
	// Validation for passwords
	$extra_validation = Model_User::get_password_validation($values)
		->rule('password', 'not_empty');

	return $this->values($values, $expected)->create($extra_validation);
}

public email_available( Validation $validation , string $field ) (defined in Model_Auth_User)

Does the reverse of unique_key_exists() by triggering error if email exists. Validation callback.

Parameters

  • Validation $validation required - Validation object
  • string $field required - Field name

Return Values

  • void

Source Code

public function email_available(Validation $validation, $field)
{
	if ($this->unique_key_exists($validation[$field], 'email'))
	{
		$validation->error($field, 'email_available', array($validation[$field]));
	}
}

public filters( ) (defined in Model_Auth_User)

Filters to run when data is set in this model. The password filter automatically hashes the password when it's set in the model.

Return Values

  • array - Filters

Source Code

public function filters()
{
	return array(
		'password' => array(
			array(array(Auth::instance(), 'hash'))
		)
	);
}

public static get_password_validation( array $values ) (defined in Model_Auth_User)

Password validation for plain passwords.

Parameters

  • array $values required - $values

Return Values

  • Validation

Source Code

public static function get_password_validation($values)
{
	return Validation::factory($values)
		->rule('password', 'min_length', array(':value', 8))
		->rule('password_confirm', 'matches', array(':validation', ':field', 'password'));
}

public labels( ) (defined in Model_Auth_User)

Labels for fields in this model

Return Values

  • array - Labels

Source Code

public function labels()
{
	return array(
		'username'         => 'username',
		'email'            => 'email address',
		'password'         => 'password',
	);
}

public rules( ) (defined in Model_Auth_User)

Rules for the user model. Because the password is always a hash when it's set,you need to run an additional not_empty rule in your controller to make sure you didn't hash an empty string. The password rules should be enforced outside the model or with a model helper method.

Return Values

  • array - Rules

Source Code

public function rules()
{
	return array(
		'username' => array(
			array('not_empty'),
			array('min_length', array(':value', 4)),
			array('max_length', array(':value', 32)),
			array('regex', array(':value', '/^[-\pL\pN_.]++$/uD')),
			array(array($this, 'username_available'), array(':validation', ':field')),
		),
		'password' => array(
			array('not_empty'),
		),
		'email' => array(
			array('not_empty'),
			array('min_length', array(':value', 4)),
			array('max_length', array(':value', 127)),
			array('email'),
			array(array($this, 'email_available'), array(':validation', ':field')),
		),
	);
}

public unique_key( string $value ) (defined in Model_Auth_User)

Allows a model use both email and username as unique identifiers for login

Parameters

  • string $value required - Unique value

Return Values

  • string - Field name

Source Code

public function unique_key($value)
{
	return Valid::email($value) ? 'email' : 'username';
}

public unique_key_exists( mixed $value [, string $field = NULL ] ) (defined in Model_Auth_User)

Tests if a unique key value exists in the database.

Parameters

  • mixed $value required - The value to test
  • string $field = NULL - Field name

Return Values

  • boolean

Source Code

public function unique_key_exists($value, $field = NULL)
{
	if ($field === NULL)
	{
		// Automatically determine field by looking at the value
		$field = $this->unique_key($value);
	}

	return (bool) DB::select(array('COUNT("*")', 'total_count'))
		->from($this->_table_name)
		->where($field, '=', $value)
		->where($this->_primary_key, '!=', $this->pk())
		->execute($this->_db)
		->get('total_count');
}

public update_user( array $values [, array $expected = NULL ] ) (defined in Model_Auth_User)

Update an existing user

We make the assumption that if a user does not supply a password, that they do not wish to update their password.

Example usage:

$user = ORM::factory('user')
    ->where('username', '=', 'kiall')
    ->find()
    ->update_user($_POST, array(
        'username',
        'password',
        'email',
    );

Parameters

  • array $values required - $values
  • array $expected = NULL - $expected

Tags

Source Code

public function update_user($values, $expected = NULL)
{
	if (empty($values['password']))
	{
		unset($values['password'], $values['password_confirm']);
	}

	// Validation for passwords
	$extra_validation = Model_User::get_password_validation($values);

	return $this->values($values, $expected)->update($extra_validation);
}

public username_available( Validation $validation , string $field ) (defined in Model_Auth_User)

Does the reverse of unique_key_exists() by triggering error if username exists. Validation callback.

Parameters

  • Validation $validation required - Validation object
  • string $field required - Field name

Return Values

  • void

Source Code

public function username_available(Validation $validation, $field)
{
	if ($this->unique_key_exists($validation[$field], 'username'))
	{
		$validation->error($field, 'username_available', array($validation[$field]));
	}
}

public __call( string $method , array $args ) (defined in Kohana_ORM)

Handles pass-through to database methods. Calls to query methods (query, get, insert, update) are not allowed. Query builder methods are chainable.

Parameters

  • string $method required - Method name
  • array $args required - Method arguments

Return Values

  • mixed

Source Code

public function __call($method, array $args)
{
	if (in_array($method, ORM::$_properties))
	{
		if ($method === 'validation')
		{
			if ( ! isset($this->_validation))
			{
				// Initialize the validation object
				$this->_validation();
			}
		}

		// Return the property
		return $this->{'_'.$method};
	}
	elseif (in_array($method, ORM::$_db_methods))
	{
		// Add pending database call which is executed after query type is determined
		$this->_db_pending[] = array('name' => $method, 'args' => $args);

		return $this;
	}
	else
	{
		throw new Kohana_Exception('Invalid method :method called in :class',
			array(':method' => $method, ':class' => get_class($this)));
	}
}

public __construct( [ mixed $id = NULL ] ) (defined in Kohana_ORM)

Constructs a new model and loads a record if given

Parameters

  • mixed $id = NULL - Parameter for find or object to load

Return Values

  • void

Source Code

public function __construct($id = NULL)
{
	$this->_initialize();

	if ($id !== NULL)
	{
		if (is_array($id))
		{
			foreach ($id as $column => $value)
			{
				// Passing an array of column => values
				$this->where($column, '=', $value);
			}

			$this->find();
		}
		else
		{
			// Passing the primary key
			$this->where($this->_table_name.'.'.$this->_primary_key, '=', $id)->find();
		}
	}
	elseif ( ! empty($this->_cast_data))
	{
		// Load preloaded data from a database call cast
		$this->_load_values($this->_cast_data);

		$this->_cast_data = array();
	}
}

public __get( string $column ) (defined in Kohana_ORM)

Handles retrieval of all model values, relationships, and metadata.

Parameters

  • string $column required - Column name

Return Values

  • mixed

Source Code

public function __get($column)
{
	if (array_key_exists($column, $this->_object))
	{
		return $this->_object[$column];
	}
	elseif (isset($this->_related[$column]))
	{
		// Return related model that has already been fetched
		return $this->_related[$column];
	}
	elseif (isset($this->_belongs_to[$column]))
	{
		$model = $this->_related($column);

		// Use this model's column and foreign model's primary key
		$col = $model->_table_name.'.'.$model->_primary_key;
		$val = $this->_object[$this->_belongs_to[$column]['foreign_key']];

		// Make sure we don't run WHERE "AUTO_INCREMENT column" = NULL queries. This would
		// return the last inserted record instead of an empty result.
		// See: http://mysql.localhost.net.ar/doc/refman/5.1/en/server-session-variables.html#sysvar_sql_auto_is_null
		if ($val !== NULL)
		{
			$model->where($col, '=', $val)->find();
		}

		return $this->_related[$column] = $model;
	}
	elseif (isset($this->_has_one[$column]))
	{
		$model = $this->_related($column);

		// Use this model's primary key value and foreign model's column
		$col = $model->_table_name.'.'.$this->_has_one[$column]['foreign_key'];
		$val = $this->pk();

		$model->where($col, '=', $val)->find();

		return $this->_related[$column] = $model;
	}
	elseif (isset($this->_has_many[$column]))
	{
		$model = ORM::factory($this->_has_many[$column]['model']);

		if (isset($this->_has_many[$column]['through']))
		{
			// Grab has_many "through" relationship table
			$through = $this->_has_many[$column]['through'];

			// Join on through model's target foreign key (far_key) and target model's primary key
			$join_col1 = $through.'.'.$this->_has_many[$column]['far_key'];
			$join_col2 = $model->_table_name.'.'.$model->_primary_key;

			$model->join($through)->on($join_col1, '=', $join_col2);

			// Through table's source foreign key (foreign_key) should be this model's primary key
			$col = $through.'.'.$this->_has_many[$column]['foreign_key'];
			$val = $this->pk();
		}
		else
		{
			// Simple has_many relationship, search where target model's foreign key is this model's primary key
			$col = $model->_table_name.'.'.$this->_has_many[$column]['foreign_key'];
			$val = $this->pk();
		}

		return $model->where($col, '=', $val);
	}
	else
	{
		throw new Kohana_Exception('The :property property does not exist in the :class class',
			array(':property' => $column, ':class' => get_class($this)));
	}
}

public __isset( string $column ) (defined in Kohana_ORM)

Checks if object data is set.

Parameters

  • string $column required - Column name

Return Values

  • boolean

Source Code

public function __isset($column)
{
	return (isset($this->_object[$column]) OR
		isset($this->_related[$column]) OR
		isset($this->_has_one[$column]) OR
		isset($this->_belongs_to[$column]) OR
		isset($this->_has_many[$column]));
}

public __set( string $column , mixed $value ) (defined in Kohana_ORM)

Base set method - this should not be overridden.

Parameters

  • string $column required - Column name
  • mixed $value required - Column value

Return Values

  • void

Source Code

public function __set($column, $value)
{
	if ( ! isset($this->_object_name))
	{
		// Object not yet constructed, so we're loading data from a database call cast
		$this->_cast_data[$column] = $value;
	}
	else
	{
		// Set the model's column to given value
		$this->set($column, $value);
	}
}

public __toString( ) (defined in Kohana_ORM)

Displays the primary key of a model when it is converted to a string.

Return Values

  • string

Source Code

public function __toString()
{
	return (string) $this->pk();
}

public __unset( string $column ) (defined in Kohana_ORM)

Unsets object data.

Parameters

  • string $column required - Column name

Return Values

  • void

Source Code

public function __unset($column)
{
	unset($this->_object[$column], $this->_changed[$column], $this->_related[$column]);
}

public add( string $alias , mixed $far_keys ) (defined in Kohana_ORM)

Adds a new relationship to between this model and another.

// Add the login role using a model instance
$model->add('roles', ORM::factory('role', array('name' => 'login')));
// Add the login role if you know the roles.id is 5
$model->add('roles', 5);
// Add multiple roles (for example, from checkboxes on a form)
$model->add('roles', array(1, 2, 3, 4));

Parameters

  • string $alias required - Alias of the has_many "through" relationship
  • mixed $far_keys required - Related model, primary key, or an array of primary keys

Return Values

  • ORM

Source Code

public function add($alias, $far_keys)
{
	$far_keys = ($far_keys instanceof ORM) ? $far_keys->pk() : $far_keys;

	$columns = array($this->_has_many[$alias]['foreign_key'], $this->_has_many[$alias]['far_key']);
	$foreign_key = $this->pk();

	$query = DB::insert($this->_has_many[$alias]['through'], $columns);

	foreach ( (array) $far_keys as $key)
	{
		$query->values(array($foreign_key, $key));
	}

	$query->execute($this->_db);

	return $this;
}

public as_array( ) (defined in Kohana_ORM)

Returns the values of this object as an array, including any related one-one models that have already been loaded using with()

Return Values

  • array

Source Code

public function as_array()
{
	$object = array();

	foreach ($this->_object as $column => $value)
	{
		// Call __get for any user processing
		$object[$column] = $this->__get($column);
	}

	foreach ($this->_related as $column => $model)
	{
		// Include any related objects that are already loaded
		$object[$column] = $model->as_array();
	}

	return $object;
}

public check( [ Validation $extra_validation = NULL ] ) (defined in Kohana_ORM)

Validates the current model's data

Parameters

  • Validation $extra_validation = NULL - Validation object

Return Values

  • ORM

Source Code

public function check(Validation $extra_validation = NULL)
{
	// Determine if any external validation failed
	$extra_errors = ($extra_validation AND ! $extra_validation->check());

	// Always build a new validation object
	$this->_validation();

	$array = $this->_validation;

	if (($this->_valid = $array->check()) === FALSE OR $extra_errors)
	{
		$exception = new ORM_Validation_Exception($this->_object_name, $array);

		if ($extra_errors)
		{
			// Merge any possible errors from the external object
			$exception->add_object('_external', $extra_validation);
		}
		throw $exception;
	}

	return $this;
}

public clear( ) (defined in Kohana_ORM)

Unloads the current object and clears the status.

Tags

  • Chainable -

Return Values

  • ORM

Source Code

public function clear()
{
	// Create an array with all the columns set to NULL
	$values = array_combine(array_keys($this->_table_columns), array_fill(0, count($this->_table_columns), NULL));

	// Replace the object and reset the object status
	$this->_object = $this->_changed = $this->_related = array();

	// Replace the current object with an empty one
	$this->_load_values($values);

	// Reset primary key
	$this->_primary_key_value = NULL;
	
	// Reset the loaded state
	$this->_loaded = FALSE;

	$this->reset();

	return $this;
}

public count_all( ) (defined in Kohana_ORM)

Count the number of records in the table.

Return Values

  • integer

Source Code

public function count_all()
{
	$selects = array();

	foreach ($this->_db_pending as $key => $method)
	{
		if ($method['name'] == 'select')
		{
			// Ignore any selected columns for now
			$selects[] = $method;
			unset($this->_db_pending[$key]);
		}
	}

	if ( ! empty($this->_load_with))
	{
		foreach ($this->_load_with as $alias)
		{
			// Bind relationship
			$this->with($alias);
		}
	}

	$this->_build(Database::SELECT);

	$records = $this->_db_builder->from($this->_table_name)
		->select(array('COUNT("*")', 'records_found'))
		->execute($this->_db)
		->get('records_found');

	// Add back in selected columns
	$this->_db_pending += $selects;

	$this->reset();

	// Return the total number of records in a table
	return $records;
}

public create( [ Validation $validation = NULL ] ) (defined in Kohana_ORM)

Insert a new object to the database

Parameters

  • Validation $validation = NULL - Validation object

Return Values

  • ORM

Source Code

public function create(Validation $validation = NULL)
{
	if ($this->_loaded)
		throw new Kohana_Exception('Cannot create :model model because it is already loaded.', array(':model' => $this->_object_name));

	// Require model validation before saving
	if ( ! $this->_valid OR $validation)
	{
		$this->check($validation);
	}

	$data = array();
	foreach ($this->_changed as $column)
	{
		// Generate list of column => values
		$data[$column] = $this->_object[$column];
	}

	if (is_array($this->_created_column))
	{
		// Fill the created column
		$column = $this->_created_column['column'];
		$format = $this->_created_column['format'];

		$data[$column] = $this->_object[$column] = ($format === TRUE) ? time() : date($format);
	}

	$result = DB::insert($this->_table_name)
		->columns(array_keys($data))
		->values(array_values($data))
		->execute($this->_db);

	if ( ! array_key_exists($this->_primary_key, $data))
	{
		// Load the insert id as the primary key if it was left out
		$this->_object[$this->_primary_key] = $this->_primary_key_value = $result[0];
	}

	if (empty($this->_primary_key_value))
	{
		// Set the primary key value if it was manually chosen by the user
		$this->_primary_key_value = $this->_object[$this->_primary_key];
	}

	// Object is now loaded and saved
	$this->_loaded = $this->_saved = TRUE;

	// All changes have been saved
	$this->_changed = array();

	return $this;
}

public delete( ) (defined in Kohana_ORM)

Deletes a single record while ignoring relationships.

Tags

  • Chainable -

Return Values

  • ORM

Source Code

public function delete()
{
	if ( ! $this->_loaded)
		throw new Kohana_Exception('Cannot delete :model model because it is not loaded.', array(':model' => $this->_object_name));

	// Use primary key value
	$id = $this->pk();

	// Delete the object
	DB::delete($this->_table_name)
		->where($this->_primary_key, '=', $id)
		->execute($this->_db);

	return $this->clear();
}

public static factory( string $model [, mixed $id = NULL ] ) (defined in Kohana_ORM)

Creates and returns a new model.

Parameters

  • string $model required - Model name
  • mixed $id = NULL - Parameter for find()

Tags

  • Chainable -

Return Values

  • ORM

Source Code

public static function factory($model, $id = NULL)
{
	// Set class name
	$model = 'Model_'.ucfirst($model);

	return new $model($id);
}

public find( ) (defined in Kohana_ORM)

Finds and loads a single database row into the object.

Tags

  • Chainable -

Return Values

  • ORM

Source Code

public function find()
{
	if ($this->_loaded)
		throw new Kohana_Exception('Method find() cannot be called on loaded objects');

	if ( ! empty($this->_load_with))
	{
		foreach ($this->_load_with as $alias)
		{
			// Bind auto relationships
			$this->with($alias);
		}
	}

	$this->_build(Database::SELECT);

	return $this->_load_result(FALSE);
}

public find_all( ) (defined in Kohana_ORM)

Finds multiple database rows and returns an iterator of the rows found.

Return Values

  • Database_Result

Source Code

public function find_all()
{
	if ($this->_loaded)
		throw new Kohana_Exception('Method find_all() cannot be called on loaded objects');

	if ( ! empty($this->_load_with))
	{
		foreach ($this->_load_with as $alias)
		{
			// Bind auto relationships
			$this->with($alias);
		}
	}

	$this->_build(Database::SELECT);

	return $this->_load_result(TRUE);
}

public has( string $alias , mixed $far_keys ) (defined in Kohana_ORM)

Tests if this object has a relationship to a different model, or an array of different models.

// Check if $model has the login role
$model->has('roles', ORM::factory('role', array('name' => 'login')));
// Check for the login role if you know the roles.id is 5
$model->has('roles', 5);
// Check for all of the following roles
$model->has('roles', array(1, 2, 3, 4));

Parameters

  • string $alias required - Alias of the has_many "through" relationship
  • mixed $far_keys required - Related model, primary key, or an array of primary keys

Return Values

  • Database_Result

Source Code

public function has($alias, $far_keys)
{
	$far_keys = ($far_keys instanceof ORM) ? $far_keys->pk() : $far_keys;

	// We need an array to simplify the logic
	$far_keys = (array) $far_keys;

	// Nothing to check if the model isn't loaded or we don't have any far_keys
	if ( ! $far_keys OR ! $this->_loaded)
		return FALSE;

	$count = (int) DB::select(array('COUNT("*")', 'records_found'))
		->from($this->_has_many[$alias]['through'])
		->where($this->_has_many[$alias]['foreign_key'], '=', $this->pk())
		->where($this->_has_many[$alias]['far_key'], 'IN', $far_keys)
		->execute($this->_db)->get('records_found');

	// Rows found need to match the rows searched
	return $count === count($far_keys);
}

public last_query( ) (defined in Kohana_ORM)

Returns last executed query

Return Values

  • string

Source Code

public function last_query()
{
	return $this->_db->last_query;
}

public list_columns( ) (defined in Kohana_ORM)

Proxy method to Database list_columns.

Return Values

  • array

Source Code

public function list_columns()
{
	// Proxy to database
	return $this->_db->list_columns($this->_table_name);
}

public pk( ) (defined in Kohana_ORM)

Returns the value of the primary key

Return Values

  • mixed - Primary key

Source Code

public function pk()
{
	return $this->_primary_key_value;
}

public reload( ) (defined in Kohana_ORM)

Reloads the current object from the database.

Tags

  • Chainable -

Return Values

  • ORM

Source Code

public function reload()
{
	$primary_key = $this->pk();

	// Replace the object and reset the object status
	$this->_object = $this->_changed = $this->_related = array();

	// Only reload the object if we have one to reload
	if ($this->_loaded)
		return $this->clear()
			->where($this->_table_name.'.'.$this->_primary_key, '=', $primary_key)
			->find();
	else
		return $this->clear();
}

public reload_columns( [ boolean $force = bool FALSE ] ) (defined in Kohana_ORM)

Reload column definitions.

Parameters

  • boolean $force = bool FALSE - Force reloading

Tags

  • Chainable -

Return Values

  • ORM

Source Code

public function reload_columns($force = FALSE)
{
	if ($force === TRUE OR empty($this->_table_columns))
	{
		if (isset(ORM::$_column_cache[$this->_object_name]))
		{
			// Use cached column information
			$this->_table_columns = ORM::$_column_cache[$this->_object_name];
		}
		else
		{
			// Grab column information from database
			$this->_table_columns = $this->list_columns();

			// Load column cache
			ORM::$_column_cache[$this->_object_name] = $this->_table_columns;
		}
	}

	return $this;
}

public remove( string $alias [, mixed $far_keys = NULL ] ) (defined in Kohana_ORM)

Removes a relationship between this model and another.

// Remove a role using a model instance
$model->remove('roles', ORM::factory('role', array('name' => 'login')));
// Remove the role knowing the primary key
$model->remove('roles', 5);
// Remove multiple roles (for example, from checkboxes on a form)
$model->remove('roles', array(1, 2, 3, 4));
// Remove all related roles
$model->remove('roles');

Parameters

  • string $alias required - Alias of the has_many "through" relationship
  • mixed $far_keys = NULL - Related model, primary key, or an array of primary keys

Return Values

  • ORM

Source Code

public function remove($alias, $far_keys = NULL)
{
	$far_keys = ($far_keys instanceof ORM) ? $far_keys->pk() : $far_keys;

	$query = DB::delete($this->_has_many[$alias]['through'])
		->where($this->_has_many[$alias]['foreign_key'], '=', $this->pk());

	if ($far_keys !== NULL)
	{
		// Remove all the relationships in the array
		$query->where($this->_has_many[$alias]['far_key'], 'IN', (array) $far_keys);
	}

	$query->execute($this->_db);

	return $this;
}

public reset( [ bool $next = bool TRUE ] ) (defined in Kohana_ORM)

Clears query builder. Passing FALSE is useful to keep the existing query conditions for another query.

Parameters

  • bool $next = bool TRUE - Pass FALSE to avoid resetting on the next call

Return Values

  • ORM

Source Code

public function reset($next = TRUE)
{
	if ($next AND $this->_db_reset)
	{
		$this->_db_pending   = array();
		$this->_db_applied   = array();
		$this->_db_builder   = NULL;
		$this->_with_applied = array();
	}

	// Reset on the next call?
	$this->_db_reset = $next;

	return $this;
}

public save( [ Validation $validation = NULL ] ) (defined in Kohana_ORM)

Updates or Creates the record depending on loaded()

Parameters

  • Validation $validation = NULL - Validation object

Tags

  • Chainable -

Return Values

  • ORM

Source Code

public function save(Validation $validation = NULL)
{
	return $this->loaded() ? $this->update($validation) : $this->create($validation);
}

public serialize( ) (defined in Kohana_ORM)

Allows serialization of only the object data and state, to prevent "stale" objects being unserialized, which also requires less memory.

Return Values

  • string

Source Code

public function serialize()
{
	// Store only information about the object
	foreach (array('_primary_key_value', '_object', '_changed', '_loaded', '_saved', '_sorting') as $var)
	{
		$data[$var] = $this->{$var};
	}

	return serialize($data);
}

public set( string $column , mixed $value ) (defined in Kohana_ORM)

Handles setting of column

Parameters

  • string $column required - Column name
  • mixed $value required - Column value

Return Values

  • void

Source Code

public function set($column, $value)
{
	if (array_key_exists($column, $this->_object))
	{
		// Filter the data
		$value = $this->run_filter($column, $value);

		// See if the data really changed
		if ($value !== $this->_object[$column])
		{
			$this->_object[$column] = $value;

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

			// Object is no longer saved or valid
			$this->_saved = $this->_valid = FALSE;
		}
	}
	elseif (isset($this->_belongs_to[$column]))
	{
		// Update related object itself
		$this->_related[$column] = $value;

		// Update the foreign key of this model
		$this->_object[$this->_belongs_to[$column]['foreign_key']] = $value->pk();

		$this->_changed[$column] = $this->_belongs_to[$column]['foreign_key'];
	}
	else
	{
		throw new Kohana_Exception('The :property: property does not exist in the :class: class',
			array(':property:' => $column, ':class:' => get_class($this)));
	}

	return $this;
}

public unserialize( string $data ) (defined in Kohana_ORM)

Prepares the database connection and reloads the object.

Parameters

  • string $data required - String for unserialization

Return Values

  • void

Source Code

public function unserialize($data)
{
	// Initialize model
	$this->_initialize();

	foreach (unserialize($data) as $name => $var)
	{
		$this->{$name} = $var;
	}

	if ($this->_reload_on_wakeup === TRUE)
	{
		// Reload the object
		$this->reload();
	}
}

public update( [ Validation $validation = NULL ] ) (defined in Kohana_ORM)

Updates a single record or multiple records

Parameters

  • Validation $validation = NULL - Validation object

Tags

  • Chainable -

Return Values

  • ORM

Source Code

public function update(Validation $validation = NULL)
{
	if ( ! $this->_loaded)
		throw new Kohana_Exception('Cannot update :model model because it is not loaded.', array(':model' => $this->_object_name));

	// Run validation if the model isn't valid or we have additional validation rules.
	if ( ! $this->_valid OR $validation)
	{
		$this->check($validation);
	}

	if (empty($this->_changed))
	{
		// Nothing to update
		return $this;
	}

	$data = array();
	foreach ($this->_changed as $column)
	{
		// Compile changed data
		$data[$column] = $this->_object[$column];
	}

	if (is_array($this->_updated_column))
	{
		// Fill the updated column
		$column = $this->_updated_column['column'];
		$format = $this->_updated_column['format'];

		$data[$column] = $this->_object[$column] = ($format === TRUE) ? time() : date($format);
	}

	// Use primary key value
	$id = $this->pk();

	// Update a single record
	DB::update($this->_table_name)
		->set($data)
		->where($this->_primary_key, '=', $id)
		->execute($this->_db);

	if (isset($data[$this->_primary_key]))
	{
		// Primary key was changed, reflect it
		$this->_primary_key_value = $data[$this->_primary_key];
	}

	// Object has been saved
	$this->_saved = TRUE;

	// All changes have been saved
	$this->_changed = array();

	return $this;
}

public values( array $values [, array $expected = NULL ] ) (defined in Kohana_ORM)

Set values from an array with support for one-one relationships. This method should be used for loading in post data, etc.

Parameters

  • array $values required - Array of column => val
  • array $expected = NULL - Array of keys to take from $values

Return Values

  • ORM

Source Code

public function values(array $values, array $expected = NULL)
{
	// Default to expecting everything except the primary key
	if ($expected === NULL)
	{
		$expected = array_keys($this->_table_columns);

		// Don't set the primary key by default
		unset($values[$this->_primary_key]);
	}

	foreach ($expected as $key => $column)
	{
		if (is_string($key))
		{
			// isset() fails when the value is NULL (we want it to pass)
			if ( ! array_key_exists($key, $values))
				continue;

			// Try to set values to a related model
			$this->{$key}->values($values[$key], $column);
		}
		else
		{
			// isset() fails when the value is NULL (we want it to pass)
			if ( ! array_key_exists($column, $values))
				continue;

			// Update the column, respects __set()
			$this->$column = $values[$column];
		}
	}

	return $this;
}

public with( string $target_path ) (defined in Kohana_ORM)

Binds another one-to-one object to this model. One-to-one objects can be nested using 'object1:object2' syntax

Parameters

  • string $target_path required - Target model to bind to

Return Values

  • void

Source Code

public function with($target_path)
{
	if (isset($this->_with_applied[$target_path]))
	{
		// Don't join anything already joined
		return $this;
	}

	// Split object parts
	$aliases = explode(':', $target_path);
	$target = $this;
	foreach ($aliases as $alias)
	{
		// Go down the line of objects to find the given target
		$parent = $target;
		$target = $parent->_related($alias);

		if ( ! $target)
		{
			// Can't find related object
			return $this;
		}
	}

	// Target alias is at the end
	$target_alias = $alias;

	// Pop-off top alias to get the parent path (user:photo:tag becomes user:photo - the parent table prefix)
	array_pop($aliases);
	$parent_path = implode(':', $aliases);

	if (empty($parent_path))
	{
		// Use this table name itself for the parent path
		$parent_path = $this->_table_name;
	}
	else
	{
		if ( ! isset($this->_with_applied[$parent_path]))
		{
			// If the parent path hasn't been joined yet, do it first (otherwise LEFT JOINs fail)
			$this->with($parent_path);
		}
	}

	// Add to with_applied to prevent duplicate joins
	$this->_with_applied[$target_path] = TRUE;

	// Use the keys of the empty object to determine the columns
	foreach (array_keys($target->_object) as $column)
	{
		$name = $target_path.'.'.$column;
		$alias = $target_path.':'.$column;

		// Add the prefix so that load_result can determine the relationship
		$this->select(array($name, $alias));
	}

	if (isset($parent->_belongs_to[$target_alias]))
	{
		// Parent belongs_to target, use target's primary key and parent's foreign key
		$join_col1 = $target_path.'.'.$target->_primary_key;
		$join_col2 = $parent_path.'.'.$parent->_belongs_to[$target_alias]['foreign_key'];
	}
	else
	{
		// Parent has_one target, use parent's primary key as target's foreign key
		$join_col1 = $parent_path.'.'.$parent->_primary_key;
		$join_col2 = $target_path.'.'.$parent->_has_one[$target_alias]['foreign_key'];
	}

	// Join the related object into the result
	$this->join(array($target->_table_name, $target_path), 'LEFT')->on($join_col1, '=', $join_col2);

	return $this;
}

protected _build( integer $type ) (defined in Kohana_ORM)

Initializes the Database Builder to given query type

Parameters

  • integer $type required - Type of Database query

Return Values

  • ORM

Source Code

protected function _build($type)
{
	// Construct new builder object based on query type
	switch ($type)
	{
		case Database::SELECT:
			$this->_db_builder = DB::select();
		break;
		case Database::UPDATE:
			$this->_db_builder = DB::update($this->_table_name);
		break;
		case Database::DELETE:
			$this->_db_builder = DB::delete($this->_table_name);
	}

	// Process pending database method calls
	foreach ($this->_db_pending as $method)
	{
		$name = $method['name'];
		$args = $method['args'];

		$this->_db_applied[$name] = $name;

		call_user_func_array(array($this->_db_builder, $name), $args);
	}

	return $this;
}

protected _build_select( ) (defined in Kohana_ORM)

Returns an array of columns to include in the select query. This method can be overridden to change the default select behavior.

Return Values

  • array - Columns to select

Source Code

protected function _build_select()
{
	$columns = array();

	foreach ($this->_table_columns as $column => $_)
	{
		$columns[] = array($this->_table_name.'.'.$column, $column);
	}

	return $columns;
}

protected _initialize( ) (defined in Kohana_ORM)

Prepares the model database connection, determines the table name, and loads column information.

Return Values

  • void

Source Code

protected function _initialize()
{
	// Set the object name and plural name
	$this->_object_name = strtolower(substr(get_class($this), 6));
	$this->_object_plural = Inflector::plural($this->_object_name);

	if ( ! is_object($this->_db))
	{
		// Get database instance
		$this->_db = Database::instance($this->_db_group);
	}

	if (empty($this->_table_name))
	{
		// Table name is the same as the object name
		$this->_table_name = $this->_object_name;

		if ($this->_table_names_plural === TRUE)
		{
			// Make the table name plural
			$this->_table_name = Inflector::plural($this->_table_name);
		}
	}

	foreach ($this->_belongs_to as $alias => $details)
	{
		$defaults['model'] = $alias;
		$defaults['foreign_key'] = $alias.$this->_foreign_key_suffix;

		$this->_belongs_to[$alias] = array_merge($defaults, $details);
	}

	foreach ($this->_has_one as $alias => $details)
	{
		$defaults['model'] = $alias;
		$defaults['foreign_key'] = $this->_object_name.$this->_foreign_key_suffix;

		$this->_has_one[$alias] = array_merge($defaults, $details);
	}

	foreach ($this->_has_many as $alias => $details)
	{
		$defaults['model'] = Inflector::singular($alias);
		$defaults['foreign_key'] = $this->_object_name.$this->_foreign_key_suffix;
		$defaults['through'] = NULL;
		$defaults['far_key'] = Inflector::singular($alias).$this->_foreign_key_suffix;

		$this->_has_many[$alias] = array_merge($defaults, $details);
	}

	// Load column information
	$this->reload_columns();

	// Clear initial model state
	$this->clear();
}

protected _load_result( [ bool $multiple = bool FALSE ] ) (defined in Kohana_ORM)

Loads a database result, either as a new record for this model, or as an iterator for multiple rows.

Parameters

  • bool $multiple = bool FALSE - Return an iterator or load a single row

Tags

  • Chainable -

Return Values

  • ORM|Database_Result

Source Code

protected function _load_result($multiple = FALSE)
{
	$this->_db_builder->from($this->_table_name);

	if ($multiple === FALSE)
	{
		// Only fetch 1 record
		$this->_db_builder->limit(1);
	}

	// Select all columns by default
	$this->_db_builder->select_array($this->_build_select());

	if ( ! isset($this->_db_applied['order_by']) AND ! empty($this->_sorting))
	{
		foreach ($this->_sorting as $column => $direction)
		{
			if (strpos($column, '.') === FALSE)
			{
				// Sorting column for use in JOINs
				$column = $this->_table_name.'.'.$column;
			}

			$this->_db_builder->order_by($column, $direction);
		}
	}

	if ($multiple === TRUE)
	{
		// Return database iterator casting to this object type
		$result = $this->_db_builder->as_object(get_class($this))->execute($this->_db);

		$this->reset();

		return $result;
	}
	else
	{
		// Load the result as an associative array
		$result = $this->_db_builder->as_assoc()->execute($this->_db);

		$this->reset();

		if ($result->count() === 1)
		{
			// Load object values
			$this->_load_values($result->current());
		}
		else
		{
			// Clear the object, nothing was found
			$this->clear();
		}

		return $this;
	}
}

protected _load_values( array $values ) (defined in Kohana_ORM)

Loads an array of values into into the current object.

Parameters

  • array $values required - Values to load

Tags

  • Chainable -

Return Values

  • ORM

Source Code

protected function _load_values(array $values)
{
	if (array_key_exists($this->_primary_key, $values))
	{
		if ($values[$this->_primary_key] !== NULL)
		{
			// Flag as loaded, saved, and valid
			$this->_loaded = $this->_saved = $this->_valid = TRUE;

			// Store primary key
			$this->_primary_key_value = $values[$this->_primary_key];
		}
		else
		{
			// Not loaded, saved, or valid
			$this->_loaded = $this->_saved = $this->_valid = FALSE;
		}
	}

	// Related objects
	$related = array();

	foreach ($values as $column => $value)
	{
		if (strpos($column, ':') === FALSE)
		{
			// Load the value to this model
			$this->_object[$column] = $value;
		}
		else
		{
			// Column belongs to a related model
			list ($prefix, $column) = explode(':', $column, 2);

			$related[$prefix][$column] = $value;
		}
	}

	if ( ! empty($related))
	{
		foreach ($related as $object => $values)
		{
			// Load the related objects with the values in the result
			$this->_related($object)->_load_values($values);
		}
	}

	return $this;
}

Returns an ORM model for the given one-one related alias

Parameters

  • string $alias required - Alias name

Return Values

  • ORM

Source Code

protected function _related($alias)
{
	if (isset($this->_related[$alias]))
	{
		return $this->_related[$alias];
	}
	elseif (isset($this->_has_one[$alias]))
	{
		return $this->_related[$alias] = ORM::factory($this->_has_one[$alias]['model']);
	}
	elseif (isset($this->_belongs_to[$alias]))
	{
		return $this->_related[$alias] = ORM::factory($this->_belongs_to[$alias]['model']);
	}
	else
	{
		return FALSE;
	}
}

protected _validation( ) (defined in Kohana_ORM)

Initializes validation rules, and labels

Return Values

  • void

Source Code

protected function _validation()
{
	// Build the validation object with its rules
	$this->_validation = Validation::factory($this->_object)
		->bind(':model', $this);

	foreach ($this->rules() as $field => $rules)
	{
		$this->_validation->rules($field, $rules);
	}

	// Use column names by default for labels
	$columns = array_keys($this->_table_columns);

	// Merge user-defined labels
	$labels = array_merge(array_combine($columns, $columns), $this->labels());

	foreach ($labels as $field => $label)
	{
		$this->_validation->label($field, $label);
	}
}

protected run_filter( string $field , string $value ) (defined in Kohana_ORM)

Filters a value for a specific column

Parameters

  • string $field required - The column name
  • string $value required - The value to filter

Return Values

  • string

Source Code

protected function run_filter($field, $value)
{
	$filters = $this->filters();

	// Get the filters for this column
	$wildcards = empty($filters[TRUE]) ? array() : $filters[TRUE];

	// Merge in the wildcards
	$filters = empty($filters[$field]) ? $wildcards : array_merge($wildcards, $filters[$field]);

	// Bind the field name and model so they can be used in the filter method
	$_bound = array
	(
		':field' => $field,
		':model' => $this,
	);

	foreach ($filters as $array)
	{
		// Value needs to be bound inside the loop so we are always using the
		// version that was modified by the filters that already ran
		$_bound[':value'] = $value;

		// Filters are defined as array($filter, $params)
		$filter = $array[0];
		$params = Arr::get($array, 1, array(':value'));

		foreach ($params as $key => $param)
		{
			if (is_string($param) AND array_key_exists($param, $_bound))
			{
				// Replace with bound value
				$params[$key] = $_bound[$param];
			}
		}

		if (is_array($filter) OR ! is_string($filter))
		{
			// This is either a callback as an array or a lambda
			$value = call_user_func_array($filter, $params);
		}
		elseif (strpos($filter, '::') === FALSE)
		{
			// Use a function call
			$function = new ReflectionFunction($filter);

			// Call $function($this[$field], $param, ...) with Reflection
			$value = $function->invokeArgs($params);
		}
		else
		{
			// Split the class and method of the rule
			list($class, $method) = explode('::', $filter, 2);

			// Use a static method call
			$method = new ReflectionMethod($class, $method);

			// Call $Class::$method($this[$field], $param, ...) with Reflection
			$value = $method->invokeArgs(NULL, $params);
		}
	}

	return $value;
}