waModel

Database management

Contents...

Correct calls of this class's methods is possible only for its subclasses (an app's or plugin's model classes), in which a valid value for class property $table containing the name of an existing table in framework's database is defined as shown below:

protected $table = 'table_name';
This limitation does not apply to the use of methods exec and query.

By default, database records are uniquely identified by the values of field named id. If a subclass of waModel should use a field with a different name for identifying database records, its name should be specified as the value of subclass property $id:

protected $id = 'product_id';

If more than one field is required for identifying database records, the names of all such fields should be specified as an array:

protected $id = array('product_id', 'order_id');

Methods

public function countAll()

Returns the number of records stored in the table.

Example

$model = new myappModel();
$model->countAll();

Result

156 //in the table whose name is specified in some model subclass named 'myappModel' there are 156 records

public function countByField ($field, $value = null)

Returns the number of records with the value of the specified field matching the specified value.

Parameters

Example

$model = new myappModel();
$model->countByField('name', 'John');

Result

12 //the table contains 12 records in which field 'name' contains value 'John'

public function deleteByField ($field, $value = null)

Deletes records with the value of the specified field matching the specified value.

Parameters

Example

$model = new myappModel();
$model->deleteByField('name', 'John');

Example

$model = new myappModel();
$model->deleteByField(array(
    'name', 'John',
    'age',  '24',
));

public function deleteById ($value)

Deletes the record with the value of the identifier field matching the specified value.

Parameters

Example

$model = new myappModel();
$model->deleteById(123); //method deletes the record in which the value of the identifier field (by default, it is 'id') is equal to 123

public function escape ($data, $type = null)

Prepares data for safe saving to the database.

Parameters

Пример

$model = new waModel();
$model->escape($data);

public function exec ($sql, $params = null)

Executes a SQL query without returning its result.

Parameters

Example

$model = new waModel();
$model->exec('INSERT INTO table_name (name) VALUES (?)', $customer_name); //the contents of $customer_name variable will be inserted instead of ?

Example

$model = new waModel();
$model->exec('UPDATE table_name SET name = ? WHERE id = ?', $name, $id); //the contents of variables $name and $id will be inserted instead of ? characters exactly in the same order in which these variables are specified as parameters of the exec method

Example

$model = new waModel();
$data = array(
    'name' => 'John',
    'id' => 25,
);
$model->exec('UPDATE table_name SET name = s:name WHERE id = i:id', $data); //the values of $data array items with keys 'name' and 'id' will be inserted into the SQL query instead of placeholders with appropriate names; their values will be converted into the data types specified for them, i.e. 'name'—string (s:), 'id'—integer (i:)

Example

$model = new waModel();
$data = array(
    'name' => 'John',
    'id' => 25,
);
$model->exec('UPDATE table_name SET name = :name WHERE id = i:id', $data); //for placeholder with name 'name', no data type is specified (:name), thus, its value extracted from the $data array will be treated as a string

public function fieldExists ($field)

Verifies whether the specified field exists in the table.

Parameters

Example

$model = new myappModel();
$model->fieldExists('extra_description');

public function getAll ($key = null, $normalize = false)

Returns table contents as an array each of its items being a subarray corresponding to one of table records.

Parameters

Examples for this method are based on the following sample data:

idnameage
1John25
2Mary26
3Bill25
4Michael19
5Jane26

Example

$model = new myappModel();
$model->getAll();

Result

Array
(
  0 => Array
  (
    id => '1'
    name => 'John'
    age => '25'
  )
  1 => Array
  (
    id => '2'
    name => 'Mary'
    age => '26'
  )
  2 => Array
  (
    id => '3'
    name => 'Bill'
    age => '25'
  )
  3 => Array
  (
    id => '4'
    name => 'Michael'
    age => '19'
  )
  4 => Array
  (
    id => '5'
    name => 'Jane'
    age => '26'
  )
)

Example

$model = new myappModel();
$model->getAll('id', 1); //element 'id' is removed from each subarray

Result

Array
(
  1 => Array
  (
    name => 'John'
    age => '25'
  )
  2 => Array
  (
    name => 'Mary'
    age => '26'
  )
  3 => Array
  (
    name => 'Bill'
    age => '25'
  )
  4 => Array
  (
    name => 'Michael'
    age => '19'
  )
  5 => Array
  (
    name => 'Jane'
    age => '26'
  )
)

Example

$model = new myappModel();
$model->getAll('age', 2); //values are grouped by the value of field 'age'

Result

Array
(
  25 => Array
  (
    0 => Array
    (
      id => '1'
      name => 'John'
    )
    1 => Array
    (
      id => '3'
      name => 'Bill'
    )
  )
  26 => Array
  (
    0 => Array
    (
      id => '2'
      name => 'Mary'
    )
    1 => Array
    (
      id => '5'
      name => 'Jane'
    )
  )
  19 => Array
  (
    0 => Array
    (
      id => '4'
      name => 'Michael'
    )
  )
)

public function getByField ($field, $value = null, $all = false, $limit = false)

Returns the contents of records with the value of the specified field matching the specified value. Method allows 2 modes of passing parameters: for one value and for multiple values.

Parameters (for one value)

Parameters (for multiple values)

Example

$model = new myappModel();
$model->getByField('age', 25, true, 10); //return the first 10 records in which the value of field 'age' is equal to 25

Example

$model = new myappModel();
$data = array(
    'age' => 25,
    'name' => 'John',
);
$model->getByField($data, true); //return all records with the specified field values

public function getById ($value)

Returns the contents of record with the value of the identifier field matching the specified value.

Parameters

Example

$model = new myappModel();
$model->getById(4);

public function getEmptyRow()

Returns an array corresponding to all table fields and containing their default values.

Example

$model = new myappModel();
$model->getEmptyRow();

Result

Array
(
  id => ''
  name => ''
  age => ''
)

public function getTableId()

Returns the name of the identifier field used by the model class.

Example

$model = new myappModel();
$model->getTableId();

Result

id //name of the identifier field which is by default used if a different field name is not defined in the model class

public function getTableName()

Returns the table name defined in the model class.

Example

$model = new myappModel();
$model->getTableName();

public function insert ($data, $type = 0)

Inserts a new record with specified values.

Parameters

Example

$model = new myappModel();
$data = array(
    'id' => 6,
    'age' => 25,
    'name' => 'John',
);
$model->insert($data, 1);

public function multipleInsert ($data)

Inserts several records with specified values.

Параметры (отдельно для каждой записи)

Example

$model = new myappModel();
$data = array(
    array(
        'name' => 'bag',
        'color' => 'red',
    ),
    array(
        'name' => 'bag',
        'color' => 'green',
    ),
    array(
        'name' => 'bag',
        'color' => 'blue',
    ),
);
$model->multipleInsert($data); //3 records corresponding to 3 array items will be inserted

Example

$model = new myappModel();
$data = array(
    'name' => 'bag',
    'color' => array(
        'red',
        'green',
        'blue',
    ),
);
$model->multipleInsert($data); //3 records corresponding to 3 values of the 'color' element will be inserted with the value of the 'name' field equal for all such records

public function ping()

Restores connection to the database management server in case of its failure.

Example

$model = new myappModel();
$model->ping();

public function query ($sql)

Executes a SQL query and returns its result as an instance of class waDbResultSelect, waDbResultInsert, waDbResultUpdate, waDbResultDelete, or waDbResultReplace. To access the result of a SQL query, call public methods of the class corresponding to the specific query type.

Parameters

Example

$model = new waModel();
$model->query('SELECT * FROM table_name')->fetchAll() //method fetchAll is available for accessing the results of a 'SELECT' query because it is described in the source code of class waDbResultSelect;
//this method returns a PHP array of values retrieved by the SQL query

public function replace ($data)

Replaces a table record using SQL operator REPLACE.

Parameters

Example

$model = new myappModel();
$data = array(
    array(
        'item_id' => 18,
        'order_id' => 984,
    ),
);
$model->replace($data);

public function updateByField ($field, $value, $data = null, $options = null, $return_object = false)

Updates the contents of records containing the specified field values. Several methods of passing parameters are acceptable:

Parameters (verifying values in one field)

Parameters (verifying values in several fields)

Example

$model = new myappModel();
$model->updateByField('name', 'John', array('name' => 'Johnny')); //in field 'name' value 'John' will be replaced with 'Johnny'

Example

$model = new myappModel();
$values = array(
    'John',
    'Johnny',
);
$data = array(
    'mood' => 'bright',
);
$model->updateByField('name', $values, $data); //for records where the value of field 'name' is equal to 'John' or 'Johnny', the value of field 'mood' will be replaced with 'bright'

Example

$model = new myappModel();
$fields = array(
    'name' => 'John',
    'age' => 25,
);
$data = array(
    'mood' => 'bright',
);
$model->updateByField($fields, $data); //for records where the value of field 'name' is equal to 'John' and the value of 'age' is equal to 25, set the value of field 'mood' to 'bright'

public function updateById ($id, $data, $options = null, $return_object = false)

Updates the contents of a table record with the identifier field value matching the specified value.

Parameters

Example

$model = new myappModel();
$data = array(
    'name' => 'John',
    'age' => 25,
);
$model->updateById(6, $data);