IModel

Interface for the data model classes.
Source
IModel.php
Extends
Iterator
Implementations
Model

Static Methods

getDbIndex

string IModel::getDbIndex(string group, string model)

Get a model's index used in the database views. Each model name is mapped to an index, this index is used instead of table name in the db views.

Arguments

    group (string)
    Model group name
    model (string)
    Model name

Returns

string
The model index used in views

midware

mixed IModel::midware(mixed value, array def, int type=0)

A midware can be set or each data property (setting "midware-classname" to the "midware" key in the property's definitions). A midware class may contain static methods "afterNext", "beforeStore" and "beforeQuery", when the event happens on the property the appropriate midware method (if exists) will be called passing property-value and using the returned value instead. This method is used internally to check for a midware, pass and get the values however it is left public to be freely used.

Since
Artaengine 1.2.0

Arguments

    value (mixed)
    Property value to be passed to the midware method
    def (array)
    Property definition
    type=0 (int)
    Mid-ware method to be called, 0=afterNext() 1=beforeStore() 2=beforeQuery()

Returns

mixed
The value returned by the midware

Methods

add

IModel $obj->add(bool exists=false)

Add model's data. Requires "commit()" to take effect on the database.

Arguments

    exists=false (bool)
    true=do not insert data if data exists

Returns

IModel
For method chaining

between

IModel $obj->between(int from=1, int to=10)

Limit query result between two rows including the rows themselves. e.g. "$model->between(5, 10)->query();"

Arguments

    from=1 (int)
    From row number (first row = 0)
    to=10 (int)
    To row number (first row = 0)

Returns

IModel
For method chaining

cancel

IModel $obj->cancel()

Cancel all uncommitted add/update/delete.

Returns

IModel
For method chaining

commit

bool $obj->commit(bool transaction=true)

Commit model data manipulations to the database. Actions add/update/delete are performed on the database only after calling this method.

Arguments

    transaction=true (bool)
    true=execute the SQLs in a database transaction, false=execute SQLs outside a transaction

Returns

bool
State of success

Throws

count

int $obj->count()

Number of queried data rows.

Returns

int
Number of rows

delete

IModel $obj->delete(string conditions=null, array | [mixed] conditionParams=null)

Delete model data. If model has dependencies, dependencies will be removed too. Requires "commit()" to take effect on the database. To delete data you have to either set model's key(pk) to a value that would mean "DELETE ... WHERE key=value" or pass conditions to this method manually.

Arguments

    conditions=null (string)
    The condition string.
    Conditions params may be used inside the string:
    
    Params from a list:
    "id = $1 AND (name = $2 OR name IN ($3))"
    
    Params from a dictionary:
    "id = $id AND (name = $name OR name IN ($names))"
    
    To address properties of IModel properties at any level.
    e.g. if Group and Permission are IModel classes:
    "Group.Permission.id = 5"
    
    conditionParams=null (array | [mixed])
    Condition params {param: val,} | [val,] | val1, val2,...
    When params are used inside the condition string, values for the params can be
    passed to this method as shown below. Values will be sanitized before being
    inserted into the condition string.
    
    List, passed as individual method arguments:
    5, 'Ronnie', ['James', 'Dio',]
    
    Dictionary, passed as one array argument:
    {'id': 5, 'name': 'Ronnie', 'names': ['James', 'Dio',],}
    

Returns

IModel
For method chaining

extendWhere

IModel $obj->extendWhere(
    string conditions=null,
    array | [mixed] conditionParams=null
)

Add conditions for querying data. Adds to previously set conditions.

Arguments

    conditions=null (string)
    The condition string.
    Conditions params may be used inside the string:
    
    Params from a list:
    "id = $1 AND (name = $2 OR name IN ($3))"
    
    Params from a dictionary:
    "id = $id AND (name = $name OR name IN ($names))"
    
    To address properties of IModel properties at any level.
    e.g. if Group and Permission are IModel classes:
    "Group.Permission.id = 5"
    
    conditionParams=null (array | [mixed])
    Condition params {param: val,} | [val,] | val1, val2,...
    When params are used inside the condition string, values for the params can be
    passed to this method as shown below. Values will be sanitized before being
    inserted into the condition string.
    
    List, passed as individual method arguments:
    5, 'Ronnie', ['James', 'Dio',]
    
    Dictionary, passed as one array argument:
    {'id': 5, 'name': 'Ronnie', 'names': ['James', 'Dio',],}
    

Returns

IModel
For method chaining

getLabel

string $obj->getLabel(string pm)

Get the appropriate label for a data-property, method or object-path relative to the current model instance. Always use this method to get a label instead of going other ways. This method traverses the object-path and returns the first label found for it. Object-path e.g. "User.Group.name.".

Since
Artaengine 1.2.2

Arguments

    pm (string)
    Model property-name, method-name or object-path to get label for

Returns

string
The label

keyVal

mixed|array $obj->keyVal(bool newKey=true)

Get the value of model's key property and set the value to the property.
if model's key property is already set to a value return it.
if model's key property is serial(auto inc) and newKey=true return the last inserted value
query the model based on set property values and set conditions and return the key values(s)

Arguments

    newKey=true (bool)
    true=if key type is SERIAL return the last inserted key value

Returns

mixed|array
Value or an array of values (if a query is done and result has more than one rows)

limit

IModel $obj->limit(int limit=10, int $offset=0)

Limit query result the same way as SQL LIMIT OFFSET. e.g. "$model->limit(20, 21)->query();"

Arguments

    limit=10 (int)
    Max number of rows to query
    $offset=0 (int)
    Row offset to start from (first row = 0)

Returns

IModel
For method chaining

present

array|string $obj->present(string sep=null)

Get the data of model's presenter property(s). Each model can be presented by one or more properties. Presenting means when in a form or table a list or column is going to show a model's data as an object of another model then which property(s)'s data must be displayed.

Arguments

    sep=null (string)
    Separator. string=return a string of data glued with this string

Returns

array|string
{property-name: data,} | "data" or "data1SEPdata2SEPdata3"

properties

array $obj->properties()

Get a list of model data properties.

Returns

array
[property-name,]

propertyDefs

mixed $obj->propertyDefs(string property=null, string key=null, string default=null)

Get a dictionary of all model data properties and their definitions. Arguments can be passed to filter the result.

Arguments

    property=null (string)
    null=return all, property-name=only return info for this property
    key=null (string)
    Return the value of a certain key in property's definition array
    default=null (string)
    If key not exists in the array then return this value instead

Returns

mixed
not-array=value of a property definition key, array=

query

IModel $obj->query(string view=Model::QUERY_FULL)

Queries data from the database to be filled into the model.

Arguments

    view=Model::QUERY_FULL (string)
    The database view can be "Model::QUERY_SELF" or "Model::QUERY_FULL" "Model::QUERY_L1"

Returns

IModel
For method chaining

reset

IModel $obj->reset(string | int keyVal=null)

Reset model instancing state.

Arguments

    keyVal=null (string | int)
    If provided, after resetting the model's key property will be set to this value

Returns

IModel
For method chaining

setLocale

IModel $obj->setLocale(string | array | [string] locale=null)

Set model locale(s). A data property will be localized if "i18n" is set to true in it's definition. Query and actions on this properties will be locale aware. By default the model locale is set to user's selected LOCALE, you can manually change it with this method. If you set an array of locales then the data will be queried for all those locales. Same thing is valid for other actions. All app's available locales="Arta::$globals['locales']", users locale="LOCALE".

Arguments

    locale=null (string | array | [string])
    Locale(s) e.g. "en-US", "fa-IR"

Returns

IModel
For method chaining

slice

IModel $obj->slice(array configs)

Slice query result into pages. Use this for querying a paging and producing paging links. e.g. "$model->slice($configs)->query();". After query get paging links from. "$model->__page__->render();"

Arguments

    configs (array)
    Paging configs
    {
        int    page      : 1
            current page number,
        string url       : CURRENT_URL
            URL to be used for paging links,
        const  link      : Paging::LINK_QUERY
            paging link type,
        string key       : Paging::URL_KEY=page
            the key to be used in query string or URL to assign page number
            to it. e.g ?page=2 or url/page/2,
        int    max_rows  : Paging::MAX_ROWS
            max number of rows per page,
        int    max_links : Paging::MAX_LINKS
            number of links to show previous and next to the current page link.
            e.g. 6 = 2|3|4(5)6|7|8,
        int    count     :
            the total data row count,
        bool   abstract  : false
            the raw output shape. false=return a verbose array true=return a
            short and simple array,
        string js        : Arta.pageList(Paging::PAGE)
            if link=LINK_JS then you can set the JavaScript function for
            paging link clicks to this key. "Paging::PAGE" and "Paging::URL"
            strings can be used in the value and will be replaced by their
            real values in the paging links,
        const style      : Paging::LINK_NOM
            render setting - the paging links text display style e.g.
            "Paging::LINK_FROM_TO"=[1-10][11-20][21-30] or
            "Paging::LINK_NOM"=[1][2][3],
        string next      : _(next)
            render setting - text label for the "next" link,
        string previous  : _(prev)
            render setting - text label for the "previous" link,
        string first     : _(first)
            render setting - text label for the "first" link,
        string last      : _(last)
            render setting - text label for the "last" link,
        string tag       : li
            render setting - link container tags,
        string info      : _(Paging::FROM - Paging::TO / Paging::COUNT)
            render setting - template for the extra info being shown beside
            the links. "Paging::FROM", "Paging::TO" and "Paging::COUNT" will
            be replaced with their real values. set to null to disable
            this feature,
        string infopos   : right
            render setting - the place to show the extra info
            may be "right or "left" to the paging links,
        string midware   : null
            render setting - name of a static class method as "Class::method"
            all the link labels will be passed to this method and the
            returned value  will be used instead. this can be useful to
            customize the label texts,
        string leftbox   : null
            render setting - a custom string to be placed left to the links,
        string rightbox  : null
            render setting - a custom string to be placed right to the links,
    }
    

Returns

IModel
For method chaining

sort

IModel $obj->sort([string] properties)

Sort query data by property names. e.g. "$model->sort('Group.id ASC', 'id DESC')->query();"

Arguments

    properties ([string])
    Can be name of a model's data property e.g. "name" or if a property is an IModel object then the name of the model and it's property to sort on e.g. "Group.id" and so on... "ASC" and "DESC" may be added to each item

Returns

IModel
For method chaining

top

IModel $obj->top(int top=10)

Limit query result to the first n rows. e.g. "$model->top(10)->query();"

Arguments

    top=10 (int)
    Top n rows

Returns

IModel
For method chaining

translateToSql

string $obj->translateToSql(string str, bool useTable=false)

Translate Model codition to database SQL condition. Mostly for internal uses only.

Arguments

    str (string)
    Model condition
    useTable=false (bool)
    false=use views, true=use tables

Returns

string
Database query-able SQL condition string

update

IModel $obj->update(string conditions=null, array | [mixed] conditionParams=null)

Update model's data. Requires "commit()" to take effect on the database. To update data you have to either set model's key(pk) to a value that would mean "UPDATE ... WHERE key=value" or pass conditions to this method manually.

Arguments

    conditions=null (string)
    The condition string.
    Conditions params may be used inside the string:
    
    Params from a list:
    "id = $1 AND (name = $2 OR name IN ($3))"
    
    Params from a dictionary:
    "id = $id AND (name = $name OR name IN ($names))"
    
    To address properties of IModel properties at any level.
    e.g. if Group and Permission are IModel classes:
    "Group.Permission.id = 5"
    
    conditionParams=null (array | [mixed])
    Condition params {param: val,} | [val,] | val1, val2,...
    When params are used inside the condition string, values for the params can be
    passed to this method as shown below. Values will be sanitized before being
    inserted into the condition string.
    
    List, passed as individual method arguments:
    5, 'Ronnie', ['James', 'Dio',]
    
    Dictionary, passed as one array argument:
    {'id': 5, 'name': 'Ronnie', 'names': ['James', 'Dio',],}
    

Returns

IModel
For method chaining

where

IModel $obj->where(string conditions=null, array | [mixed] conditionParams=null)

Set conditions for querying data. Removed previously set conditions.

Arguments

    conditions=null (string)
    The condition string.
    Conditions params may be used inside the string:
    
    Params from a list:
    "id = $1 AND (name = $2 OR name IN ($3))"
    
    Params from a dictionary:
    "id = $id AND (name = $name OR name IN ($names))"
    
    To address properties of IModel properties at any level.
    e.g. if Group and Permission are IModel classes:
    "Group.Permission.id = 5"
    
    conditionParams=null (array | [mixed])
    Condition params {param: val,} | [val,] | val1, val2,...
    When params are used inside the condition string, values for the params can be
    passed to this method as shown below. Values will be sanitized before being
    inserted into the condition string.
    
    List, passed as individual method arguments:
    5, 'Ronnie', ['James', 'Dio',]
    
    Dictionary, passed as one array argument:
    {'id': 5, 'name': 'Ronnie', 'names': ['James', 'Dio',],}
    

Returns

IModel
For method chaining