PHP Class SQL_Model, atk4

Inheritance: extends Model, implements Serializable
Show file Open project: atk4/atk4 Class Usage Examples

Public Properties

Property Type Description
$db DB Set to use different database connection
$debug boolean Call $model->debug(true|false) to turn on|off debug mode
$entity_code
$fast boolean Set this to true to speed up model, but sacrifice some of the consistency
$field_class string Default Field class name
$relations array Joins
$table_alias string This will help to keep SQL syntax shorter, but will not impact functionality.

Protected Properties

Property Type Description
$_iterating boolean | DB_dsql False: finished iterating. True, reset not yet fetched. Object=DSQL
$dsql DB_dsql For low level use only. Use $this->dsql() when in doubt.

Public Methods

Method Description
__clone ( ) Clone DSQL
__construct ( $options = [] ) Initialization of ID field, which must always be defined
_dsql ( ) : DB_dsql Use this instead of accessing dsql directly.
_preexec ( )
_ref ( $ref, $class, $field, $val )
_refBind ( $field_in, $expression, $field_out = null ) Strange method. Uses undefined $field variable, undefined refBind() method etc.
addCache ( $controller, $table = null, $priority = 5 )
addCondition ( mixed $field, mixed $cond = UNDEFINED, mixed $value = UNDEFINED, DB_dsql $dsql = null ) Adds "WHERE" condition / conditions in underlying DSQL.
addExpression ( string $name, mixed $expression = null ) : DB_dsql Adds and returns SQL-calculated expression as a read-only field.
addField ( string $name, string $actual_field = null ) : Field Adds field to model
containsMany ( $field, $model ) Defines multiple contained models for field
containsOne ( $field, $model ) Defines contained model for field
count ( string $alias = null ) : DB_dsql Returns dynamic query selecting number of entries in the database.
current ( )
debug ( boolean $enabled = true ) Turns debugging mode on|off for this model. All database operations will be outputed.
delete ( $id = null ) Deletes record matching the ID
deleteAll ( ) Deletes all records matching this model. Use with caution.
dsql ( ) : DB_dsql Produces a clone of Dynamic SQL object configured with table, conditions and joins of this model.
each ( $callable )
exception ( ) exception() will automatically add information about current model and will allow to turn on "debug" mode
fieldQuery ( $field ) Return query for a specific field. All other fields are ommitted.
get ( $name = null )
getActualFields ( $group = UNDEFINED )
getBy ( $field, $cond = UNDEFINED, $value = UNDEFINED ) Loads data record and return array of that data. Will not affect currently loaded record.
getField ( $f )
getRef ( $name, $load = null )
getRows ( $fields = null ) Loads all matching data into array of hashes
hasField ( $name )
hasMany ( $model, $their_field = null, $our_field = null, $as_field = null ) Defines many to one association
hasOne ( $model, $our_field = null, $display_field = null, $as_field = null ) Defines one to many association
init ( )
initQuery ( ) Initializes base query for this model.
isDirty ( $name )
isInstanceLoaded ( )
join ( $foreign_table, $master_field = null, $join_kind = null, $_foreign_alias = null, $relation = null ) Constructs model from multiple tables.
key ( )
leftJoin ( $foreign_table, $master_field = null, $join_kind = null, $_foreign_alias = null, $relation = null ) Creates weak join between tables.
load ( $id ) Loads record specified by ID.
loadAny ( ) Loads the first matching record from the model
loadBy ( $field, $cond = UNDEFINED, $value = UNDEFINED ) Similar to loadAny() but will apply condition before loading.
loadData ( $id = null )
loadRandom ( )
newField ( $name )
next ( )
offsetExists ( $name )
offsetGet ( $name )
offsetSet ( $name, $val )
offsetUnset ( $name )
ref ( $name, $load = null ) Traverses references. Use field name for hasOne() relations. Use model name for hasMany()
refSQL ( $name, $load = null ) Returns Model with SQL join usable for subqueries.
reset ( )
rewind ( ) {{{ Iterator support
save ( ) Save model into database and load it back.
saveAndUnload ( ) Save model into database and don't try to load it back
saveAs ( $model ) Save model into database and try to load it back as a new model of specified class.
selectQuery ( array $fields = null ) : DB_dsql Completes initialization of dsql() by adding fields and expressions.
serialize ( )
set ( $name, $value = UNDEFINED ) Override all methods to keep back-compatible
setActualFields ( array $fields )
setDirty ( $name )
setLimit ( $count, $offset = null ) Sets limit on query
setMasterField ( $field, $value )
setOrder ( $field, $desc = null ) Sets an order on the field. Field must be properly defined
setSource ( $controller, $table = null, $id = null )
sum ( string | array | Field $field ) : DB_dsql Returns dynamic query selecting sum of particular field or fields.
titleQuery ( ) Returns query which selects title field
tryDelete ( $id = null ) Tries to delete record, but does nothing if not found
tryLoad ( $id ) Try to load a record by specified ID. Will not raise exception if record is not found
tryLoadAny ( ) Try to load a matching record for the model. Will not raise exception if no records are found
tryLoadBy ( $field, $cond = UNDEFINED, $value = UNDEFINED ) Attempt to load using a specified condition, but will not fail if such record is not found
tryLoadRandom ( ) Loads random entry into model
unload ( ) forget currently loaded record and it's ID. Will not affect database
unserialize ( $data )
update ( $data = [] )
valid ( )

Protected Methods

Method Description
_load ( $id, $ignore_missing = false ) Internal loading funciton. Do not use. OK to override.

Private Methods

Method Description
insert ( ) Internal function which performs insert of data. Use save() instead. OK to override.
modify ( ) Internal function which performs modification of existing data. Use save() instead. OK to override.

Method Details

__clone() public method

Clone DSQL
public __clone ( )

__construct() public method

Initialization of ID field, which must always be defined
public __construct ( $options = [] )

_dsql() public method

This will initialize $dsql property if it does not exist yet.
public _dsql ( ) : DB_dsql
return DB_dsql

_load() protected method

Internal loading funciton. Do not use. OK to override.
protected _load ( $id, $ignore_missing = false )

_preexec() public method

public _preexec ( )

_ref() public method

public _ref ( $ref, $class, $field, $val )

_refBind() public method

https://github.com/atk4/atk4/issues/711
public _refBind ( $field_in, $expression, $field_out = null )

addCache() public method

public addCache ( $controller, $table = null, $priority = 5 )

addCondition() public method

It tries to be smart about where and how the field is defined. $field can be passed as: - string (field name in this model) - Field object - DSQL expression - array (see note below) $cond can be passed as: - string ('=', '>', '<=', etc.) - value can be passed here, then it's used as $value with condition '=' $value can be passed as: - string, integer, boolean or any other simple data type - Field object - DSQL expreession NOTE: $field can be passed as array of conditions. Then all conditions will be joined with OR using DSQLs orExpr method. For example, $model->addCondition(array( array('profit', '=', null), array('profit', '<', 1000), )); will generate "WHERE profit is null OR profit < 1000" EXAMPLES: you can pass [dsql, dsql, dsql ...] and this will be treated as (dsql OR dsql OR dsql) ... you can pass [[field,cond,value], [field,cond,value], ...] and this will be treated as (field=value OR field=value OR ...) BTW, you can mix these too :) [[field,cond,value], dsql, [field,cond,value], ...] will become (field=value OR dsql OR field=value) Value also can be DSQL expression, so following will work nicely: [dsql,'>',dsql] will become (dsql > dsql) [dsql, dsql] will become (dsql = dsql) [field, cond, dsql] will become (field = dsql)
public addCondition ( mixed $field, mixed $cond = UNDEFINED, mixed $value = UNDEFINED, DB_dsql $dsql = null )
$field mixed Field for comparing or array of conditions
$cond mixed Condition
$value mixed Value for comparing
$dsql DB_dsql DSQL object to which conditions will be added

addExpression() public method

See Field_Expression class.
public addExpression ( string $name, mixed $expression = null ) : DB_dsql
$name string
$expression mixed
return DB_dsql

addField() public method

Adds field to model
public addField ( string $name, string $actual_field = null ) : Field
$name string
$actual_field string
return Field

containsMany() public method

Defines multiple contained models for field
public containsMany ( $field, $model )

containsOne() public method

Defines contained model for field
public containsOne ( $field, $model )

count() public method

Returns dynamic query selecting number of entries in the database.
public count ( string $alias = null ) : DB_dsql
$alias string Optional alias of count expression
return DB_dsql

current() public method

public current ( )

debug() public method

Turns debugging mode on|off for this model. All database operations will be outputed.
public debug ( boolean $enabled = true )
$enabled boolean

delete() public method

Deletes record matching the ID
public delete ( $id = null )

deleteAll() public method

Deletes all records matching this model. Use with caution.
public deleteAll ( )

dsql() public method

Use for statements you are going to execute manually.
public dsql ( ) : DB_dsql
return DB_dsql

each() public method

public each ( $callable )

exception() public method

exception() will automatically add information about current model and will allow to turn on "debug" mode
public exception ( )

fieldQuery() public method

Return query for a specific field. All other fields are ommitted.
public fieldQuery ( $field )

get() public method

public get ( $name = null )

getActualFields() public method

public getActualFields ( $group = UNDEFINED )

getBy() public method

Loads data record and return array of that data. Will not affect currently loaded record.
public getBy ( $field, $cond = UNDEFINED, $value = UNDEFINED )

getField() public method

public getField ( $f )

getRef() public method

public getRef ( $name, $load = null )

getRows() public method

Loads all matching data into array of hashes
public getRows ( $fields = null )

hasField() public method

public hasField ( $name )

hasMany() public method

Defines many to one association
public hasMany ( $model, $their_field = null, $our_field = null, $as_field = null )

hasOne() public method

Defines one to many association
public hasOne ( $model, $our_field = null, $display_field = null, $as_field = null )

init() public method

public init ( )

initQuery() public method

Initializes base query for this model.
public initQuery ( )

isDirty() public method

public isDirty ( $name )

isInstanceLoaded() public method

public isInstanceLoaded ( )

join() public method

Queries will join tables, inserts, updates and deletes will be applied on both tables
public join ( $foreign_table, $master_field = null, $join_kind = null, $_foreign_alias = null, $relation = null )

key() public method

public key ( )

leftJoin() public method

The foreign table may be absent and will not be automatically deleted.
public leftJoin ( $foreign_table, $master_field = null, $join_kind = null, $_foreign_alias = null, $relation = null )

load() public method

Loads record specified by ID.
public load ( $id )

loadAny() public method

Loads the first matching record from the model
public loadAny ( )

loadBy() public method

Condition is temporary. Fails if record is not loaded.
public loadBy ( $field, $cond = UNDEFINED, $value = UNDEFINED )

loadData() public method

Deprecation: 4.3.3 Backward-compatible. Will attempt to load but will not fail
public loadData ( $id = null )

loadRandom() public method

public loadRandom ( )

newField() public method

public newField ( $name )

next() public method

public next ( )

offsetExists() public method

public offsetExists ( $name )

offsetGet() public method

public offsetGet ( $name )

offsetSet() public method

public offsetSet ( $name, $val )

offsetUnset() public method

public offsetUnset ( $name )

ref() public method

Traverses references. Use field name for hasOne() relations. Use model name for hasMany()
public ref ( $name, $load = null )

refSQL() public method

Returns Model with SQL join usable for subqueries.
public refSQL ( $name, $load = null )

reset() public method

public reset ( )

rewind() public method

{{{ Iterator support
public rewind ( )

save() public method

If for some reason it won't load, whole operation is undone.
public save ( )

saveAndUnload() public method

Save model into database and don't try to load it back
public saveAndUnload ( )

saveAs() public method

Instance of new class is returned.
public saveAs ( $model )

selectQuery() public method

Completes initialization of dsql() by adding fields and expressions.
public selectQuery ( array $fields = null ) : DB_dsql
$fields array
return DB_dsql

serialize() public method

public serialize ( )

set() public method

Override all methods to keep back-compatible
public set ( $name, $value = UNDEFINED )

setActualFields() public method

public setActualFields ( array $fields )
$fields array

setDirty() public method

public setDirty ( $name )

setLimit() public method

Sets limit on query
public setLimit ( $count, $offset = null )

setMasterField() public method

Deprecation: use two-argument addCondition. Always keep $field equals to $value for queries and new data
public setMasterField ( $field, $value )

setOrder() public method

Sets an order on the field. Field must be properly defined
public setOrder ( $field, $desc = null )

setSource() public method

public setSource ( $controller, $table = null, $id = null )

sum() public method

Returns dynamic query selecting sum of particular field or fields.
public sum ( string | array | Field $field ) : DB_dsql
$field string | array | Field
return DB_dsql

titleQuery() public method

Returns query which selects title field
public titleQuery ( )

tryDelete() public method

Tries to delete record, but does nothing if not found
public tryDelete ( $id = null )

tryLoad() public method

Try to load a record by specified ID. Will not raise exception if record is not found
public tryLoad ( $id )

tryLoadAny() public method

Try to load a matching record for the model. Will not raise exception if no records are found
public tryLoadAny ( )

tryLoadBy() public method

Attempt to load using a specified condition, but will not fail if such record is not found
public tryLoadBy ( $field, $cond = UNDEFINED, $value = UNDEFINED )

tryLoadRandom() public method

Loads random entry into model
public tryLoadRandom ( )

unload() public method

forget currently loaded record and it's ID. Will not affect database
public unload ( )

unserialize() public method

public unserialize ( $data )

update() public method

Deprecation: 4.3.1 Use set() then save().
public update ( $data = [] )

valid() public method

public valid ( )

Property Details

$_iterating protected property

False: finished iterating. True, reset not yet fetched. Object=DSQL
protected bool|DB_dsql $_iterating
return boolean | DB_dsql

$db public property

Set to use different database connection
public DB $db
return DB

$debug public property

Call $model->debug(true|false) to turn on|off debug mode
public bool $debug
return boolean

$dsql protected property

For low level use only. Use $this->dsql() when in doubt.
protected DB_dsql $dsql
return DB_dsql

$entity_code public property

Deprecation: 4.3.0 Use $table instead
public $entity_code

$fast public property

Set this to true to speed up model, but sacrifice some of the consistency
public bool $fast
return boolean

$field_class public property

Default Field class name
public string $field_class
return string

$relations public property

Joins
public array $relations
return array

$table_alias public property

This will help to keep SQL syntax shorter, but will not impact functionality.
public string $table_alias
return string